# Key Files and Architecture of the actions/checkout GitHub Action

> Discover the key files in the actions/checkout architecture. Understand how srcmaints, gitSourceProviderTs, and gitCommandManagerTs manage repository cloning and Git operations.

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

---

**The actions/checkout architecture relies on a modular TypeScript codebase where [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) orchestrates input parsing and cleanup, while specialized providers in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) and [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) handle the actual repository cloning and Git operations.**

The `actions/checkout` repository powers the official GitHub Action used by millions of workflows to clone repositories into CI runners. Understanding the actions/checkout architecture requires examining how a small set of TypeScript files in the `src/` directory separates concerns between configuration parsing, Git command execution, authentication management, and state persistence across pre-run and post-run phases.

## Core Architecture Overview

The action executes in two distinct phases controlled by [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts). During the pre-run phase, the entry point calls `inputHelper.getInputs()` to build an `IGitSourceSettings` object, then invokes `gitSourceProvider.getSource()` to perform the checkout. During the post-run phase, the same file dispatches to `cleanup()` to remove temporary credentials and reset state.

This design creates clear boundaries between input validation, source acquisition, and command execution, allowing the action to fallback from Git operations to REST API downloads when necessary.

## Key Source Files and Their Responsibilities

### Entry Point and Orchestration ([`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts))

