### Configuration Mapping Example

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Demonstrates how input parameters like 'files' are mapped to environment variables and then to CLI arguments.

```text
Input: files
  ↓ (to action.yml step 9)
  ↓
Env: CC_FILES
  ↓ (to codecov.sh)
  ↓
CLI args: --file ./coverage.xml --file ./coverage2.xml
```

--------------------------------

### Simple Usage Example

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/README.md

A basic example of how to use the codecov-action in a GitHub Actions workflow. It specifies the coverage files to upload and assigns a flag for categorization. The token is securely passed using GitHub secrets.

```yaml
- uses: codecov/codecov-action@v5
  with:
    files: ./coverage.xml
    flags: unittests
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Install CLI via Pip

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Installs the Codecov CLI using pip if CC_USE_PYPI is set to true. Exits if installation fails.

```bash
elif [ "$CC_USE_PYPI" == "true" ]; then
  if ! pip install "${CC_CLI_TYPE}..." ; then
    exit_if_error "Could not install via pypi."
  fi
```

--------------------------------

### Environment Variable Naming Convention Example

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/index.md

Illustrates the conversion pattern from action input names to environment variables. This is useful for understanding how inputs are exposed internally.

```markdown
Input name (snake_case) → CC_NAME (UPPER_SNAKE_CASE)
Example: fail_ci_if_error → CC_FAIL_ON_ERROR
```

--------------------------------

### Multi-Step Upload with Notifications Workflow

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This example demonstrates a sequential GitHub Actions workflow for uploading coverage, ensuring the commit is tracked with an empty upload if necessary, and then sending notifications.

```yaml
jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@main

      # Step 1: Upload coverage
      - uses: codecov/codecov-action@v5
        with:
          run_command: upload-coverage
          files: ./coverage.xml
          token: ${{ secrets.CODECOV_TOKEN }}

      # Step 2: Ensure commit tracked
      - uses: codecov/codecov-action@v5
        if: success()
        with:
          run_command: empty-upload
          token: ${{ secrets.CODECOV_TOKEN }}

      # Step 3: Send notifications
      - uses: codecov/codecov-action@v5
        if: success()
        with:
          run_command: send-notifications
          token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Environment Variable Mapping Example

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/configuration.md

Illustrates how action inputs are mapped to environment variables with a `CC_` prefix and uppercase snake_case.

```markdown
| Input | Environment Variable |
|---|---|
| `base_sha` | `CC_BASE_SHA` |
| `binary` | `CC_BINARY` |
| `codecov_yml_path` | `CC_YML_PATH` |
| `commit_parent` | `CC_PARENT_SHA` |
| `directory` | `CC_DIR` |
| `disable_file_fixes` | `CC_DISABLE_FILE_FIXES` |
| `disable_search` | `CC_DISABLE_SEARCH` |
| `disable_telem` | `CC_DISABLE_TELEM` |
| `dry_run` | `CC_DRY_RUN` |
| `env_vars` | `CC_ENV` |
| `exclude` | `CC_EXCLUDES` |
| `fail_ci_if_error` | `CC_FAIL_ON_ERROR` |
| `files` | `CC_FILES` |
| `flags` | `CC_FLAGS` |
| `force` | `CC_FORCE` |
| `git_service` | `CC_GIT_SERVICE` / `CC_SERVICE` |
| `gcov_args` | `CC_GCOV_ARGS` |
| `gcov_executable` | `CC_GCOV_EXECUTABLE` |
| `gcov_ignore` | `CC_GCOV_IGNORE` |
| `gcov_include` | `CC_GCOV_INCLUDE` |
| `handle_no_reports_found` | `CC_HANDLE_NO_REPORTS_FOUND` |
| `job_code` | `CC_JOB_CODE` |
| `name` | `CC_NAME` |
| `network_filter` | `CC_NETWORK_FILTER` |
| `network_prefix` | `CC_NETWORK_PREFIX` |
| `os` | `CC_OS` |
| `override_branch` | `CC_BRANCH` |
| `override_build` | `CC_BUILD` |
| `override_build_url` | `CC_BUILD_URL` |
| `override_commit` | `CC_SHA` |
| `override_pr` | `CC_PR` |
| `plugins` | `CC_PLUGINS` |
| `recurse_submodules` | `CC_RECURSE_SUBMODULES` |
| `report_code` | `CC_CODE` |
| `report_type` | `CC_REPORT_TYPE` |
| `root_dir` | `CC_NETWORK_ROOT_FOLDER` |
| `run_command` | `CC_RUN_CMD` |
| `skip_validation` | `CC_SKIP_VALIDATION` |
| `slug` | `CC_SLUG` |
| `swift_project` | `CC_SWIFT_PROJECT` |
| `token` | `CC_TOKEN` |
| `url` | `CC_ENTERPRISE_URL` |
| `use_legacy_upload_endpoint` | `CC_LEGACY` |
| `use_oidc` | `CC_USE_OIDC` |
| `use_pypi` | `CC_USE_PYPI` |
| `verbose` | `CC_VERBOSE` |
| `version` | `CC_VERSION` |
| `working-directory` | — 
```

