What .git-credentials File Is Used by actions/checkout?

The actions/checkout GitHub Action generates a temporary credentials file named git-credentials-<uuid>.config in the runner's temporary directory (RUNNER_TEMP) when persist-credentials is enabled.

When you use the actions/checkout action to authenticate with GitHub repositories, it does not rely on a static .git-credentials file in your repository. Instead, the action dynamically creates a unique, temporary configuration file at runtime to store authentication tokens securely. This implementation ensures that sensitive credentials never persist in the repository filesystem beyond the job's execution.

How actions/checkout Creates the Git Credentials File

The credential management logic is implemented in src/git-auth-helper.ts. When persist-credentials is set to true (the default), the action instantiates a GitAuthHelper class that orchestrates the creation and lifecycle of the temporary credentials file.

Temporary File Location and Naming Convention

The action generates a unique file path using the GitAuthHelper.getCredentialsConfigPath() method. This creates a file following the pattern:

git-credentials-<uuid>.config

The file is stored in the runner's temporary directory, accessible via the RUNNER_TEMP environment variable. For example:

/home/runner/work/_temp/git-credentials-c0a6...-42a5-4d7e-8c2c-9b5c0a2c6a3f.config

The UUID ensures no naming collisions occur when multiple jobs run concurrently on the same runner.

The Credentials Configuration Content

The temporary file contains Git configuration directives that inject an HTTP authorization header. As implemented in GitAuthHelper.configureToken() (lines 26-34 and 60-68), the file content follows this structure:

[http "https://github.com"]
    extraheader = AUTHORIZATION: basic <base64-encoded-token>

For security, the action first writes a placeholder value (AUTHORIZATION: basic ***) and then immediately replaces it with the actual token (lines 42-58). This prevents the real token from appearing in process command-line arguments or logs.

Technical Implementation Details

The GitAuthHelper class manages the entire lifecycle of the credentials file:

• Configuration: The configureToken() method creates an includeIf entry (or include.path for global configuration) in the repository's Git config, pointing to the temporary file.
• Path Storage: The absolute path is stored in the GitAuthHelper.credentialsConfigPath property (lines 24-30).
• Cleanup: The removeToken() method (lines 81-99) removes all includeIf entries referencing files matching the git-credentials-*.config pattern and deletes the temporary file—only if it resides under RUNNER_TEMP.

The low-level Git operations are handled by src/git-command-manager.ts, which executes the necessary git config commands.

Controlling Credentials Persistence

You can control whether the temporary .git-credentials file is created using the persist-credentials input.

Default Behavior (Credentials Persisted)

- name: Checkout repository
  uses: actions/checkout@v4
  with:
    persist-credentials: true  # Default: creates git-credentials-*.config in RUNNER_TEMP

Disable Credentials File Creation

- name: Checkout without credentials
  uses: actions/checkout@v4
  with:
    persist-credentials: false  # No temporary credentials file is generated

When set to false, the action skips the GitAuthHelper configuration entirely, and no authentication tokens are written to disk.

Inspecting and Debugging the Credentials File

For troubleshooting purposes, you can inspect the temporary file during workflow execution. Note that this exposes sensitive tokens and should only be used for debugging.

- name: Debug credentials file
  run: |
    echo "Looking for credentials in $RUNNER_TEMP"
    ls -la $RUNNER_TEMP/git-credentials-*.config
    cat $RUNNER_TEMP/git-credentials-*.config
  shell: bash

The unit tests in src/git-auth-helper.test.ts (lines 120-130) verify the temporary file naming convention and cleanup logic, checking specifically for the git-credentials- prefix.

Summary

• The actions/checkout action does not use a static .git-credentials file; it generates a temporary runtime file named git-credentials-<uuid>.config.
• The file is stored in RUNNER_TEMP to ensure isolation between concurrent jobs.
• Authentication is configured via Git's includeIf mechanism, injecting an extraheader with a base64-encoded token.
• Security measures include using placeholder values before writing real tokens and restricting cleanup to files within RUNNER_TEMP.
• The ** persist-credentials: false** option prevents the file creation entirely.

Frequently Asked Questions

Where is the .git-credentials file stored in actions/checkout?

The credentials file is stored in the runner's temporary directory (RUNNER_TEMP), not in the repository workspace. The full path follows the pattern $RUNNER_TEMP/git-credentials-<uuid>.config, where the UUID ensures unique naming for each job run.

What happens to the git credentials file after the job completes?

The GitAuthHelper.removeToken() method automatically cleans up the file when the job finishes. It removes all includeIf entries from the Git configuration that reference the temporary file, then deletes the file itself—but only if it resides within RUNNER_TEMP to prevent accidental deletion of unrelated files.

How can I prevent actions/checkout from creating a credentials file?

Set persist-credentials: false in your workflow configuration. This disables the authentication helper entirely, preventing the creation of the temporary git-credentials-*.config file. Use this setting when you do not need subsequent Git operations to authenticate with the repository.

What format does the temporary credentials file use?

The file uses the standard Git configuration format with an http section specific to GitHub's URL. It contains an extraheader directive that injects the Authorization: basic HTTP header with a base64-encoded token, enabling authentication without storing credentials in the remote URL.

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