GitHub Actions Checkout Action: actions/checkout
actions/checkoutThe GitHub Actions checkout action (actions/checkout) is the official step that clones your repository into a workflow runner so the rest of your job can build, test, or deploy it. It's the near-universal first line of a GitHub Actions workflow — a `uses: actions/checkout@v4` step that pulls your code onto the runner, with inputs for how much history, which ref, and which credentials come along.
Reach for it — the GitHub Actions checkout action is the default first step in almost any workflow, and the real decisions aren't whether to use it but which options you set: fetch-depth, submodules, token handling, and version pinning. There's rarely a reason to hand-roll `git clone`, since this action already handles auth, workspace cleanup, and the detached-HEAD edge cases for you.
The problem it solves
A GitHub Actions runner starts empty — your repository isn't on it. Before you can run tests or a build, something has to fetch the code, wire up credentials so `git push` works, and clean the workspace between runs. Doing that by hand with `git clone` means juggling the `GITHUB_TOKEN`, detached-HEAD states, and post-job cleanup yourself. This action exists to make that first step a single line.
What is it?
The GitHub Actions checkout action is the official action (actions/checkout) that clones your repository into a workflow runner under `$GITHUB_WORKSPACE`, so later steps can access your code. By default it fetches a single commit — the ref or SHA that triggered the workflow — and persists an auth token in the local git config so your scripts can run authenticated git commands; that token is removed during post-job cleanup. It's written in TypeScript, MIT-licensed, and maintained by GitHub itself.
Why it's getting attention
It's less trending than foundational — at 8.4k stars, actions/checkout is one of the most-used GitHub Actions in existence, sitting at the top of essentially every workflow file. Recent movement is about security: the README says v7 now refuses to check out fork pull-request code by default under `pull_request_target` and `workflow_run` (a common 'pwn request' vector), v6 moved persisted credentials out of `.git/config` into `$RUNNER_TEMP`, and v5 moved to the node24 runtime.
Key features
- ✓Fetch-depth control: `fetch-depth: 0` pulls full history for all branches and tags; the default of 1 grabs only the triggering commit
- ✓Submodule support via `submodules: true` or `recursive` to check out nested repositories
- ✓Sparse checkout through `sparse-checkout` (with cone mode) and partial clone via `filter`, to fetch only the paths you need
- ✓Git-LFS support with `lfs: true` for large files
- ✓Token and SSH auth: persists the `GITHUB_TOKEN` (or a PAT, or an `ssh-key`) in git config for authenticated commands, then removes it post-job
- ✓Multi-repo checkout using `path` and `repository` to place several repositories side by side or nested on the runner
- ✓A `ref` input to check out any branch, tag, or SHA instead of the default event ref
Best use cases
- •The first step of almost any CI job — getting your code onto the runner before building, testing, or linting
- •Fetching full git history with `fetch-depth: 0` for tools that need it, like semantic-release or `git describe`
- •Checking out a second repository (private tools, shared config) alongside your main repo in one workflow
- •Sparse or single-file checkouts to speed up jobs that only touch part of a large monorepo
- •Pushing a commit back from a workflow using the built-in token — e.g. a bot that generates and commits files
How to install / try
There's nothing to install — it's a GitHub Action referenced directly in a workflow YAML file. Add a step with `uses: actions/checkout@v4`, pinning to a major-version tag (or a full commit SHA for stricter supply-chain safety). The GitHub Actions checkout action is MIT-licensed and maintained by GitHub; v7 is the current major, though `@v4` remains the most widely pinned. It runs on GitHub-hosted and self-hosted runners.
How to use
In a workflow file, the checkout step goes first: ```yaml - uses: actions/checkout@v4 ``` That clones the ref that triggered the run. To fetch all history and tags: ```yaml - uses: actions/checkout@v4 with: fetch-depth: 0 ``` To check out a second repository into a subdirectory: ```yaml - uses: actions/checkout@v4 with: repository: my-org/my-tools path: my-tools ``` The README recommends setting `permissions: contents: read` for the `GITHUB_TOKEN` unless you provide your own `token` or `ssh-key`.
Strengths
- ✓One line replaces a pile of `git clone` plumbing — auth, workspace cleanup, and detached-HEAD handling included
- ✓Maintained by GitHub, so it tracks runner and Node-runtime changes and receives security fixes
- ✓Sensible option surface: fetch-depth, submodules, LFS, sparse checkout, and multi-repo layouts are all inputs, not hand-written scripts
- ✓Post-job cleanup removes the persisted token automatically, so credentials don't linger on the runner
- ✓MIT-licensed and open source, so you can read exactly what it does before trusting it with your token
Limitations & risks
- △GitHub Actions-only — it's a workflow action, with no use outside a GitHub Actions (or compatible) runner
- △The default `fetch-depth: 1` catches people out: a shallow checkout has no tags and no history, so tools that call `git log`, `git describe`, or diff against a base branch fail until you set `fetch-depth: 0`
- △Version pinning is a genuine decision — pinning `@v4` trusts a moving tag; strict supply-chain setups pin the full commit SHA, which then needs manual updates
- △By default it persists a credential for authenticated git commands (`persist-credentials: true`); set it to `false` if you don't want a token available to later steps
- △The README states GitHub is not currently accepting contributions to this repo, so external feature PRs won't be merged — only bug reports and security fixes
Alternatives
Who should try it — and who should skip
Anyone writing a GitHub Actions workflow. If your job touches your repository's code at all — build, test, lint, release — the checkout action is the step that puts the code on the runner. The only people who skip it are those running a job that genuinely needs no source (a pure API call, or a container image that already ships the code), or who have a specific reason to script `git clone` by hand.
Frequently asked questions
actions/checkout is the official GitHub Action that clones your repository onto the workflow runner under `$GITHUB_WORKSPACE`, so later steps can build, test, or deploy your code. It's the standard first step in a GitHub Actions workflow.
Only if a step needs your repository's files. A job that just calls an API or runs a prebuilt image can skip it, but any build, test, or lint job needs the code on the runner first.
By default the action fetches only the single triggering commit (`fetch-depth: 1`). Set `fetch-depth: 0` to pull full history and tags for tools like `git describe` or semantic-release.
`@v4` is a major-version tag and receives patch updates automatically. Pinning the full commit SHA is stricter for supply-chain safety but means you update it by hand. v7 is the current major version.
Yes. It's open source under the MIT License and maintained by GitHub; using it costs nothing beyond your normal GitHub Actions minutes.