--------------------------------

### Manually Specify Base SHA for pr-base-picking

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This example demonstrates how to manually specify the `base_sha` for the `pr-base-picking` command in GitHub Actions when automatic detection is insufficient.

```yaml
- uses: codecov/codecov-action@v5
  with:
    run_command: pr-base-picking
    base_sha: abc1234567890def1234567890def1234567890
    pr: 42
    slug: owner/repo
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Example GitHub Actions Workflow with Codecov

Source: https://github.com/codecov/codecov-action/blob/main/README.md

This workflow demonstrates setting up Python, generating a coverage report using pytest, and uploading it to Codecov. Ensure you have the CODECOV_TOKEN secret configured in your repository.

```yaml
name: Example workflow for Codecov
on: [push]
jobs:
  run:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    env:
      OS: ${{ matrix.os }}
      PYTHON: "3.10"
    steps:
      - uses: actions/checkout@main
      - name: Setup Python
        uses: actions/setup-python@main
        with:
          python-version: "3.10"
      - name: Generate coverage report
        run: |
          pip install pytest
          pip install pytest-cov
          pytest --cov=./ --cov-report=xml
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        with:
          directory: ./coverage/reports/
          env_vars: OS,PYTHON
          fail_ci_if_error: true
          files: ./coverage1.xml,./coverage2.xml,!./cache
          flags: unittests
          name: codecov-umbrella
          token: ${{ secrets.CODECOV_TOKEN }}
          verbose: true

```

--------------------------------

### Install GPG on macOS

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Installs GPG using Homebrew on macOS if it's not already found. Ensures Homebrew doesn't auto-update.

```bash
HOMEBREW_NO_AUTO_UPDATE=1 brew install gpg
```

--------------------------------

### Token Configuration: Action Input

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/configuration.md

Example of how to provide the Codecov token directly as an input parameter to the action in a GitHub Actions workflow.

```yaml
with:
  token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Retry Configuration Example

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

This snippet defines the retry settings for network operations, specifying the number of attempts and the delay between them. These settings are applied using flags like --retry and --retry-delay.

```bash
retry="--retry 5 --retry-delay 2"
```

--------------------------------

### Token Configuration: Environment Variable

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/configuration.md

Example of how to configure the Codecov token using the `CODECOV_TOKEN` environment variable within a GitHub Actions workflow.

```yaml
env:
  CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Example Workflow for Upload Coverage

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This YAML workflow demonstrates how to use the Codecov Action to upload coverage reports. It specifies the coverage file, flags, a custom name, and enables failure on error, requiring a Codecov token.

```yaml
- uses: codecov/codecov-action@v5
  with:
    files: ./coverage/report.xml
    flags: unittests
    name: coverage-report
    fail_ci_if_error: true
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Verify GPG Signature

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Verifies the integrity of the checksum file using the downloaded GPG signature. Requires gpg to be installed.

```bash
gpg --verify "${CC_FILENAME}.SHA256SUM.sig" "${CC_FILENAME}.SHA256SUM"
```

--------------------------------

### Get CLI Flag Name from Environment Variable

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Outputs the CLI flag name (prefixed with '--') if the corresponding CC_* environment variable is set. Use this to dynamically include flags in CLI commands.

```bash
k_arg "FILES"  # If CC_FILES is set, returns: --files
```

--------------------------------

### Initialize Wrapper Configuration Variables

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Sets default values for essential wrapper configuration variables like version, error handling, and command execution. Ensures consistent behavior by providing fallbacks.

```bash
CC_WRAPPER_VERSION="0.2.9"
CC_VERSION="${CC_VERSION:-latest}"
CC_FAIL_ON_ERROR="${CC_FAIL_ON_ERROR:-false}"
CC_RUN_CMD="${CC_RUN_CMD:-upload-coverage}"
CC_CLI_TYPE=${CC_CLI_TYPE:-"codecov-cli"}
```

--------------------------------

### Multi-Value Parameter Expansion

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Shows how comma-separated inputs for parameters like 'files' are expanded into multiple CLI flags.

```text
Input: files: "coverage1.xml,coverage2.xml"
  ↓
Env: CC_FILES="coverage1.xml,coverage2.xml"
  ↓
Loop: for file in $CC_FILES; do ... done
  ↓
CLI: --file coverage1.xml --file coverage2.xml
```

