How the persist-credentials Option Works in actions/checkout

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 (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, 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 (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) The action reads the input and converts it to a boolean value stored in the internal settings object:

// 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) 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) 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:

# Default behavior: credentials persisted for subsequent steps

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

# Security-hardened: remove credentials after checkout

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

# 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, preventing unauthorized access in later steps.
• The input is parsed in src/input-helper.ts and defaults to true according to 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 (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.

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