How to Make a Checkout Read-Only Using actions/checkout

Set persist-credentials: false when calling actions/checkout to prevent the GitHub token from being stored in the local Git configuration, ensuring subsequent git operations cannot authenticate.

GitHub Actions workflows rely on actions/checkout to clone repositories and prepare the workspace for CI/CD tasks. While the action defaults to persisting authentication credentials for convenience, you can make a checkout read-only using actions/checkout by explicitly disabling credential storage. This approach fetches the code without leaving tokens available for subsequent push operations, following the principle of least privilege.

How persist-credentials Controls Repository Access

By default, actions/checkout clones the repository and stores the supplied authentication token (by default ${{ github.token }}) in the local Git configuration. This enables subsequent git commands to push changes back to the repository. To create a read-only workspace, you disable this credential persistence.

When the input persist-credentials is set to false, the action does not write the token into .git/config. As a result, the checkout can still fetch the code, but any later git push, git pull, or other authenticated operations will fail because no credentials are available.

Input Parsing in src/input-helper.ts

The default behavior is defined in [src/input-helper.ts](https://github.com/actions/checkout/blob/main/src/input-helper.ts) at line 100, where the persist-credentials input is parsed and defaults to true. This Boolean value determines whether the authentication helper will store credentials after the initial clone operation.

Credential Cleanup in src/git-auth-helper.ts

During the post-job cleanup phase, [src/git-auth-helper.ts](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts) removes any persisted credentials. By setting persist-credentials: false, you opt out of the persistence mechanism entirely, meaning credentials are never written to disk and therefore do not require cleanup.

Action Metadata Declaration

The action’s metadata in [action.yml](https://github.com/actions/checkout/blob/main/action.yml) declares the persist-credentials input with the description "Whether to configure the token … (default: true)". This official documentation confirms the input's purpose for controlling read-only access.

Implementation Examples for Read-Only Checkouts

The following configurations demonstrate how to implement read-only checkouts in different workflow scenarios.

Basic Read-Only Configuration

Use this pattern for simple CI jobs that only need to read repository contents:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          # Do not store the token; the workspace will be read-only

          persist-credentials: false

Shallow Clone with Read-Only Access

Combine persist-credentials: false with other checkout options like shallow cloning and specific branch references:

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          ref: main                # checkout the main branch

          fetch-depth: 1          # shallow clone (default)

          persist-credentials: false

Matrix Strategy Workflows

When running parallel jobs across different environments, ensure each checkout is read-only:

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [14, 16, 18]
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: Run tests
        run: npm test

Summary

• Set persist-credentials: false to make a checkout read-only using actions/checkout.
• This prevents the GitHub token from being written to .git/config in src/input-helper.ts (line 100).
• The workspace can fetch code but cannot perform authenticated git push or git pull operations.
• Credentials are never persisted to disk, so src/git-auth-helper.ts has no tokens to clean up during post-job phases.
• Suitable for CI jobs that only require reading repository contents without writing changes.

Frequently Asked Questions

What happens if I attempt to push changes after setting persist-credentials to false?

The push operation will fail with an authentication error. Since actions/checkout does not store the GitHub token in the local Git configuration when persist-credentials is set to false, subsequent git push or git pull commands lack the necessary credentials to authenticate with the remote repository.

Does disabling persist-credentials affect the initial repository clone?

No. The initial clone and fetch operations complete successfully because authentication occurs during the checkout process itself. The persist-credentials setting only controls whether the token is written to disk for reuse by later steps, as implemented in the post-job cleanup logic of src/git-auth-helper.ts.

Is persist-credentials false recommended for security best practices?

Yes. Unless your workflow specifically requires pushing changes back to the repository, setting persist-credentials: false is the recommended way to make a checkout read-only. This keeps the repository secure by preventing accidental pushes and ensures that compromised workflow steps cannot misuse the GitHub token stored in the Git configuration.

Can I use persist-credentials with private repositories?

Yes. The persist-credentials input works with both public and private repositories. When set to false, the initial clone still authenticates using the provided token, but the token is not persisted, maintaining a read-only workspace while still allowing access to private code during the checkout step.

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