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

> Learn to configure token authentication for actions/checkout. Securely provide your Personal Access Token or GitHub token to authenticate Git operations. This guide ensures safe secret handling.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: how-to-guide
- Published: 2026-07-05

---

**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`](https://github.com/actions/checkout/blob/main/src/input-helper.ts) and [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts).

### Input Parsing and Token Retrieval

In [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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.

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