--------------------------------

### OS Detection Logic

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Illustrates the multi-step process the script uses to detect the operating system and architecture. This logic determines the correct OS value for subsequent operations.

```bash
1. Detect family: uname -s
   - darwin → macos
   - linux → linux
   - (other) → windows

2. If linux, check /etc/os-release
   - ID=alpine → alpine

3. If linux, detect architecture: arch
   - aarch64 → append -arm64
```

--------------------------------

### Import GPG Key

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Imports the Codecov GPG public key from Keybase into the GPG keyring. Uses curl to fetch the key and gpg to import it.

```bash
echo "$(curl -s https://keybase.io/codecovsecops/pgp_keys.asc)" | \
  gpg --no-default-keyring --import
```

--------------------------------

### Get Environment Variable Value for CLI Argument

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Outputs the value of a CC_* environment variable. Use this to dynamically provide values for CLI arguments.

```bash
v_arg "FILES"  # If CC_FILES="/path/to/file.xml", returns: /path/to/file.xml
```

--------------------------------

### Get Current Branch Name

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Retrieves the name of the current Git branch. This is used in conjunction with `git log` to define the range of commits to analyze for the changelog.

```bash
git branch --show-current
```

--------------------------------

### File Writing for CHANGELOG.md

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Demonstrates writing the complete, newly generated changelog content to the `CHANGELOG.md` file. The file is opened in write mode, overwriting any existing content.

```python
with open('CHANGELOG.md', 'w') as f:
    f.write('\n'.join(changelog))
```

--------------------------------

### Handle Pre-Downloaded Binary Path

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Checks if the CC_BINARY environment variable is set and if the specified file exists. If valid, it sets the CC_FILENAME and CC_COMMAND to the binary path, bypassing further validation.

```bash
if [ -n "$CC_BINARY" ]; then
  if [ -f "$CC_BINARY" ]; then
    CC_FILENAME=$CC_BINARY
    CC_COMMAND=$CC_BINARY
  else
    exit_if_error "Could not find binary file $CC_BINARY"
  fi
```

--------------------------------

### Execute pr-base-picking CLI Command

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This illustrates the CLI command for `pr-base-picking` when a slug is provided. It's useful for direct command-line usage or debugging.

```bash
codecov-cli pr-base-picking --slug owner/repo -t <redacted>
```

--------------------------------

### Run Changelog Script

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Command to execute the changelog update script. Ensure all requirements are met before running.

```bash
python changelog.py
```

--------------------------------

### Changelog Script Entry Point

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

The entry point for the changelog update script. Executes the `update_changelog` function when the script is run directly.

```python
if __name__=="__main__":
    update_changelog()
```

--------------------------------

### Construct Download URL

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Constructs the URL for downloading the Codecov CLI binary based on version, OS, and filename.

```bash
CC_URL="https://cli.codecov.io/${CC_VERSION}/${CC_OS}/${CC_FILENAME}"
```

--------------------------------

### OIDC Authentication Flow

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Explains the steps for OIDC authentication, from setting `use_oidc` to the CLI authenticating with the OIDC token.

```mermaid
graph TD
    A(use_oidc input = true)
    B(action.yml step 5 runs GitHub Script)
    C(core.getIDToken() returns OIDC token)
    D(action.yml step 6 prioritizes OIDC)
    E(CC_TOKEN = OIDC token)
    F(CLI authenticates via OIDC)

    A --> B --> C --> D --> E --> F
```

--------------------------------

### Custom Binary Acquisition

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Describes the flow when a custom binary path is provided, skipping download and validation steps.

```mermaid
graph TD
    A(binary input = "/path/to/codecov")
    B(codecov.sh step 2A (CLI Acquisition))
    C(File exists check passes)
    D(Skip download and validation)
    E(Use provided binary directly)
    F(CLI executes immediately)

    A --> B --> C --> D --> E --> F
```

--------------------------------

### Make Binary Executable

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Changes the permissions of the downloaded Codecov CLI binary to make it executable.

```bash
chmod +x "$CC_COMMAND"
```

--------------------------------

### Action Execution Steps Flowchart

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Visual representation of the 9 sequential steps executed by the action.

