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

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 (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 (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 (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 (lines 150‑152):

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

Note that despite the parsing logic containing a fallback to 'false', the 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 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 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)

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

Security-Focused Workflows (Credentials Removed)

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

SSH Key with Explicit Cleanup

- 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, src/input-helper.ts, and 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 (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 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.

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 (lines 92‑96).

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