# How the persist-credentials Option Works in actions/checkout

> Learn how the persist-credentials option in actions/checkout stores your GitHub token or SSH key after checkout. Understand its impact on subsequent Git operations.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: deep-dive
- Published: 2026-07-16

---

**The `persist-credentials` option controls whether the GitHub token or SSH key used to fetch a repository remains stored in the Git configuration after the checkout step completes.**

The `actions/checkout` repository is the official GitHub Action for checking out repositories in workflows. Understanding the `persist-credentials` input is essential for securing your CI/CD pipelines and managing authentication for subsequent Git operations, such as submodule fetching or push commands.

## Understanding the persist-credentials Behavior

The `persist-credentials` option is a boolean flag defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) (lines 52-55) that determines the lifecycle of authentication credentials during and after the checkout process.

### Default Behavior (persist-credentials: true)

When **`persist-credentials` is set to `true`** (the default), the authentication token or SSH key is written to the local Git configuration within the workspace. This allows subsequent steps in the same job to execute authenticated Git commands without re-authenticating. According to the source code in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), this persistence is required for operations like submodule authentication, where the helper calls `configureSubmoduleAuth()` to apply the same credentials to nested repositories (lines 92-96).

However, credentials are **not automatically removed** after the job finishes. This means the token remains accessible to any downstream steps, including potentially untrusted code.

### Security-Focused Behavior (persist-credentials: false)

When **`persist-credentials` is set to `false`**, the token or SSH key is still written temporarily to allow the initial checkout to succeed, but it is **removed immediately after checkout** completes. As implemented in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (lines 19-24), this cleanup ensures that later steps cannot inadvertently access or leak the credentials. This behavior is critical when workflows execute untrusted third-party scripts or when you want to enforce strict token isolation.

## Implementation Details in the Source Code

The option flows through several key files in the `actions/checkout` repository:

**Input Parsing ([`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts))**
The action reads the input and converts it to a boolean value stored in the internal settings object:

```typescript
// src/input-helper.ts, lines 150-152
result.persistCredentials =
  (core.getInput('persist-credentials') || 'false').toUpperCase() === 'TRUE';

```

**Checkout and Cleanup Logic ([`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts))**
This file manages the credential lifecycle. It applies the authentication helper during checkout and conditionally removes it based on the `persistCredentials` setting. The removal logic ensures that the Git configuration is cleaned up after the job when the flag is disabled.

**Authentication Helper ([`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts))**
Contains the low-level implementation for configuring and removing Git credentials, including the setup of credential helpers and SSH key management.

## Practical Configuration Examples

Configure the `persist-credentials` option in your workflow YAML to control credential availability:

```yaml

# Default behavior: credentials persisted for subsequent steps

- uses: actions/checkout@v4
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    # persist-credentials defaults to true

```

```yaml

# Security-hardened: remove credentials after checkout

- uses: actions/checkout@v4
  with:
    persist-credentials: false
    token: ${{ secrets.GITHUB_TOKEN }}

```

```yaml

# SSH key with credential cleanup

- uses: actions/checkout@v4
  with:
    ssh-key: ${{ secrets.SSH_DEPLOY_KEY }}
    persist-credentials: false

```

## Common Use Cases

**Fetching Private Submodules**
If your repository contains private submodules, you typically need `persist-credentials: true` (the default) so that the authentication helper can propagate the token to submodule fetch operations via `configureSubmoduleAuth()`.

**Running Untrusted Code**
When a workflow executes third-party scripts or build tools that might be compromised, set `persist-credentials: false` to ensure the GitHub token is unavailable to those processes, preventing potential credential leakage or unauthorized repository access.

**Selective Authentication**
Use `persist-credentials: false` when you want to verify the checkout succeeded but plan to use a different authentication method (such as a dedicated deploy key or PAT) for subsequent push operations, avoiding conflicts between credential helpers.

## Summary

- The `persist-credentials` option in `actions/checkout` controls whether the GitHub token or SSH key remains in the Git configuration after checkout.
- When set to `true` (default), credentials persist for subsequent steps, enabling submodule authentication and additional Git commands.
- When set to `false`, credentials are removed after checkout completes, as implemented in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), preventing unauthorized access in later steps.
- The input is parsed in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) and defaults to `true` according to [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml).

## Frequently Asked Questions

### What happens to my GitHub token if I set persist-credentials to false?

The token is still used to perform the initial checkout, but it is removed from the Git configuration immediately after the checkout completes. According to the source code in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (lines 19-24), the cleanup ensures that subsequent steps cannot access the token through Git's credential helper.

### Do I need persist-credentials true for submodules?

Yes, if your submodules require authentication, you typically need `persist-credentials: true` (the default) so that the action can call `configureSubmoduleAuth()` to apply the same credentials to submodule fetch operations. If you disable persistence, submodule fetching with authentication will fail unless you configure separate credentials manually.

### Is persist-credentials false more secure?

Setting `persist-credentials: false` is generally more secure when your workflow runs untrusted code or third-party actions, because it prevents the GitHub token from being exposed to later steps. However, it prevents any subsequent Git commands in the same job from authenticating with the original token, so you must balance security requirements against your workflow's functional needs.