The [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) file serves as the universal entry point for both execution phases. It registers the problem-matcher from [`src/problem-matcher.json`](https://github.com/actions/checkout/blob/main/src/problem-matcher.json) to convert Git errors into GitHub annotations, then determines whether to run the standard workflow or cleanup logic based on the `IsPost` state flag.

During normal operation, it delegates to `gitSourceProvider.getSource()`. During cleanup, it ensures temporary credentials are removed according to the `persist-credentials` input.

### Input Processing and Validation ([`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts))

All action inputs flow through [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), which constructs the `IGitSourceSettings` configuration object. This file performs critical environment checks against `GITHUB_WORKSPACE`, validates repository names, parses sparse-checkout flags, and implements safety checks for fork pull requests.

The helper handles complex input combinations including SSH keys, known hosts, LFS options, and submodule recursion settings, ensuring the downstream providers receive a sanitized configuration.

### Source Acquisition ([`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts))

The [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) file contains the high-level workflow logic for obtaining source code. It instantiates a `GitCommandManager`, configures authentication through `gitAuthHelper`, resolves the default branch when not explicitly specified, and orchestrates the fetch and checkout sequence.

This provider supports both full Git clones and sparse checkouts, handling LFS initialization and submodule synchronization before calling `git.checkout()` to place files in the workspace.

### Git Command Abstraction ([`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts))

All direct Git executable interactions are encapsulated in [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts). This file implements the `IGitCommandManager` interface with methods like `fetch()`, `checkout()`, `sparseCheckout()`, and `lfsInstall()`.

It enforces version requirements through constants like `MinimumGitVersion` and `MinimumGitSparseCheckoutVersion`, ensuring the runner's Git binary supports advanced features before attempting operations that would fail on older installations.

### Authentication and URL Handling

**[`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts)** manages temporary credentials by writing tokens or SSH keys into `.git/config` or global Git configuration. It respects the `persist-credentials` input to determine whether to scrub these entries during the post-run cleanup phase.

**[`src/url-helper.ts`](https://github.com/actions/checkout/blob/main/src/url-helper.ts)** constructs the correct fetch URL based on the selected protocol, handling GitHub Enterprise Server URLs, SSH key-based authentication, and HTTPS token injection.

### State and Context Management

**[`src/state-helper.ts`](https://github.com/actions/checkout/blob/main/src/state-helper.ts)** persists the repository path between the pre-run and post-run phases using GitHub Actions state management. It exposes the `IsPost` flag and `RepositoryPath` variables that allow [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) to execute the correct logic in each phase.

**[`src/workflow-context-helper.ts`](https://github.com/actions/checkout/blob/main/src/workflow-context-helper.ts)** retrieves organization-level information required for self-hosted GitHub Enterprise Server scenarios, ensuring the action can resolve the correct API endpoints for enterprise installations.

### Public Interface ([`action.yml`](https://github.com/actions/checkout/blob/main/action.yml))

The [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) file defines the public contract for the GitHub Actions runtime, declaring all inputs (`ref`, `fetch-depth`, `submodules`, `sparse-checkout`, etc.) and outputs (`commit`, `ref`). This metadata file maps user-facing configuration options to the internal TypeScript logic.

## Data Flow Through the Architecture

The execution flow follows a strict pipeline:

1. **[`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts)** parses the run context and determines the execution phase
2. **[`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts)** validates environment variables and builds the settings object
3. **[`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts)** decides between Git clone or REST API download
4. **[`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)** executes the actual Git commands with retry logic
5. **[`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts)** and **[`src/url-helper.ts`](https://github.com/actions/checkout/blob/main/src/url-helper.ts)** provide authentication and URL resolution
6. **[`src/state-helper.ts`](https://github.com/actions/checkout/blob/main/src/state-helper.ts)** persists the repository path for post-run cleanup

## Common Configuration Patterns

Basic checkout using default settings:

```yaml
- uses: actions/checkout@v4

```

Shallow checkout of a specific branch:

```yaml
- uses: actions/checkout@v4
  with:
    ref: feature/my-branch
    fetch-depth: 1

```

Sparse checkout of specific directories:

```yaml
- uses: actions/checkout@v4
  with:
    sparse-checkout: |
      src
      docs
    sparse-checkout-cone-mode: true

```

Checkout of a private repository with authentication:

```yaml
- uses: actions/checkout@v4
  with:
    repository: my-org/private-repo
    token: ${{ secrets.PAT }}
    path: private-repo

```

## Summary

- **[`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts)** serves as the dual-phase entry point, dispatching to either checkout logic or cleanup routines based on state flags.
- **[`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts)** constructs the `IGitSourceSettings` object and validates all action inputs against the runner environment.
- **[`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts)** orchestrates the cloning workflow, handling branch resolution, submodules, and LFS initialization.
- **[`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)** abstracts the Git executable with version validation and high-level methods like `sparseCheckout()` and `lfsInstall()`.
- **[`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts)** manages temporary credentials, ensuring tokens are removed post-run unless `persist-credentials` is enabled.
- **[`src/state-helper.ts`](https://github.com/actions/checkout/blob/main/src/state-helper.ts)** maintains the repository path across the pre-run and post-run execution phases.

## Frequently Asked Questions

### What is the role of [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) in the actions/checkout architecture?

[`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) functions as the central dispatcher for both the pre-run and post-run phases. It registers the problem-matcher for Git error annotations, calls `inputHelper.getInputs()` to parse configuration, and invokes either `gitSourceProvider.getSource()` to clone the repository or `cleanup()` to remove temporary credentials based on the current execution phase.

### How does actions/checkout handle authentication for private repositories?

The [`src/git-auth-helper.ts`](https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts) file writes temporary credentials into the Git configuration—either embedding HTTPS tokens in the URL or configuring SSH keys and known hosts. During the post-run phase, the same helper removes these credentials unless the `persist-credentials` input is set to `true`, ensuring secrets do not remain in the workspace between jobs.

### What is the difference between [`git-source-provider.ts`](https://github.com/actions/checkout/blob/main/git-source-provider.ts) and [`git-command-manager.ts`](https://github.com/actions/checkout/blob/main/git-command-manager.ts)?

[`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) contains the business logic for repository acquisition, deciding whether to clone via Git or download via REST API, while [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts) provides the low-level interface to the Git executable. The provider uses the command manager to execute specific operations like fetch, checkout, and sparse-checkout configuration, keeping the command abstraction separate from the workflow orchestration.

### How does actions/checkout persist state between the pre-run and post-run phases?

The [`src/state-helper.ts`](https://github.com/actions/checkout/blob/main/src/state-helper.ts) file utilizes GitHub Actions state management to store the repository path and an `IsPost` flag during the initial run. When the post-run phase executes, [`src/main.ts`](https://github.com/actions/checkout/blob/main/src/main.ts) checks these state variables to locate the repository for cleanup operations and ensure temporary files and credentials are properly removed even if the job is cancelled or fails.