Authenticated Git Commands in Docker Container Actions with actions/checkout: Requirements and Implementation

The actions/checkout action stores Git authentication tokens in the local Git configuration using the http.<origin>/.extraheader key, enabling automatic authentication for any Git commands run inside Docker containers as long as the runner version is at least v2.329.0 and the persist-credentials input remains set to its default value of true.

Running Git commands inside Docker container actions often requires authentication to private repositories. The actions/checkout action simplifies this by automatically injecting credentials into the Git configuration, but specific runner requirements and configuration settings must be satisfied for this mechanism to function correctly within containerized environments.

Runner Version and Environment Requirements

For authenticated Git commands to work inside Docker containers, the GitHub Actions runner must meet specific version and mounting requirements.

Minimum Runner Version

The runner must be version v2.329.0 or later. Earlier versions cannot mount the temporary directory required for the token file that enables cross-container authentication. According to the actions/checkout README at line 18, this version introduced the necessary support for mounting $RUNNER_TEMP into container environments.

RUNNER_TEMP Directory Mounting

The runner must mount the $RUNNER_TEMP directory into the Docker container. This mount allows the token file stored in the temporary directory to be accessible from inside the container environment. As documented in adrs/0153-checkout-v2.md at lines 31-33, this mounting capability is essential for the authentication mechanism to bridge the host and container environments.

How Token Persistence Works

When actions/checkout runs, it configures Git to include authentication headers automatically for all subsequent commands.

The Git Authentication Helper

In src/git-auth-helper.ts at line 57, the action creates a Git configuration entry using the pattern http.<origin>/.extraheader. For example, this generates a configuration like http.https://github.com/.extraheader. The src/git-source-provider.ts file calls this helper to establish authentication before cloning or fetching repositories.

This extra header contains the authorization token that Git includes in every HTTP request to the remote origin, eliminating the need to manually configure credentials inside your container.

Token Storage Location

By default, the action writes the token to a file under $RUNNER_TEMP and references it from the Git config key http.<origin>/.extraheader. The token is automatically removed after the job finishes, ensuring credentials do not persist beyond the workflow execution.

Configuration Options for Private Repositories

Accessing the Current Repository

For the repository being checked out, authentication happens automatically using the default GITHUB_TOKEN. The persist-credentials input controls whether these credentials remain available for subsequent steps.

Accessing Other Private Remotes

When you need to authenticate to a private remote other than the current repository, supply a personal access token (PAT) via the token input. As noted in the README at line 307, the action writes this token to the same extraheader config key, making it available for authenticated operations against external private repositories.

Controlling Credential Persistence

The persist-credentials input determines whether the Git authentication token remains available for subsequent commands.

Default Behavior

By default, persist-credentials is set to true. This stores the token in a file under $RUNNER_TEMP and references it from the Git config, allowing any Git commands run inside Docker containers to authenticate automatically.

Disabling Persistence

Set persist-credentials: false to prevent the action from storing credentials. This is recommended when subsequent steps do not require Git authentication or when minimizing credential exposure is a security priority. When disabled, any git commands inside the container will fail with authentication errors unless you manually provide credentials.

Implementation Examples

The following workflow demonstrates authenticated Git commands inside a Docker container action:

# .github/workflows/example.yml

name: Demo authenticated git in a container
on: [push]

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repo
        uses: actions/checkout@v3
        with:
          # Optional: provide a PAT for accessing other private repos

          # token: ${{ secrets.MY_PAT }}

      - name: Run a Docker container action
        uses: my-org/my-container-action@v1
        # Inside the container, commands like these work automatically:

        #   git fetch --all --tags

        #   git pull origin main

To run Git commands without automatic authentication:

      - name: Checkout without persisting credentials
        uses: actions/checkout@v3
        with:
          persist-credentials: false

Summary

• Runner version v2.329.0+ is required to mount $RUNNER_TEMP into Docker containers for token access.
• Token storage occurs in http.<origin>/.extraheader within the Git configuration, implemented in src/git-auth-helper.ts at line 57.
• Default configuration with persist-credentials: true enables automatic authentication for subsequent Git commands inside containers.
• Private repository access requires the token input when accessing remotes other than the checked-out repository.
• Security opt-out is available via persist-credentials: false to prevent credential exposure in container environments.

Frequently Asked Questions

What runner version is required for authenticated Git commands in Docker containers?

GitHub Actions runner version v2.329.0 or later is required. Earlier versions lack support for mounting the $RUNNER_TEMP directory into containers, which prevents the authentication token from being accessible inside Docker environments. This requirement is documented in the actions/checkout README at line 18 and the architectural decision record at adrs/0153-checkout-v2.md lines 31-33.

How does actions/checkout store the Git authentication token?

The action stores the token using the Git configuration key http.<origin>/.extraheader (for example, http.https://github.com/.extraheader). In src/git-auth-helper.ts at line 57, the action sets this configuration to include an authorization header with the token. The token file itself resides in $RUNNER_TEMP, which the runner mounts into the container.

Can I disable credential persistence for security reasons?

Yes. Set persist-credentials: false in the actions/checkout step configuration. This prevents the action from writing the token to the Git configuration and creating the temporary credential file. Use this option when subsequent steps do not require Git authentication or when following security best practices to minimize credential exposure.

How do I access private repositories other than the one being checked out?

Supply a personal access token (PAT) using the token input. The action writes this token to the same extraheader Git configuration key, allowing authenticated access to private remotes. This is necessary when your Docker container action needs to fetch from or push to private repositories different from the workflow's primary repository.

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