# How actions/checkout Facilitates Code Checkout for GitHub Actions

> Discover how actions/checkout simplifies code checkout for GitHub Actions. This official action efficiently prepares your job workspace with repository source code and handles authentication, fetching, and cleanup.

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

---

**actions/checkout is the official GitHub Action that prepares a job's workspace with a copy of the repository source code, orchestrating authentication, fetching, and cleanup through a modular TypeScript architecture.**

The `actions/checkout` repository provides the standard mechanism for obtaining source code within GitHub Actions workflows. This official action implements a robust, multi-phase checkout process that handles everything from repository initialization to authentication cleanup. Understanding how actions/checkout facilitates code checkout reveals the sophisticated coordination between Git commands, GitHub API calls, and cross-platform state management.

## Core Architecture and Execution Phases

The action's architecture divides execution into distinct phases managed through [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts). This entry point determines whether to run the main checkout logic or cleanup routines based on the `stateHelper.IsPost` flag.

### Pre-Execution Phase

When `stateHelper.IsPost` is false, the action enters the pre phase and executes the `run()` function. This function begins by calling `inputHelper.getInputs()` to parse and validate action inputs such as `ref`, `fetch-depth`, `lfs`, and `submodules`. It then registers a problem matcher for Git errors before invoking the core logic in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) via `gitSourceProvider.getSource(sourceSettings)`.

### Post-Execution Cleanup

After all workflow steps complete, the post phase runs when `stateHelper.IsPost` evaluates to true. During this phase, [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) calls `cleanup()` to remove temporary authentication configuration and restore the repository directory to a safe state, unless `persist-credentials` is enabled.

## The Checkout Workflow Orchestration

The `gitSourceProvider.getSource()` function in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) coordinates the entire checkout sequence. This method manages repository preparation, authentication, and source retrieval through several specialized helper modules.

### Repository URL Resolution and Initialization

The process begins with `urlHelper.getFetchUrl(settings)` building the appropriate HTTPS or SSH fetch URL. The provider then prepares the target directory by removing stale paths and creating the destination folder. If the directory lacks a Git repository, it initializes one using `git init`, adds the remote origin, and optionally disables automatic garbage collection.

### Git Command Abstraction and Authentication

The action creates a command manager via `gitCommandManager.createCommandManager()` to detect a usable Git binary and provide a wrapper (`IGitCommandManager`) for all Git invocations. Simultaneously, `gitAuthHelper.createAuthHelper()` configures temporary global Git settings, including `safe.directory` when `set-safe-directory` is true, and establishes credentials for HTTPS, SSH keys, or token-based authentication.

### Fetching Strategies and Ref Resolution

When no `ref` or `commit` is specified, the action queries the default branch using either `git.getDefaultBranch` for remote queries or `githubApiHelper.getDefaultBranch` for GitHub API fallback. The `refHelper.getRefSpec*` functions construct ref-specs based on `fetch-depth`, `filter`, and `sparse-checkout` settings. The `git.fetch()` command retrieves objects while validating that fetched refs point to expected commits—critical for tags that may move.

### Advanced Features: LFS, Submodules, and Sparse Checkout

For repositories using Git LFS, the action runs `git.lfsInstall()` followed by `git.lfsFetch()` when the `lfs` input is true. Sparse checkout support configures Git's cone or non-cone mode when enabled. Submodule handling authenticates submodule fetches, executes `git submodule sync` and `git submodule update`, and optionally persists credentials for nested repositories.

## Commit Validation and Output Generation

After successfully checking out the source via `git.checkout()`, the action retrieves commit metadata using `git.log1()` to obtain the SHA. This value is emitted as the `commit` output for downstream steps to reference. Unless `persist-credentials` is set to true, the action immediately removes temporary authentication files to prevent credential leakage.

## Fallback Mechanisms and API Integration

When Git is unavailable on the runner, [`src/github-api-helper.ts`](https://github.com/actions/checkout/blob/main/src/github-api-helper.ts) provides an alternative path by downloading repository tarballs through the GitHub REST API. This ensures the action remains functional across diverse environments including containerized workflows and minimal runners.

## Practical Implementation Examples

Configure a basic checkout with shallow history:

```yaml

# .github/workflows/ci.yml

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

```

Perform a full clone with LFS and recursive submodules:

```yaml
- uses: actions/checkout@v4
  with:
    fetch-depth: 0          # fetch all history

    lfs: true               # enable Git LFS

    submodules: recursive   # fetch submodules

    set-safe-directory: true  # required for container jobs

```

Checkout a specific ref and capture the commit SHA:

```yaml
- uses: actions/checkout@v4
  id: checkout
  with:
    ref: v1.2.3
    fetch-depth: 1
- name: Show commit SHA
  run: echo "Checked out commit ${{ steps.checkout.outputs.sha }}"

```

## Summary

- **actions/checkout** uses a two-phase architecture (pre and post) defined in [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) to separate checkout logic from cleanup.
- The **git-source-provider.ts** module orchestrates the workflow, coordinating URL resolution, authentication, and source retrieval.
- **Authentication** is handled temporarily through `gitAuthHelper.createAuthHelper()` with automatic cleanup unless `persist-credentials` is enabled.
- **Advanced features** include LFS support, recursive submodules, sparse checkout configuration, and shallow fetch optimization.
- A **GitHub API fallback** in [`src/github-api-helper.ts`](https://github.com/actions/checkout/blob/main/src/github-api-helper.ts) allows operation when Git is not installed.

## Frequently Asked Questions

### What is the primary entry point for actions/checkout?

The primary entry point is [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts), which determines whether to execute the main checkout logic via `run()` or the cleanup phase via `cleanup()` based on the `stateHelper.IsPost` flag. This file initializes input parsing, registers problem matchers, and delegates to [`git-source-provider.ts`](https://github.com/actions/checkout/blob/main/git-source-provider.ts) for repository operations.

### How does actions/checkout handle authentication?

The action creates a temporary authentication helper through `gitAuthHelper.createAuthHelper()` in [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts). This configures global Git credentials for HTTPS tokens, SSH keys, or personal access tokens, and sets `safe.directory` when required. Unless `persist-credentials` is set to true, these configurations are automatically removed during the post-phase cleanup.

### Can actions/checkout work without Git installed?

Yes, when Git is unavailable, the action falls back to [`src/github-api-helper.ts`](https://github.com/actions/checkout/blob/main/src/github-api-helper.ts), which downloads repository tarballs via the GitHub REST API. This ensures workflows can obtain source code even on minimal runners or specialized containers lacking Git binaries.

### How does the post-phase cleanup work?

The post-phase activates when `stateHelper.IsPost` is true, triggering the `cleanup()` function in [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts). This removes temporary authentication configuration from Git global settings and restores the repository directory to a safe state, preventing credential persistence between workflow jobs.