How to use the checkout action in GitHub Actions

In GitHub Actions, the jobs defined in a workflow are executed in a runner, which is a virtual machine. In order to build, test, or deploy the code, the runners need to access the code. This is where the actions/checkout action comes in. This action checks out a GitHub repository so that the runners can execute the defined jobs.

What is actions/checkout

GitHub automatically sets the $GITHUB_WORKSPACE environment variable to the runner's working directory, and by default, the directory is empty. The actions/checkout action clones the GitHub repo to $GITHUB_WORKSPACE to accomplish various jobs, such as building, testing, and deploying the code. By default, this action clones the repo where the workflow is defined, but it can be configured to clone any GitHub repo. If the workflow is triggered by an event, such as a push or pull_request, then this action checks out the particular commit corresponding to that event. Otherwise, the default branch, such as main or master, is checked out.

How to use actions/checkout

To use actions/checkout, you need to define a step using this action with the uses key, just like any action. Following is an example of a workflow that checks out the current repository when a pull request is made and executes the tests:

name: Run tests
on:
  pull_request:

jobs:
  tag:
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v4
	- name: Run test
  	run: |
    	make test

Note: You can check the GitHub repo to find the latest version of the action.

Configuring actions/checkout

You can customize the behavior of the action by passing parameters using the with key. Some of the options that you can use are as follows:

• repository: Use this to check out a repository, and use this in the format owner/repo. The default is ${{ github.repository }}.
• ref: Use this to check out a branch, tag, or commit Secure Hash Algorithm (SHA). If an event triggers the workflow, the corresponding SHA is used; otherwise, the default branch is used.
• token: Use this to configure your action with a token with permissions to fetch the repository. For example, you can use your personal access token (PAT). The default is ${{ github.token }}.
• path: Use this to specify the relative path under $GITHUB_WORKSPACE where the repository is fetched.
• fetch-depth: Use this to specify the number of commits to fetch. By default, only one commit is fetched. You can use 0 to fetch all commits and history for all branches and tags.

You can see the list of all parameters in the GitHub repo.

Use cases for actions/checkout

There are many different use cases and scenarios where the actions/checkout action can come in handy. Following are some example code snippets for different use cases:

Fetch the current repository

You can use actions/checkout without any parameters to check out the current repo:

- uses: actions/checkout@v4

Check out a different branch

The ref parameter can be used to check out a different branch of the current repo. It can be a branch name, tag, or commit SHA:

- uses: actions/checkout@v4
  with:
	ref: some-branch

Check out a different repo

The repository key can be used for checking out a different repo:

uses: actions/checkout@v4
  with:
	repository: my-org/my-other-repo

Check out a private repo

If a repo is private, you must pass a PAT with the correct permission in order to check out the repo:

uses: actions/checkout@v4
  with:
	repository: my-org/my-other-repo
	token: ${{ secrets.PAT }} # `PAT` is a secret that contains the token

Note: If your current repo is private, you don't need to pass the token parameter as it defaults to ${{ github.token }}, which is scoped to the current repo. But the token is mandatory if you want to check out any other private repo.

Check out multiple repos in different paths

You can use actions/checkout as many times as you want to clone multiple repos. Be sure to pass the path parameter so that the repos are cloned in different directories:

# Current repo
- name: Checkout
  uses: actions/checkout@v4

# Other repo
- name: Checkout other repo
  uses: actions/checkout@v4
  with:
	repository: my-org/my-other-repo
	path: other-repo # Store in $GITHUB_WORKSPACE/other-repo