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

> Learn how to make actions/checkout read-only by setting persist-credentials false to prevent token storage and secure subsequent Git operations.

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

---

**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)](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)](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)](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:

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

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

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