What Permissions Does actions/checkout Require? Minimal GitHub Token Setup

The actions/checkout action requires only contents: read permission to clone your repository and fetch all referenced content.

The actions/checkout action is the most widely used step in GitHub Actions workflows, responsible for cloning your repository into the workflow runner. Understanding the minimal actions/checkout permissions is essential for securing your CI/CD pipelines and following the principle of least privilege. According to the source code in the actions/checkout repository, this action only needs read access to repository contents, regardless of whether you use the default GITHUB_TOKEN or a custom personal access token (PAT).

Understanding the Minimal Permission Set

The action requires exactly one permission to function: read access to repository contents.

The contents: read Requirement

When you include actions/checkout in your workflow, it authenticates using the GITHUB_TOKEN (or a custom token via the token input). As documented in the README (lines 777-785), the action is recommended to run with the following minimal permission:

permissions:
  contents: read

This single permission is sufficient for all core checkout operations, including:

• Fetching the specified Git ref
• Performing sparse-checkout operations
• Downloading Git LFS objects
• Handling Git submodules

According to action.yml (lines 12-25), the token input defaults to ${{ github.token }}, which means the workflow-level permissions configuration determines what the checkout step can access.

How the Token is Consumed

The action's entry point in src/main.ts reads the token input and initializes the Git authentication helper. In src/git-auth-helper.ts, the action configures Git to use the provided token for HTTPS operations. This implementation confirms that the action only needs to read repository data—never write, delete, or modify repository contents, issues, pull requests, or packages.

Configuring Permissions in Your Workflow

Minimal Workflow Configuration

Here is the minimal configuration required for a workflow using actions/checkout:

name: CI
on: [push, pull_request]

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: echo "Repository checked out successfully"

Setting permissions: contents: read at the workflow level ensures that the default token provided to every job has exactly the actions/checkout permissions required, and nothing more.

Using a Personal Access Token (PAT)

If you supply a custom token via the token input, it must have equivalent read-only scopes:

permissions:
  contents: read

steps:
  - uses: actions/checkout@v7
    with:
      token: ${{ secrets.MY_PAT }}

When using a PAT, ensure it has at least repo scope (for private repositories) or public_repo scope (for public repositories), which map to the contents: read permission in the GitHub Actions context.

Why Additional Permissions Are Not Required

Unlike actions that create releases, comment on issues, or push code, actions/checkout is strictly a read-only operation. The action does not:

• Write to the repository
• Modify workflow files
• Access issues or pull request metadata
• Upload packages

Even advanced features like checking out submodules or fetching LFS objects only require read access to those specific resources. The src/git-auth-helper.ts file handles credential configuration purely for authentication during fetch operations, never for push operations.

Summary

• The only required permission for actions/checkout is contents: read
• The action defaults to using ${{ github.token }} as defined in action.yml
• Configuration in src/main.ts and src/git-auth-helper.ts confirms the action only performs read operations
• Both the default GITHUB_TOKEN and custom PATs must provide at least repository read access
• No additional permissions are needed for submodules, LFS, or sparse-checkout

Frequently Asked Questions

Do I need write permissions for actions/checkout?

No. The actions/checkout action never writes to your repository. It only clones and fetches data, so contents: read is sufficient. Write permissions are only necessary for subsequent steps in your workflow that might push changes or create releases.

Can I use actions/checkout with a personal access token?

Yes. You can provide a PAT via the token input. Ensure the PAT has at least repo scope (for private repositories) or public_repo scope (for public repositories), which provides the equivalent of contents: read access. As defined in action.yml lines 12-25, the token input accepts any valid Git credential.

What happens if I don't specify permissions in my workflow?

If you omit the permissions key, the workflow receives the default permissions granted to the GITHUB_TOKEN, which historically was write-all but now defaults to restricted in newer repositories. While checkout might work with default permissions, explicitly setting contents: read follows security best practices and ensures your workflow functions correctly under restricted token permissions.

Are additional permissions needed for submodules or Git LFS?

No. Checking out submodules or Git LFS objects does not require additional GitHub token permissions beyond contents: read. These features operate within the repository read scope, fetching additional blobs or submodule repositories using the same authentication credentials already configured in src/git-auth-helper.ts.

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