How to use the checkout action in GitHub Actions

Greg Foster
Greg Foster
Graphite software engineer

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.

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.

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:

Terminal
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.

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.

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:

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

Terminal
- uses: actions/checkout@v4

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:

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

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

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

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

Terminal
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.

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:

Terminal
# 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

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2