GitHub Tutorial for Beginners: A Researcher’s First Repository

This GitHub tutorial for beginners walks through a researcher’s first repository: create it, change a file on a branch, merge it through a pull request, and run a first GitHub Actions workflow. Along the way it shows how the same steps keep analysis scripts, data-cleaning code and manuscript source under version control. The menu names and commands below follow the current GitHub Docs and the Pro Git book (checked 2026-10-29).

What GitHub and Git are used for in research

Git is a version control system that tracks changes to files. GitHub is a platform for building software that stores Git projects, called repositories, in the cloud (GitHub Docs, “About GitHub and Git”). For a researcher, a repository is a folder of analysis scripts, notebooks or manuscript source whose every saved state can be listed, compared and recovered.

Git “thinks about its data more like a stream of snapshots” (Pro Git, “What is Git?”). Each time you commit, Git records a snapshot of the files you staged. That is what makes it useful for a paper: you can say exactly which version of the code produced which table. For datasets rather than code, see versioning research datasets.

The three states every file moves through

Pro Git describes three states for a file in a Git project:

• Modified: you have changed the file but have not committed it.
• Staged: you have marked a modified file in its current version to go into your next commit snapshot.
• Committed: the data is safely stored in your local database.

These map to three sections of a Git project: the working tree, the staging area and the Git directory. Most operations in Git need only local files and resources, so you can commit offline and upload later.

Install or access (official source only)

Git itself is installed from the official site, git-scm.com; the Pro Git book is the reference for the commands below. GitHub is used in the browser at github.com. The first tutorial below needs only a browser; the command-line part needs Git installed locally.

Once Git is installed, set your identity once. Every Git commit uses this information, and it is “immutably baked into the commits you start creating”:

git config --global user.name "John Doe"
git config --global user.email [email protected]

With --global you do this only once per computer. Run the commands without --global inside a project to override the values for that project only (Pro Git, “First-Time Git Setup”).

Step-by-step: your first repository, branch, commit and pull request

These steps follow GitHub’s “Hello World” tutorial, performed entirely in the browser.

1. Create a repository. In the upper-right corner, click “+” (Create something new), then “New repository”. Enter hello-world as the “Repository name”, add a “Description”, choose “Public” or “Private”, select “Add a README file”, then click “Create repository”.
2. Create a branch. On the “Code” tab, open the branch dropdown (it shows “main”), type readme-edits, and choose “Create branch: readme-edits from main”.
3. Make and commit a change. With the readme-edits branch selected, open README.md, click the pencil icon (“Edit file”), make a change, click “Commit changes”, enter a commit message, and click “Commit changes” again.
4. Open a pull request. Go to the “Pull requests” tab and click “New pull request”. Choose readme-edits to compare with main, review the diff, click “Create pull request”, enter a title and description, and click “Create pull request” once more. GitHub’s tutorial calls pull requests “the heart of collaboration on GitHub”.
5. Merge it. Click “Merge pull request”, then “Confirm merge”, then “Delete branch”.

The same cycle on the command line

To put an existing project folder under version control, go to the folder and run git init. This creates a .git subdirectory; at that point nothing in the project is tracked yet. Then track files and make the first commit (Pro Git, “Getting a Git Repository”):

git add *.c
git add LICENSE
git commit -m 'Initial project version'

In that example *.c and LICENSE stand for the files you want tracked; for a research project they would be your scripts and your license file. To get a copy of an existing repository instead, use git clone, which pulls down every version of every file in the project history by default.

A file you change is “modified” until you stage it with git add, and only staged versions go into the next commit snapshot.

Your first GitHub Actions workflow

GitHub Actions runs a workflow file from your repository when an event such as a push occurs. This is how a repository can re-run a check each time you commit. The steps follow GitHub’s Actions quickstart.

