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

> Debug actions/checkout issues effectively. Enable debug logging with ACTIONS_STEP_DEBUG true for detailed traces, helping you pinpoint problems in input parsing, ref resolution, and git command execution.

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

---

**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.

```yaml
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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/src/git-directory-helper.ts)** – Determines the target directory (`GITHUB_WORKSPACE` or a custom `path`) and checks for existing repositories.
- **[`src/main.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/input-helper.ts)

If the action exits early or behaves unexpectedly, inspect the debug output for lines logged by [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/ref-helper.ts)

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

Authentication failures typically surface in [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/git-command-manager.ts)

Network issues, permission errors, or repository size limits manifest in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/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:**

```yaml
- 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:**

```yaml
- 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:**

```yaml
- 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`](https://github.com/actions/checkout/blob/main/src/main.ts) and its helpers.
- **Trace the data flow** through [`input-helper.ts`](https://github.com/actions/checkout/blob/main/input-helper.ts) (inputs), [`ref-helper.ts`](https://github.com/actions/checkout/blob/main/ref-helper.ts) (ref resolution), [`git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/git-auth-helper.ts) (credentials), and [`git-command-manager.ts`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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`](https://github.com/actions/checkout/blob/main/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.