actions/checkout

Check out your repository so a workflow can access its code.

Official actionCategory: Source & CheckoutLatest v4View on GitHub

What it does

actions/checkout is the first step in almost every workflow. It clones your repository into the runner workspace ($GITHUB_WORKSPACE) so subsequent steps can compile, test, and read files.

By default it makes a shallow clone of only the commit that triggered the run (fetch-depth: 1) and checks out a detached HEAD. That is fine for most builds but breaks tools that need full history.

Usage

workflow (.yml)

steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0   # full history: needed for git describe, changed-files, release notes

Inputs

Input	Description	Default	Required
`repository`	Repository to check out.	`current repo`	No
`ref`	Branch, tag, or SHA to check out.	`triggering ref`	No
`token`	Token used to fetch the repo.	`GITHUB_TOKEN`	No
`fetch-depth`	Number of commits to fetch. 0 fetches all history and tags.	`1`	No
`submodules`	Check out submodules: false, true, or recursive.	`false`	No
`persist-credentials`	Write the token to .git/config for later git commands.	`true`	No
`path`	Relative directory to check out into.	`workspace root`	No
`lfs`	Download Git LFS files.	`false`	No

Notes

A detached HEAD is expected. If a step needs the branch name, read it from github.ref_name rather than git rev-parse.

Common errors

fatal: not a git repository usually means a git command ran in a job before checkout. Make actions/checkout the first step.
Tools that need history (git describe, changelog generators, changed-files) fail on the default shallow clone. Set fetch-depth: 0.
A later push step failing with a permission error often means persist-credentials was disabled or the job lacks contents: write.

Security and pinning

checkout is an official GitHub action, but still pin it to a full commit SHA (actions/checkout@<sha> # v4) so a moved tag cannot change what runs in your pipeline.
persist-credentials: true (the default) writes the GITHUB_TOKEN into .git/config. If later steps run untrusted code, set it to false.

Frequently asked questions

Do I need actions/checkout in every workflow?

Only when a job reads your repository files. Jobs that just call an API or deploy a prebuilt artifact may not need it.

Why is my build in a detached HEAD state?

That is normal. checkout checks out the exact commit that triggered the run, not a branch. Use github.ref_name for the branch name.

References

GitHub Actions documentation