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

> Discover the minimal permissions actions/checkout needs. Learn how to set up your GitHub token with just contents: read for secure repository cloning and content fetching.

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

---

**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:

```yaml
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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/src/main.ts) reads the token input and initializes the Git authentication helper. In [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/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`:

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

```yaml
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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/action.yml)
- Configuration in [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) and [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts).