How to Debug Issues with the `actions/checkout` GitHub Action

Enable debug logging by setting ACTIONS_STEP_DEBUG: true in your workflow environment to expose detailed traces from input parsing, ref resolution, and git command execution.

actions/checkout is a TypeScript‑based JavaScript action that clones a repository (or a specific ref) into the runner’s workspace. Understanding its internal architecture and knowing where to look in the source code helps you pinpoint why a checkout fails and how to extract actionable diagnostic information.

Enable Debug Logging to Expose Internal Traces

The action emits detailed diagnostic information only when the runner’s log level is set to debug. You can enable this by setting the job‑level environment variable ACTIONS_STEP_DEBUG to true, or by configuring the repository secret ACTIONS_RUNNER_DEBUG to true for broader runner diagnostics.

jobs:
  checkout:
    runs-on: ubuntu-latest
    env:
      ACTIONS_STEP_DEBUG: true   # Enables core.debug calls across all steps

    steps:
      - uses: actions/checkout@v4

With debug mode enabled, the action prints messages prefixed with ##[debug] in the workflow step logs, revealing the inner workings of each component.

Understanding the Checkout Architecture and Debug Points

The action is structured into discrete modules, each responsible for a specific phase of the checkout process. When you debug issues with actions/checkout, you are effectively tracing data through these specific source files:

• src/input-helper.ts – Parses all inputs (ref, fetch-depth, submodules, lfs, etc.) and logs the resolved values using core.debug.
• src/ref-helper.ts – Normalises the ref (branch, tag, or pull‑request) and resolves the commit SHA, emitting debug messages when the ref format is unexpected.
• src/github-api-helper.ts – Calls the GitHub REST API (e.g., to fetch a PR’s head SHA) and prints the raw response when debug logging is active.
• src/git-command-manager.ts – Wraps the git CLI; all executed commands are printed via core.debug, and stdout/stderr are captured for inspection.
• src/git-auth-helper.ts – Sets up authentication (HTTPS token or SSH key) and writes temporary Git config files, logging the config path and any errors.
• src/git-directory-helper.ts – Determines the target directory (GITHUB_WORKSPACE or a custom path) and checks for existing repositories.
• src/main.ts – Orchestrates the workflow by wiring together inputs, ref resolution, authentication, and the final checkout command.

Interpreting Debug Output and Common Failure Points

When a checkout fails, the debug logs allow you to isolate the failure to one of four common areas.

Input Validation Failures in input-helper.ts

If the action exits early or behaves unexpectedly, inspect the debug output for lines logged by src/input-helper.ts. Look for:

##[debug]qualified repository = 'owner/my-repo'
##[debug]ref = 'refs/heads/main'
##[debug]fetch depth = 1

If these values do not match your intended configuration (e.g., a typo in the ref input or an unsupported fetch-depth value), the failure occurs at the input parsing stage.

Ref Resolution Errors in ref-helper.ts

The src/ref-helper.ts module converts shorthand references (like main or refs/pull/1/head) into full commit SHAs. If you see Unexpected ref format in the debug logs, the supplied ref parameter may be malformed. For example, omitting the refs/heads/ prefix on certain edge cases can cause resolution to fail. Let the action auto‑detect the ref by omitting the input, or ensure you use the fully qualified reference.

Authentication and Credential Setup in git-auth-helper.ts

Authentication failures typically surface in src/git-auth-helper.ts. This module writes a temporary Git credential helper to disk and configures the local Git environment to use it. Debug logs reveal the temporary file path. If you see "Unsetting HOME override" without a preceding "Credentials config path" entry, the token input may be missing or empty, causing subsequent Git operations to fail with authentication errors.

Git Command Execution Failures in git-command-manager.ts

Network issues, permission errors, or repository size limits manifest in src/git-command-manager.ts. The debug output shows the exact command line executed:

##[debug]Running git clone --depth 1 ...

When a command returns a non‑zero exit code, the captured stdout and stderr appear immediately after the command line. Copy the exact command and run it locally (or in an interactive debugging container) to reproduce the raw Git error outside of the GitHub Actions environment.

Practical Debugging Workflow Examples

You can augment the standard checkout behavior with additional diagnostic steps to capture more context.

Explicitly echo resolved inputs after checkout:

- uses: actions/checkout@v4
- name: Show checkout inputs
  run: |
    echo "Repository: ${{ github.repository }}"
    echo "Ref: ${{ inputs.ref || 'default (head)' }}"
    echo "Fetch depth: ${{ inputs.fetch-depth || 'default (1)' }}"

Enable verbose Git output and full history:

- name: Checkout with verbose debugging
  uses: actions/checkout@v4
  with:
    fetch-depth: 0               # Full history for debugging history-related errors

    submodules: true
  env:
    ACTIONS_STEP_DEBUG: true
    GIT_TRACE: 1                 # Extra verbose Git output

    GIT_CURL_VERBOSE: 1          # Verbose network operations

Capture raw action output by invoking the distribution directly:

- name: Checkout (wrapped for capture)
  run: |
    set -e
    node $(npm root -g)/@actions/checkout/dist/index.js
  env:
    ACTIONS_STEP_DEBUG: true
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Summary

• Enable debug mode by setting ACTIONS_STEP_DEBUG: true to see internal core.debug traces from src/main.ts and its helpers.
• Trace the data flow through input-helper.ts (inputs), ref-helper.ts (ref resolution), git-auth-helper.ts (credentials), and git-command-manager.ts (execution).
• Inspect specific log prefixes: qualified repository, ref =, and Running git to identify exactly which phase fails.
• Validate authentication by checking for temporary credential paths in the debug output; missing paths indicate token issues.
• Reproduce locally by copying the exact Git commands shown in the git-command-manager.ts debug logs.

Frequently Asked Questions

How do I enable debug logging for actions/checkout?

Set the environment variable ACTIONS_STEP_DEBUG: true in your job configuration, or set the repository secret ACTIONS_STEP_DEBUG to true. This activates core.debug calls within the action, printing internal state such as parsed inputs and executed Git commands to the step logs prefixed with ##[debug].

Why does my checkout fail with "Unexpected ref format"?

This error originates in src/ref-helper.ts when the action cannot parse the provided ref input into a valid Git reference. Ensure you use fully qualified references like refs/heads/main or refs/tags/v1.0.0, or omit the ref input entirely to let the action auto‑detect the correct reference from the workflow event.

How can I see the exact git commands executed by actions/checkout?

Enable debug logging and look for lines beginning with ##[debug]Running git in the step output. The src/git-command-manager.ts module logs every command line before execution, including arguments like --depth or --recurse-submodules, allowing you to copy and run the command locally for further investigation.

What does "Unsetting HOME override" mean in the logs?

This message appears in src/git-auth-helper.ts during cleanup. If you see it without a preceding "Credentials config path" message, the action failed to write the temporary Git credential helper, usually because the token input was empty or the GITHUB_TOKEN secret was not passed to the step. Verify that your workflow has proper permissions or explicitly passes a token.

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