How to Use the actions/checkout Action in GitHub Actions Workflows

The actions/checkout action clones your repository into $GITHUB_WORKSPACE using configurable inputs defined in action.yml and orchestrated through src/main.ts, supporting sparse checkouts, LFS, submodules, and cross-repository authentication.

The actions/checkout repository is the official JavaScript-based composite action that handles repository checkouts in GitHub Actions workflows. According to the actions/checkout source code, it normalizes inputs, validates security constraints, and executes Git commands to make your code available to subsequent workflow steps. Understanding its implementation helps you optimize fetch performance and secure your CI/CD pipelines.

How the actions/checkout Action Works

Architecture Overview

The action consists of several TypeScript modules that handle specific responsibilities:

Component	Role	Source File
action.yml	Declares inputs, defaults, and the entry point script that the runner executes.	action.yml
src/main.ts	Entry point that orchestrates the checkout process by invoking input parsing and Git operations.	src/main.ts
src/input-helper.ts	Parses and validates all with: inputs, normalizes repository names, and constructs the IGitSourceSettings object.	src/input-helper.ts
src/git-source-provider.ts	Executes concrete Git commands including git init, git fetch, git checkout, and handles sparse-checkout configurations.	src/git-source-provider.ts
src/unsafe-pr-checkout-helper.ts	Implements security guards that block checkouts from forked pull requests unless explicitly allowed.	src/unsafe-pr-checkout-helper.ts

Execution Flow

The checkout process follows a strict sequence implemented in the source code:

1. Input Parsing – The getInputs() function in src/input-helper.ts reads workflow parameters, applies defaults (such as clean: true and fetch-depth: 1), and validates the repository reference.

2. Safety Validation – The system checks the allow-unsafe-pr-checkout flag against the pull request origin to prevent "pull-request-target" attacks from forked repositories.

3. Git Environment Setup – src/git-source-provider.ts creates a fresh work-tree under $GITHUB_WORKSPACE/<path> and configures authentication tokens or SSH keys in the local Git config.

4. Fetching Code – Based on fetch-depth, filter, fetch-tags, lfs, and submodules settings, the action executes optimized git fetch commands to minimize bandwidth and time.

5. Checkout and Sparse Configuration – The requested ref (branch, tag, SHA, or PR head) is checked out. If sparse-checkout is enabled, the action configures git sparse-checkout before fetching to limit downloaded data.

6. Credential Cleanup – Unless persist-credentials: false is set, the temporary token is removed from the Git config during the action’s post-step to prevent credential leakage.

Common Usage Patterns for actions/checkout

Minimal Checkout

Use this pattern to check out the current repository at the triggering commit:

- uses: actions/checkout@v7

Checkout Specific Branches or Tags

Target a specific reference by using the ref input parameter:

- uses: actions/checkout@v7
  with:
    ref: my-branch

Replace my-branch with any tag name (e.g., v1.2.3) or commit SHA.

Fetch Full Git History

By default, the action performs a shallow clone (fetch-depth: 1). For commands requiring complete history like git log or git describe, fetch all commits:

- uses: actions/checkout@v7
  with:
    fetch-depth: 0

Sparse Checkout for Large Repositories

Download only specific files or directories to reduce fetch time and disk usage:

- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      README.md
      src/
    sparse-checkout-cone-mode: false

Set sparse-checkout-cone-mode: false when listing individual files rather than directory patterns.

Enable Git LFS

For repositories using Large File Storage, add the lfs flag:

- uses: actions/checkout@v7
  with:
    lfs: true

Checkout Submodules

Fetch nested dependencies recursively:

- uses: actions/checkout@v7
  with:
    submodules: recursive

Access Private Repositories

Checkout a different repository using a Personal Access Token (PAT) with appropriate scopes:

- uses: actions/checkout@v7
  with:
    repository: my-org/private-repo
    token: ${{ secrets.PAT }}

Checkout Pull Request Head Commit

Access the actual PR head SHA instead of the merge commit:

- uses: actions/checkout@v7
  with:
    ref: ${{ github.event.pull_request.head.sha }}

Security Considerations for actions/checkout

The action includes protections against unsafe pull request checkouts. By default, src/unsafe-pr-checkout-helper.ts prevents checking out code from forked repositories when the workflow is triggered by pull_request_target events.

Only enable unsafe checkouts after reviewing the security implications:

- uses: actions/checkout@v7
  with:
    allow-unsafe-pr-checkout: true

This bypasses the safety check implemented in src/unsafe-pr-checkout-helper.ts and should only be used when you explicitly trust the forked code.

Summary

• actions/checkout is a JavaScript composite action that clones repositories into $GITHUB_WORKSPACE using configurations defined in action.yml.
• The execution flow involves src/input-helper.ts for parsing, src/unsafe-pr-checkout-helper.ts for security validation, and src/git-source-provider.ts for Git operations.
• Use fetch-depth: 0 for full history, sparse-checkout for partial clones, and lfs: true for Large File Storage support.
• Always protect against unsafe PR checkouts unless explicitly requiring forked code access.

Frequently Asked Questions

What is the default fetch depth for actions/checkout?

By default, actions/checkout uses fetch-depth: 1, which performs a shallow clone containing only the latest commit. This minimizes checkout time and disk usage. Change this to 0 in your workflow configuration to fetch the complete history when running commands like git describe or git log.

How do I checkout a different repository using actions/checkout?

Specify the repository input using the owner/repo format and provide authentication via the token input. For private repositories, use a Personal Access Token (PAT) stored in GitHub Secrets. The src/input-helper.ts module resolves the repository name and configures the authentication token in the Git config before fetching.

Why is my sparse checkout not working correctly?

Ensure you set sparse-checkout-cone-mode: false when listing individual files rather than directory patterns. According to the implementation in src/git-source-provider.ts, the action configures git sparse-checkout before fetching, so incorrect cone mode settings will cause the sparse patterns to fail silently or fetch unintended files.

Is it safe to use allow-unsafe-pr-checkout in production?

Only use allow-unsafe-pr-checkout: true after thoroughly reviewing the security implications. The src/unsafe-pr-checkout-helper.ts file contains logic that blocks checkouts from forked pull requests to prevent attackers from exfiltrating secrets or modifying your codebase. Only enable this flag when you explicitly need to test code from forks and have implemented additional security controls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}