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

> Discover how the actions/checkout GitHub Action creates and uses a temporary .git-credentials file when persist-credentials is enabled. Learn about runner temporary directories and credential persistence.

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

---

**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`](https://github.com/actions/checkout/blob/main/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:

```ini
[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`](https://github.com/actions/checkout/blob/main/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)

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

```

### Disable Credentials File Creation

```yaml
- 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.

```yaml
- 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`](https://github.com/actions/checkout/blob/main/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.