```text
┌─────────────────────────────────────────┐
│ 1. Check System Dependencies            │
│    (bash, curl, git, gpg)               │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│ 2. Display Action Version               │
│    (from src/version)                   │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│ 3. Set Safe Directory                   │
│    (git config for workspace)           │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│ 4. Detect Fork Context                  │
│    (GitHub event comparison)            │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│ 5. Retrieve OIDC Token (if enabled)     │
│    (GitHub OIDC provider)               │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│ 6. Resolve Authentication Token         │
│    (OIDC > env var > input)             │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│ 7. Override Branch for Forks            │
│    (if no token, use PR label)          │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│ 8. Set Commit & PR Info                 │
│    (from GitHub context)                │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│ 9. Execute Wrapper Script               │
│    (dist/codecov.sh with env vars)      │
└─────────────────────────────────────────┘
```

--------------------------------

### String Processing and SHA Extraction

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Illustrates capturing command output using `subprocess.run` and processing the stdout. It decodes the output and extracts the first 7 characters (short SHA) from each line.

```python
raw_commits = subprocess.run([...], capture_output=True)
commits = [line[:7] for line in raw_commits.stdout.decode('utf-8').split('\n')]
```

--------------------------------

### Execute empty-upload CLI Command

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This shows the underlying CLI command executed by the `empty-upload` workflow. It's useful for understanding the direct command-line interface.

```bash
codecov-cli empty-upload -t <redacted>
```

--------------------------------

### Verify Checksum

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Verifies the integrity of the downloaded binary against the checksum file. Tries both 'shasum' and 'sha256sum' commands.

```bash
shasum -a 256 -c "${CC_FILENAME}.SHA256SUM" || \
  sha256sum -c "${CC_FILENAME}.SHA256SUM"
```

--------------------------------

### Run pr-base-picking Command in GitHub Actions

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This snippet shows how to use the `pr-base-picking` command in GitHub Actions. It helps Codecov automatically determine the correct base commit for PR coverage analysis.

```yaml
- uses: codecov/codecov-action@v5
  with:
    run_command: pr-base-picking
    slug: owner/repo
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Download Binary with Curl

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Downloads the Codecov CLI binary using curl with retry logic for robustness. Retries up to 5 times with a 2-second delay between retries.

```bash
curl -O --retry 5 --retry-delay 2 "$CC_URL"
```

--------------------------------

### Codecov Action with OIDC Authentication

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Sets up the Codecov action to use OpenID Connect (OIDC) for authentication, which is a more secure alternative to using secrets. Requires 'id-token: write' permission.

```yaml
permissions:
  id-token: write

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@main
      - uses: codecov/codecov-action@v5
        with:
          use_oidc: true
```

--------------------------------

### Execute send-notifications CLI Command

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This illustrates the CLI command for `send-notifications` when a slug is provided. It's useful for direct command-line usage or debugging.

```bash
codecov-cli send-notifications --slug owner/repo -t <redacted>
```

--------------------------------

### Retrieve Actual Version

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Fetches the actual version of the Codecov CLI from the API for a given OS and version. Uses curl with retry and error handling.

```bash
v=$(curl --retry 5 --retry-delay 2 --retry-all-errors -s 
    "https://cli.codecov.io/api/${CC_OS}/${CC_VERSION}" 
    -H "Accept:application/json" | ... )
```

--------------------------------

### Run TypeScript/Jest tests

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/api-reference-calculator.md

Execute tests for TypeScript projects using Jest. Use specific file paths to run individual test suites.

```bash
npm test demo/calculator/calculator.test.ts
npm test demo/coverage-test/coverage.test.ts
```

--------------------------------

### Run Python/Pytest tests

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/api-reference-calculator.md

Execute tests for Python projects using Pytest. Specify the test file path to run the tests.

```bash
pytest app/test_calculator.py
```

--------------------------------

### Project Structure

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Overview of the codecov-action project's directory structure.

```tree
codecov-action/
├── .github/              # GitHub-specific files
├── .gitmodules          # Git submodule configuration
├── action.yml           # GitHub Action definition
├── app/                 # Python demo application
│   ├── __init__.py
│   ├── calculator.py    # Simple calculator class
│   ├── test_calculator.py
│   └── requirements.txt
├── demo/                # TypeScript demo applications
│   ├── calculator/      # Calculator demo
│   │   ├── calculator.ts
│   │   └── calculator.test.ts
│   └── coverage-test/   # Coverage demo
│       ├── coverage.ts
│       └── coverage.test.ts
├── dist/                # Compiled/distribution files
│   └── codecov.sh       # Main wrapper script
├── hooks/               # Git hooks
├── src/                 # Source files
│   ├── scripts/         # Scripts directory
│   └── version          # Version file
├── CHANGELOG.md         # Version history
├── CONTRIBUTING.md      # Contribution guidelines
├── install.sh           # Installation script
├── Makefile             # Build targets
├── LICENSE              # MIT License
├── README.md            # Documentation
└── changelog.py         # Changelog generation utility
```

--------------------------------

### Token Resolution Flow

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Illustrates the precedence logic for resolving the authentication token, prioritizing OIDC, CODECOV_TOKEN, and then the token input.

```mermaid
graph TD
    A[GitHub workflow context]
    B(OIDC)
    C(CODECOV_TOKEN)
    D(token input)
    E(Precedence logic
    (action.yml step 6))
    F(CC_TOKEN)
    G(Passed to CLI)
    H(Codecov API authentication)

    A --> B
    A --> C
    A --> D
    B --> E
    C --> E
    D --> E
    E --> F --> G --> H
