# What Is `persist-credentials` in `actions/checkout`? A Complete Guide to GitHub Actions Credential Management

> Learn what persist-credentials in actions/checkout does. Understand how it manages GitHub Actions credentials and when to disable it for enhanced security. Get the complete guide now.

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

---

**The `persist-credentials` input in `actions/checkout` controls whether the authentication token or SSH key used to fetch a repository remains available in the Git configuration after the checkout step completes, defaulting to `true` to enable submodule authentication but allowing you to clear credentials for security-sensitive workflows.**

The `actions/checkout` repository is the official GitHub Action for checking out repository code within CI/CD workflows. Understanding the `persist-credentials` option is critical for securing your pipelines and managing authentication for private submodules, as it determines whether sensitive credentials linger in the Git configuration after the initial clone. This guide explains the implementation details based on the actual source code.

## How `persist-credentials` Controls Credential Lifecycle

When `actions/checkout` executes, it writes the provided authentication token (from `secrets.GITHUB_TOKEN`) or SSH key to the local Git configuration to enable the fetch operation. The `persist-credentials` flag determines what happens to these credentials after the checkout finishes.

According to the action metadata in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) (lines 52‑55), the input defaults to `true`. When enabled, the credentials remain in the Git configuration file for the duration of the job, allowing subsequent Git operations to reuse the same authentication without re-prompting.

### Credential Persistence Enabled (`true`)

When **`persist-credentials`** is set to `true` (the default), the authentication helper writes the token or SSH key to the local Git config. These credentials are **not removed** at the end of the job, making them available for later steps that might need to fetch additional repositories or submodules.

This behavior is essential for workflows that use `configureSubmoduleAuth()` to authenticate private submodules, as seen in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (lines 92‑96). The persisted credentials enable seamless access to nested repositories without requiring additional authentication setup.

### Credential Cleanup Enabled (`false`)

When **`persist-credentials`** is set to `false`, the token or SSH key is still written temporarily to allow the checkout itself to succeed, but the action **removes** these credentials after the job finishes. 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 prevents downstream steps from unintentionally using the same token—for example, to push changes or access other repositories.

## Configuration and Input Parsing

The `persist-credentials` value is read from the workflow inputs and normalized in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) (lines 150‑152):

```typescript
result.persistCredentials =
  (core.getInput('persist-credentials') || 'false').toUpperCase() === 'TRUE';

```

Note that despite the parsing logic containing a fallback to `'false'`, the [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) declaration sets the actual default to `true`, meaning credentials persist unless explicitly disabled in your workflow.

## Security Implications and Best Practices

Understanding when to disable credential persistence is crucial for maintaining workflow security.

### Preventing Token Leakage

Set `persist-credentials: false` when your workflow runs untrusted code or third-party actions that might attempt to exfiltrate the GitHub token. This ensures the token is cleared from the Git config after checkout, reducing the attack surface. The cleanup logic in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) handles the removal of both HTTPS tokens and SSH keys from the configuration.

### Submodule Authentication Requirements

If your repository contains private submodules, you typically need `persist-credentials: true` (or the default) so that subsequent `git submodule update` commands can authenticate. The action calls `configureSubmoduleAuth()` from [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts) to apply the same credentials to submodule operations, but this requires the credentials to remain available in the Git configuration.

## Practical Configuration Examples

### Default Behavior (Credentials Persisted)

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

```

### Security-Focused Workflows (Credentials Removed)

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

```

### SSH Key with Explicit Cleanup

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

```

## Summary

- The `persist-credentials` input in `actions/checkout` controls whether authentication tokens or SSH keys remain in the Git configuration after checkout.
- **Default is `true`**: Credentials persist to support submodule authentication and subsequent Git commands.
- **Set to `false`**: Credentials are removed after the job finishes, preventing accidental token leakage to untrusted steps.
- The implementation spans [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml), [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), and [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), with cleanup logic defined at lines 19‑24.
- For workflows with private submodules, keep the default `true` to enable `configureSubmoduleAuth()` functionality.

## Frequently Asked Questions

### What is the default value of `persist-credentials` in `actions/checkout`?

The default value is `true`. As defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) (lines 52‑55), credentials persist after checkout unless explicitly set to `false`. This default ensures that workflows with private submodules can authenticate without additional configuration.

### When should I set `persist-credentials` to `false`?

Set `persist-credentials` to `false` when running untrusted code, third-party actions, or any step that should not have access to your repository token. This setting triggers the cleanup logic in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) that removes the token from the Git config after checkout, preventing potential token exfiltration.

### Does `persist-credentials` affect SSH keys as well as tokens?

Yes. The flag applies to both HTTPS tokens (from `secrets.GITHUB_TOKEN`) and SSH keys (from `secrets.SSH_DEPLOY_KEY`). When set to `false`, the action removes both types of credentials from the Git configuration after the checkout completes, as handled by the authentication helper in [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts).

### How does `persist-credentials` interact with submodules?

When `persist-credentials` is `true`, the action can reuse the same credentials for submodule operations via `configureSubmoduleAuth()`. If you set it to `false` and your repository has private submodules, subsequent submodule updates will fail authentication unless you provide separate credentials. The submodule authentication logic resides in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (lines 92‑96).