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

> Explore the actions/checkout README for a complete guide on version history, security, inputs, usage, and credential handling. Get essential information for your GitHub workflows.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts) and [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/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:

```yaml
- 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`](https://github.com/actions/checkout/blob/main/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:

```yaml
- 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`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts).

### Basic Repository Checkout

The simplest implementation uses the default configuration:

```yaml
- 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:

```yaml
- 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:

```yaml
- 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:

```yaml
- 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`](https://github.com/actions/checkout/blob/main/src/main.ts)**: Entry point that parses inputs and orchestrates the checkout flow
- **[`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts)**: Centralized definitions of all supported inputs and default values
- **[`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts)**: Handles token and SSH-key configuration, managing credential persistence
- **[`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)**: Wrapper around git commands with retry logic and error handling
- **[`src/unsafe-pr-checkout-helper.ts`](https://github.com/actions/checkout/blob/main/src/unsafe-pr-checkout-helper.ts)**: Implements safety guards for fork PR checkouts
- **[`src/state-helper.ts`](https://github.com/actions/checkout/blob/main/src/state-helper.ts)**: Persists state between the main step and post-run cleanup
- **[`src/url-helper.ts`](https://github.com/actions/checkout/blob/main/src/url-helper.ts)**: Constructs Git URLs for HTTPS or SSH protocols
- **[`src/generate-docs.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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.