```

--------------------------------

### Codecov Action with Detailed Configuration

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Configures the Codecov action with specific options for coverage files, flags, build name, verbosity, and error handling. Requires a CODECOV_TOKEN secret.

```yaml
- uses: actions/checkout@main
- uses: codecov/codecov-action@v5
  with:
    files: ./coverage/report.xml
    flags: unittests
    name: codecov-upload
    verbose: true
    fail_ci_if_error: true
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Git Log Command for Version Comparison

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Retrieves commit hashes and subjects between the previous and current version. Used to identify changes for the changelog.

```bash
git log {previous}..{current_branch} --oneline
```

--------------------------------

### Fork Pull Request Handling

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Details the process for handling fork pull requests, including detecting CC_FORK, overriding the branch, and enabling tokenless uploads.

```mermaid
graph TD
    A[GitHub event has fork PR]
    B(action.yml step 4 detects CC_FORK=true)
    C(No token available (typical for forks))
    D(action.yml step 7 overrides branch)
    E(CC_BRANCH = github.event.pull_request.head.label)
    F(codecov.sh passes branch to CLI)
    G(CLI enables tokenless upload)

    A --> B --> C --> D --> E --> F --> G
```

--------------------------------

### Set Authentication Token (Bash)

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Resolves and sets the authentication token for Codecov. It prioritizes OIDC tokens, then environment variables (CODECOV_TOKEN), and finally input parameters. The token is stored in the CC_TOKEN environment variable for subsequent steps.

```bash
CC_TOKEN=$CC_OIDC_TOKEN
```

```bash
CC_TOKEN=$INPUT_CODECOV_TOKEN
```

```bash
CC_TOKEN=$(echo "$INPUT_TOKEN" | tr -d '\n')
```

--------------------------------

### Codecov Action with OIDC Authentication

Source: https://github.com/codecov/codecov-action/blob/main/README.md

Use OpenID Connect (OIDC) for authentication with the Codecov action, disabling the need for a manual upload token. Requires write permissions for 'id-token'.

```yaml
- uses: codecov/codecov-action@v5
  with:
    use_oidc: true
```

--------------------------------

### Wrapper Script Environment Variables Table

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/configuration.md

Lists environment variables used internally by the wrapper script, including their type, default value, and description.

```markdown
| Variable | Type | Default | Description |
|---|---|---|---|
| `CC_WRAPPER_VERSION` | string | `0.2.9` | Version of the wrapper script. |
| `CC_CLI_TYPE` | string | `codecov-cli` | Type of CLI to use. Options: `codecov-cli`, `sentry-prevent-cli`. |
| `CC_FAIL_ON_ERROR` | boolean | `false` | Exit with error code on failure. |
| `CC_RUN_CMD` | string | `upload-coverage` | The CLI command to execute. |
| `CC_SKIP_VALIDATION` | boolean | `false` | Skip GPG signature verification. |
| `CC_USE_PYPI` | boolean | `false` | Install CLI from PyPI instead of cli.codecov.io. |
| `CC_TOKEN_VAR` | string | — | Name of environment variable containing the token (e.g., `CODECOV_TOKEN`). |
| `CC_DOWNLOAD_ONLY` | boolean | `false` | Only download the CLI binary, do not execute. |
| `CC_AUTO_LOAD_PARAMS_FROM` | string | — | Path to a file containing additional parameters. |
| `CC_BINARY_LOCATION` | string | — | Directory to move downloaded binary to. 
```

--------------------------------

### Move Binary to Location

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Moves the downloaded Codecov CLI binary to a specified location if CC_BINARY_LOCATION is set. Creates the directory if it doesn't exist.

```bash
mkdir -p "$CC_BINARY_LOCATION" && mv "$CC_FILENAME" $_
```

--------------------------------

### Instantiate TypeScript Calculator

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/api-reference-calculator.md

Creates a new instance of the TypeScript Calculator class. No parameters are required for instantiation.

```typescript
import Calculator from './calculator';

const calc = new Calculator();
```

--------------------------------

### Final Command Execution

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