1. In your repository, click “Add file”, then “Create new file”, and name it .github/workflows/github-actions-demo.yml. Typing that path creates the .github and workflows folders and the file in one step. GitHub finds workflows only in .github/workflows, and the file name must end in .yml or .yaml.
2. Paste the workflow from the quickstart. Its first lines are:

   name: GitHub Actions Demo
   run-name: ${{ github.actor }} is testing out GitHub Actions 🚀
   on: [push]
   jobs:
     Explore-GitHub-Actions:
       runs-on: ubuntu-latest
       steps:
         - name: Check out repository code
           uses: actions/checkout@v6

   The quickstart’s file continues with further run steps that print details about the event and list the files in the repository.

3. Click “Commit changes”. Committing the workflow file to a branch in your repository triggers the push event and runs your workflow. A pull request is not required.

Reading the workflow, line by line

• name is the workflow name shown in the Actions tab.
• on: [push] says the workflow runs on every push.
• jobs holds one job, Explore-GitHub-Actions, which runs-on: ubuntu-latest.
• uses: actions/checkout@v6 copies your repository onto the runner so later steps can read your files.

Output and how to read it

• Commit history. Each commit you make on GitHub appears in the repository with its message; a pull request shows the diff between the branch and main before you merge.
• Pull request diff. The Compare page shows the changes between your branch and main before you create the pull request.
• Actions log. Open the “Actions” tab, click “GitHub Actions Demo” in the left sidebar, click the run, open “Jobs”, choose “Explore-GitHub-Actions”, and expand the steps to read each one’s output.

Troubleshooting

• The Actions tab is missing. Per the quickstart, Actions may be disabled for the repository.
• A change is not in my commit. A commit records the staged versions of files, so run git add on the file before git commit.
• The workflow file never runs. Check that it sits in .github/workflows and ends in .yml or .yaml.

From repository to citable archive

A repository on GitHub is not by itself a permanent, citable record. GitHub’s documentation on referencing and citing content describes archiving with Zenodo: the repository must be public (“Zenodo can only access public repositories”) and should include a license. You log in to Zenodo with “Log in with GitHub”, choose “Authorize zenodo”, open the Zenodo GitHub page and switch the repository to On. After that, “Zenodo archives your repository and issues a new DOI each time you create a new GitHub release.” See the Zenodo repository guide, how to cite software, code and R packages, and the CITATION.cff entry.

Add a README explaining how to run the code; the README template is a starting point. Version-controlled code that others can re-run supports computational reproducibility.

Related tools

Tool	What it is, per its own documentation
Git	A version control system that tracks changes to files; works on local files and resources.
GitHub	A platform for building software that stores Git repositories in the cloud and hosts pull requests and GitHub Actions.
Zenodo	Archives a public GitHub repository and issues a new DOI for each GitHub release once enabled.

For how GitHub differs from other Git hosting services, see Git vs GitHub vs GitLab.

FAQ

Where do I start with a GitHub beginner tutorial?

Start with the browser-based “Hello World” steps above: create a repository, a branch, a commit and a pull request. They need no installation.

What is a GitHub Actions tutorial in one sentence?

Create a .github/workflows/github-actions-demo.yml file, commit it, and open the Actions tab to read the run log; the commit itself triggers the push event.

Do I need a pull request to run a GitHub Actions workflow?

No. Committing the workflow file to a branch triggers the push event, and the quickstart says a pull request is not necessary.

Can I use Git without an internet connection?

Yes for local work. Most Git operations need only local files and resources, so you can commit offline and upload later.

Is Git the same as GitHub?

No. Git is the version control system; GitHub is a platform that hosts Git repositories in the cloud.

Sources

• GitHub Docs, “Hello World”: docs.github.com/en/get-started/start-your-journey/hello-world (checked 2026-10-29).
• GitHub Docs, “Quickstart for GitHub Actions”: docs.github.com/en/actions/get-started/quickstart (checked 2026-10-29).
• GitHub Docs, “About GitHub and Git”: docs.github.com/en/get-started/start-your-journey/about-github-and-git (checked 2026-10-29).
• GitHub Docs, “Referencing and citing content”: docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content (checked 2026-10-29).
• Pro Git, “What is Git?”, “Getting a Git Repository”, “First-Time Git Setup”: git-scm.com/book/en/v2 (checked 2026-10-29).