What Information Is Provided in the actions/checkout README? A Complete Guide

The actions/checkout README provides comprehensive documentation for GitHub's official checkout action, including version history, security configurations, input parameters, usage scenarios, and credential handling patterns.

The actions/checkout repository hosts the official GitHub Action that clones your repository into the workflow workspace. The README.md file serves as the primary user-facing documentation, detailing everything from basic usage to advanced security patterns. Understanding the structure of this documentation helps developers implement secure, efficient CI/CD pipelines.

Overview of the actions/checkout README Structure

The README organizes content into distinct sections that cover versioning, security policies, and practical implementation guides.

Version History and Release Notes

The documentation outlines major changes across versions v7, v6, v5, and v4. Each version section summarizes critical updates:

• v7: Introduces security improvements that block unsafe fork PR checkouts by default
• v6: Migration to ESM (ECMAScript Modules) and updated runtime requirements
• v5: Enhanced credential handling and performance optimizations
• v4: Default fetch-depth behavior and token persistence changes

These sections help users migrate between versions and understand breaking changes that affect workflow security.

Security Notices and Contribution Guidelines

The README explicitly states that the repository is not currently accepting external contributions. Users seeking support are directed to official GitHub support channels rather than opening pull requests. This policy protects the integrity of a critical infrastructure component used by millions of workflows.

Core Functionality and Configuration Options

The documentation explains how the action interacts with the Git environment and the various inputs available for customization.

Default Behavior and Workspace Setup

According to the source code in src/main.ts, the action checks out the repository under $GITHUB_WORKSPACE by default. The README clarifies that:

• The default fetch-depth is 1 (shallow checkout)
• Credentials are automatically persisted in the local Git config
• The action supports both HTTPS and SSH authentication protocols

Input Parameters and Advanced Settings

The src/input-helper.ts file defines all supported inputs, which the README documents with practical examples:

• repository: Specify a different repository to checkout
• ref: Target a specific branch, tag, or SHA
• token: Authentication token for private repositories
• ssh-key: Private SSH key for SSH authentication
• fetch-depth: Number of commits to fetch (0 for full history)
• sparse-checkout: Cone mode patterns for partial repository clones
• submodules: Control whether to checkout submodules
• lfs: Enable Git Large File Storage support
• persist-credentials: Boolean to retain credentials after the job completes

Security Features and Credential Management

The README emphasizes security-first configurations implemented in src/unsafe-pr-checkout-helper.ts and src/git-auth-helper.ts.

Unsafe PR Checkout Protection (v7+)

Starting with v7, the action refuses to checkout code from forked PRs when the workflow runs under pull_request_target or workflow_run events. To override this protection, users must explicitly set:

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

This mitigation prevents "pwn request" attacks where malicious code in a fork could compromise the base repository.

Token Persistence and Cleanup

The src/git-auth-helper.ts implementation writes authentication tokens to the local Git configuration and automatically removes them after the job finishes. Users can disable credential persistence entirely:

- uses: actions/checkout@v7
  with:
    persist-credentials: false

This ensures no credentials remain on the runner disk after the checkout step completes.

Practical Usage Scenarios

The README provides YAML examples for common workflow patterns, implemented through the logic in src/git-command-manager.ts.

Basic Repository Checkout

The simplest implementation uses the default configuration:

- uses: actions/checkout@v7

This performs a shallow checkout of the commit that triggered the workflow.

Sparse Checkout Configuration

To checkout only specific directories, use the sparse-checkout feature:

- uses: actions/checkout@v7
  with:
    sparse-checkout: |
      src
      docs

This pattern reduces clone time and disk usage for large repositories.

Multi-Repository Workflows

The repository and path inputs enable side-by-side checkout of multiple repositories:

- uses: actions/checkout@v7
  with:
    path: main-repo

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

This configuration checks out a private repository using a Personal Access Token stored in secrets.

Fetching Pull Request HEAD Commits

To checkout the actual PR head rather than the merge commit:

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

This pattern is essential for workflows that need to analyze the exact state of a contributor's branch.

Implementation Details and Source Code

The README documentation corresponds to specific implementation files in the repository:

• src/main.ts: Entry point that parses inputs and orchestrates the checkout flow
• src/input-helper.ts: Centralized definitions of all supported inputs and default values
• src/git-auth-helper.ts: Handles token and SSH-key configuration, managing credential persistence
• src/git-command-manager.ts: Wrapper around git commands with retry logic and error handling
• src/unsafe-pr-checkout-helper.ts: Implements safety guards for fork PR checkouts
• src/state-helper.ts: Persists state between the main step and post-run cleanup
• src/url-helper.ts: Constructs Git URLs for HTTPS or SSH protocols
• src/generate-docs.ts: Helper script used during CI to auto-generate README sections

Summary

• The actions/checkout README documents version-specific changes, security policies, and configuration options for GitHub's official checkout action.
• Security defaults in v7+ block unsafe fork PR checkouts unless explicitly allowed via allow-unsafe-pr-checkout.
• Credential handling automatically cleans up authentication tokens after job completion, configurable through persist-credentials.
• Flexible inputs including fetch-depth, sparse-checkout, and filter support workflows ranging from shallow clones to full repository history with submodules.
• Multi-repository support enables checking out private repositories and multiple codebases within a single job.
• Minimal permissions of contents: read are recommended for the GITHUB_TOKEN in standard usage scenarios.

Frequently Asked Questions

What is the default fetch depth in actions/checkout?

The default fetch-depth is 1, meaning the action performs a shallow checkout fetching only the single commit that triggered the workflow run. To retrieve complete history, set fetch-depth: 0 in your workflow configuration.

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

Specify the repository input with the owner/repo format and provide a token input containing a Personal Access Token with repo scope. The src/git-auth-helper.ts implementation handles authentication by writing the token to the Git config temporarily.

What security risks does the allow-unsafe-pr-checkout input mitigate?

This input mitigates "pwn request" attacks where a malicious actor could trigger workflow runs from a forked repository to access secrets or compromise the base repository. The src/unsafe-pr-checkout-helper.ts logic blocks checkouts from forked PRs in pull_request_target contexts unless explicitly permitted.

Which permissions are required for the GITHUB_TOKEN when using checkout?

The action requires minimal permissions of contents: read for standard operations. Additional scopes are only necessary when the workflow pushes changes back to the repository, such as automated commits or tag creation.

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