This shows the structure of the final command executed by the wrapper script, including arguments and token handling. Behavior on failure depends on the CC_FAIL_ON_ERROR setting.

```bash
$CC_COMMAND \
  ${CC_CLI_ARGS[*]} \
  ${CC_RUN_CMD} \
  ${token_arg[*]} \
  "${CC_ARGS[@]}"
```

--------------------------------

### Download Checksums and Signatures

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Downloads the checksum and signature files for integrity verification. Uses curl with the -s flag for silent operation.

```bash
curl -Os ... "${sha_url}"
curl -Os ... "${sha_url}.sig"
```

--------------------------------

### JSON Parsing Implementation Detail

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Demonstrates parsing JSON output from a command using Python's built-in `json` module. It specifically handles the case where the output is expected to be an array with a single element.

```python
commit_details = json.loads(commit_details)[0]
```

--------------------------------

### Read Action Version

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Reads the action version from the src/version file. This is useful for scripts that need to know the current version of the action.

```python
with open('src/version', 'r') as f:
    version = f.read()
```

--------------------------------

### Handle Invalid Run Command

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This snippet shows how the wrapper script handles an invalid `run_command` by exiting with an error. It's used when an unrecognized command is specified.

```bash
exit_if_error "Invalid run command specified: $CC_RUN_CMD"
exit
```

--------------------------------

### Upload Coverage Command Execution

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This command executes the `upload-coverage` functionality of the Codecov CLI. It specifies the coverage file, a flag for grouping metrics, a custom name for the report, enables the fail-on-error option, and includes a redacted token.

```bash
codecov-cli upload-coverage \
  --file ./coverage/report.xml \
  --flag unittests \
  --name coverage-report \
  --fail-on-error \
  -t <redacted>
```

--------------------------------

### Codecov Action with Environment Variable Token

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Authenticates the Codecov action using an environment variable for the token. This is an alternative to passing the token directly in the 'with' block.

```yaml
- uses: actions/checkout@main
- uses: codecov/codecov-action@v5
  env:
    CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Run empty-upload Command in GitHub Actions

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This snippet demonstrates how to use the `empty-upload` command within a GitHub Actions workflow. It ensures commits without coverage data are still tracked on Codecov.

```yaml
- uses: codecov/codecov-action@v5
  with:
    run_command: empty-upload
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Error Propagation Strategy

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Outlines how system errors are handled based on the `CC_FAIL_ON_ERROR` setting, determining job failure or success.

```text
System error (dependency missing, file not found, etc.)
        ↓
     If CC_FAIL_ON_ERROR=true:
        exit with code 1 → Job fails
     If CC_FAIL_ON_ERROR=false:
        log error, continue → Job succeeds
```

--------------------------------

### Environment Variable Flow

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Traces the path of environment variables from GitHub workflow inputs to Codecov CLI arguments.

```text
GitHub Workflow Inputs
        ↓
action.yml step environment blocks
        ↓
Bash step: Build environment vars
        ↓
CC_* environment variables
        ↓
dist/codecov.sh
        ↓
CC_CLI_ARGS and CC_ARGS arrays
        ↓
CLI command-line arguments
        ↓
Codecov CLI execution
```

--------------------------------

### GitHub CLI Command for PR Lookup

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Searches for a merged Pull Request associated with a specific commit SHA. It outputs details like author, number, title, and URL in JSON format.

```bash
gh pr list \
  --json author,number,title,url \
  --search "{commit_sha}" \
  --state merged
```

--------------------------------

### Output Message with Color

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Outputs a message to standard output, supporting ANSI color codes for formatted text. Use this for displaying status or command information.

```bash
say "$g==>$x Running $CC_RUN_CMD"  # Green "==>" followed by command name
```

--------------------------------

### Codecov Action for Multiple Coverage Files

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Configures the Codecov action to upload multiple coverage report files. Files are specified as a comma-separated string. Requires a CODECOV_TOKEN secret.

```yaml
- uses: codecov/codecov-action@v5
  with:
    files: ./coverage1.xml,./coverage2.xml,./coverage3.xml
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Basic Codecov Action Usage

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Integrates the Codecov action into a GitHub Actions workflow. Requires a CODECOV_TOKEN secret for authentication.

```yaml
- uses: actions/checkout@main
- uses: codecov/codecov-action@v5
  with:
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Access Action Version via Bash

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Accesses the action version stored in src/version using the cat command. This is a common way to retrieve the version in shell scripts.

```bash
cat ${GITHUB_ACTION_PATH}/src/version
```

--------------------------------

### Codecov Action Execution Flow Diagram

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/architecture-and-flow.md

Visual representation of the 9-step process within the Codecov action, from workflow trigger to error handling.

