How to Configure Token Authentication for actions/checkout: Complete Implementation Guide

To configure token authentication for actions/checkout, provide a Personal Access Token (PAT) or the default GitHub token via the token input; the action automatically injects this credential into Git’s HTTP configuration using a temporary file under $RUNNER_TEMP, ensuring secure authentication while keeping the secret masked from logs and removing it after the job completes.

The actions/checkout repository handles authentication for private repositories and protected operations by accepting a GitHub token through workflow inputs. Understanding how to configure token authentication for actions/checkout ensures your CI/CD pipelines can securely fetch code and push changes without exposing sensitive credentials. This guide examines the actual TypeScript implementation to show you exactly how the token flows from workflow syntax to Git execution.

How Token Authentication Works in actions/checkout

The authentication system follows a three-stage pipeline implemented across src/input-helper.ts and src/git-auth-helper.ts.

Input Parsing and Token Retrieval

In src/input-helper.ts, lines 39-41 read the token input from the workflow configuration and store it in the IGitSourceSettings interface property authToken. By default, this resolves to ${{ github.token }} if no explicit value is provided.

Temporary Credentials File Generation

The GitAuthHelper class (instantiated via createAuthHelper in src/git-auth-helper.ts) handles the actual authentication setup. During construction (lines 55-66), it pre-computes the HTTP header value and prepares a placeholder string. The configureAuth() method triggers configureToken() (lines 26-34), which creates a temporary file under $RUNNER_TEMP, first writing a placeholder (AUTHORIZATION: basic ***) before replacing it with the base64-encoded token.

Git Configuration Wiring

To apply the credentials without modifying global Git settings permanently, the helper uses conditional includes. Lines 60-80 in src/git-auth-helper.ts execute git config commands to add includeIf.gitdir:<repo>.path entries pointing to the temporary credentials file. This ensures any Git operation within the repository directory automatically includes the authorization header.

Configuring the Token in Your Workflow

To implement token authentication, reference a secret in your workflow file using the token input.

name: Authenticated Checkout
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          persist-credentials: true

The persist-credentials: true option (default) keeps the authentication active for subsequent steps, allowing follow-up commands like git push to reuse the same token.

Security Mechanisms in the Source Code

The implementation prioritizes credential security through multiple layers of protection.

Secret Masking: Before any file operations, core.setSecret() masks the base64-encoded token string, preventing it from appearing in runner logs even if Git verbose output is enabled.

Placeholder Strategy: When writing the temporary config file, the code first inserts the placeholder AUTHORIZATION: basic *** (line 26 in src/git-auth-helper.ts), then performs an in-place replacement with the actual token. This prevents audit tools or process monitors from capturing the real credential during the write operation.

Automatic Cleanup: The post-job step invokes removeAuth() (lines 72-79 in src/git-auth-helper.ts), which deletes the temporary credentials file and removes the extraheader configuration entries, ensuring no tokens persist on the runner after the job completes.

Summary

• Token Input: Provide authentication via the token input declared in action.yml, defaulting to ${{ github.token }}.
• Secure Injection: The GitAuthHelper.configureToken() method creates a temporary file under $RUNNER_TEMP containing the base64-encoded credential.
• Git Integration: Conditional includes (includeIf) wire the temporary file into Git’s configuration without altering global settings.
• Safety Features: The token is masked via core.setSecret(), written using a placeholder strategy, and automatically cleaned up by removeAuth() post-execution.

Frequently Asked Questions

What is the default token used by actions/checkout?

If you do not specify the token input, actions/checkout defaults to ${{ github.token }} (the GITHUB_TOKEN secret). This is parsed in src/input-helper.ts and stored in the IGitSourceSettings.authToken property, providing automatic authentication for the current repository without requiring explicit secret configuration.

How does actions/checkout prevent the token from leaking in logs?

The action calls core.setSecret() to mask the base64-encoded token before any Git operations execute. Additionally, the src/git-auth-helper.ts implementation writes a placeholder value (AUTHORIZATION: basic ***) to the temporary credentials file first, then replaces it with the real token, ensuring process monitors cannot capture the secret during file creation.

Where does actions/checkout store the temporary authentication file?

The temporary credentials file is created under the $RUNNER_TEMP directory with a unique UUID filename (e.g., git-credentials-<uuid>.config). This location is determined in src/git-auth-helper.ts and is automatically deleted during the post-job cleanup phase when removeAuth() executes.

How do I persist authentication for subsequent Git commands?

Set persist-credentials: true (the default) when configuring the action. This keeps the temporary credentials file and Git configuration entries active after the initial checkout, allowing subsequent workflow steps to run authenticated git fetch, git push, or git pull commands using the same token. If set to false, the post-job cleanup runs immediately after checkout, removing authentication before later steps execute.

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