```mermaid
graph TD
    A[GitHub Actions Workflow Triggered]
    B(action.yml
    9-step process)
    C(Build Environment Variables
    - CC_* env vars from inputs
    - GitHub context variables
    - Token resolution)
    D(dist/codecov.sh
    Wrapper Script)
    E(CLI Acquisition Strategy Selection
    1. Use CC_BINARY if provided
    2. Use PyPI install if requested
    3. Download & verify from cli.io)
    F(Integrity Validation (if enabled)
    - Import GPG key from Keybase
    - Verify signature
    - Verify SHA256 checksum)
    G(Build CLI Arguments
    - From CC_* environment variables
    - Command-specific args
    - Authentication token)
    H(Execute Codecov CLI
    ./codecov upload-coverage [args]
    ./codecov empty-upload [args]
    ./codecov pr-base-picking [args]
    ./codecov send-notifications [args])
    I(CLI Operations
    - Parse coverage files
    - Collect Git metadata
    - Create/update commit in Codecov
    - Upload coverage report
    - Send notifications)
    J(Error Handling
    - Return exit code
    - Conditional job failure based on
    fail_ci_if_error setting)

A --> B --> C --> D --> E --> F --> G --> H --> I --> J
```

--------------------------------

### Python Calculator Class

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/api-reference-calculator.md

Provides static methods for basic arithmetic operations using Python.

```APIDOC
## Class: Calculator

A simple arithmetic calculator class for testing coverage in Python.

### Static Method: add

```python
Calculator.add(x, y)
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `x` | number | First number |
| `y` | number | Second number |

**Return Type:** `float`

**Returns:** Sum of x and y as float

**Description:** Adds two numbers and returns the result. Values are always converted to float in the return.

### Static Method: subtract

```python
Calculator.subtract(x, y)
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `x` | number | Minuend (first number) |
| `y` | number | Subtrahend (second number) |

**Return Type:** `float`

**Returns:** Difference of x minus y as float

**Description:** Subtracts the second number from the first and returns the result as float.

### Static Method: multiply

```python
Calculator.multiply(x, y)
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `x` | number | First number (multiplicand) |
| `y` | number | Second number (multiplier) |

**Return Type:** `float`

**Returns:** Product of x and y as float

**Description:** Multiplies two numbers and returns the result as float.

### Static Method: divide

```python
Calculator.divide(x, y)
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `x` | number | Dividend |
| `y` | number | Divisor |

**Return Type:** `float`

**Returns:** Quotient of x divided by y as float

**Description:** Divides the first number by the second and returns the result as float. Handles division by zero by raising an exception.
```

--------------------------------

### Retrieve OIDC Token

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Retrieves an OIDC token from GitHub for authentication with Codecov. This step only runs if OIDC is enabled and the action is not executing within a fork. Requires workflow permissions for id-token: write.

```javascript
if (process.env.CC_USE_OIDC === 'true' && process.env.CC_FORK != 'true') {
  const id_token = await core.getIDToken(process.env.CC_OIDC_AUDIENCE)
  return id_token
}
```

--------------------------------

### Configure Git Safe Directory

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Configures Git's safe directory setting to allow the current workspace, preventing security errors. This step runs conditionally if inputs.disable_safe_directory is not set to 'true'.

```bash
git config --global --add safe.directory "${{ github.workspace }}"
git config --global --add safe.directory "$GITHUB_WORKSPACE"
```

--------------------------------

### Generate Python coverage reports

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/api-reference-calculator.md

Generate code coverage reports for Python projects using Pytest. Use the --cov flag followed by the package name and test file path.

```bash
pytest --cov=app app/test_calculator.py
```

--------------------------------

### Generate TypeScript coverage reports

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/api-reference-calculator.md

Generate code coverage reports for TypeScript projects using Jest. Append the --coverage flag to the test command.

```bash
npm test -- --coverage demo/calculator/calculator.test.ts
```

--------------------------------

### Changelog List Data Structure

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Represents the structure of the generated changelog content, including version headers, 'What's Changed' sections, and full changelog links.

```python
changelog = [
    f"## v{version}",
    "### What's Changed",
    "* PR Title 1 by @author1 in URL1",
    "* PR Title 2 by @author2 in URL2",
    "",
    "**Full Changelog**: https://github.com/codecov/codecov-action/compare/{previous}..v{version}",
    # ... rest of previous CHANGELOG.md content ...
]
```

--------------------------------

### Basic Codecov Action Integration

Source: https://github.com/codecov/codecov-action/blob/main/README.md

Integrate the Codecov action into your workflow. Ensure actions/checkout is run first. The token is required and can be stored as a secret.

```yaml
steps:
  - uses: actions/checkout@main
  - uses: codecov/codecov-action@v5
    with:
      fail_ci_if_error: true # optional (default = false)
      files: ./coverage1.xml,./coverage2.xml # optional
      flags: unittests # optional
      name: codecov-umbrella # optional
      token: ${{ secrets.CODECOV_TOKEN }}
      verbose: true # optional (default = false)
```

--------------------------------

### Codecov Action with Custom Working Directory

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Specifies a custom working directory for the Codecov action. This is useful when the coverage reports are not located in the root of the repository.

```yaml
- uses: codecov/codecov-action@v5
  with:
    working-directory: ./subproject
```

--------------------------------

### Codecov Action for Enterprise Instance

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/github-action-interface.md

Configures the Codecov action to upload coverage to a self-hosted enterprise instance of Codecov. Requires the enterprise URL and a CODECOV_TOKEN secret.

```yaml
- uses: codecov/codecov-action@v5
  with:
    url: https://codecov.enterprise.example.com
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Codecov Action with Environment Variable Token

Source: https://github.com/codecov/codecov-action/blob/main/README.md

Configure the Codecov action to use an environment variable for the upload token. This is an alternative to passing the token directly in the 'with' block.

```yaml
steps:
  - uses: actions/checkout@main
  - uses: codecov/codecov-action@v5
    with:
      fail_ci_if_error: true # optional (default = false)
      files: ./coverage1.xml,./coverage2.xml # optional
      flags: unittests # optional
      name: codecov-umbrella # optional
      verbose: true # optional (default = false)
    env:
      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Run send-notifications Command in GitHub Actions

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/run-commands-reference.md

This snippet shows how to use the `send-notifications` command in GitHub Actions. It sends coverage status notifications without uploading new reports, assuming data has already been uploaded.

```yaml
- uses: codecov/codecov-action@v5
  with:
    run_command: send-notifications
    slug: owner/repo
    token: ${{ secrets.CODECOV_TOKEN }}
```

--------------------------------

### Deduplication Logic using Python Set

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

Shows how a Python set is used to ensure that each Pull Request is added to the changelog only once. It checks if a PR number already exists in the set before adding it.

```python
if commit_details['number'] in prs:
    continue
prs.add(commit_details['number'])
```

--------------------------------

### Calculator.divide

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/api-reference-calculator.md

Divides the first number by the second and returns the result. Handles division by zero by returning an error message string.

```APIDOC
## Calculator.divide

### Description
Divides the first number by the second and returns the result. Returns an error message string if division by zero is attempted.

### Method Signature
`Calculator.divide(x, y)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **x** (number) - Required - Dividend (first number)
- **y** (number) - Required - Divisor (second number)

### Request Example
```python
result = Calculator.divide(10, 2)  # result: 5.0
error = Calculator.divide(10, 0)   # result: 'Cannot divide by 0'
```

### Response
#### Success Response
- **result** (float or str) - The result of the division or an error message string.

#### Response Example
```json
{
  "result": 5.0
}
```

```json
{
  "result": "Cannot divide by 0"
}
```

### Throws/Returns
- Returns error message string on division by zero (does not raise exception)
```

--------------------------------

### Coverage.fully_covered

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/api-reference-calculator.md

Returns true unconditionally. This method is fully covered by tests.

```APIDOC
## Coverage.fully_covered

### Description
Returns true unconditionally. This method is fully covered by tests.

### Method Signature
`fully_covered(): boolean`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
None

### Request Example
```typescript
const cov = new Coverage();
const result = cov.fully_covered();  // result: true
```

### Response
#### Success Response
- **result** (boolean) - `true`

#### Response Example
```json
{
  "result": true
}
```

### Coverage Status
Fully covered (100%)
```

--------------------------------

### Convert String to Lowercase Flag Format

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Converts a string to lowercase, removes the 'CC_' prefix, and replaces underscores with hyphens. This is used to generate CLI flag names from environment variables.

```bash
lower "CC_SKIP_VALIDATION"  # Returns: skip-validation
```

--------------------------------

### Write Boolean CLI Argument

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/wrapper-script-reference.md

Outputs a CLI flag (without a value) if a specified boolean environment variable is set to 'true' or '1'. This is useful for flags that only indicate presence or absence.

```bash
write_bool_args CC_FAIL_ON_ERROR  # If true, returns: -fail-on-error
```

--------------------------------

### Update Changelog Function

Source: https://github.com/codecov/codecov-action/blob/main/_autodocs/utility-scripts.md

The main function to update the CHANGELOG.md file. It reads version information, fetches commit and PR data, and overwrites the changelog.

```python
def update_changelog()
```