Configuration & Options - Pinner

# Configuration & Options

A comprehensive guide to CLI flags, environment variables, and the `.pinner.toml` configuration file.

## Global Options

These options can be used with any subcommand to modify Pinner's behavior.

`-w, --workflows <PATH>` Default: GitHub/GitLab/etc paths

Specify workflow files or directories to process. Can be used multiple times.

`-y, --yes` Flag

Automatically confirm all replacements without prompting. Ideal for non-interactive environments.

`-d, --dry-run` Flag

Print what would be changed without actually modifying any files.

`--format <TYPE>` Values: text, json, markdown

Output results in the specified format. `--json` is a deprecated alias for `--format json`.

`--concurrency <NUM>` Default: 10

Number of concurrent API requests to make. Increase for large projects, decrease to avoid rate limits.

`--ignore <PATTERN>` Multiple

Actions or images to ignore (e.g., "actions/checkout"). Can be used multiple times.

## Subcommands

### pin

Scans your workflows and replaces all mutable tags with immutable commit SHAs. This is the primary command for securing your supply chain.

### upgrade

Updates pinned actions to their latest versions based on the selected `--upgrade-strategy`.

Always review changes after an upgrade to maintain security.

### verify

Checks if all actions in your workflows are pinned. Returns a non-zero exit code if unpinned actions are found. Perfect for CI/CD.

### set <ACTION> <HASH>

Forcibly sets a specific action to a provided hash across all matching occurrences in your workflows.

### generate-completion <SHELL>

Generates shell completion scripts for Bash, Zsh, Fish, Powershell, or Elvish.

## Environment Variables

Pinner automatically reads these variables for authentication and configuration.

Variable | Description | Default
--- | --- | ---
`GITHUB_TOKEN` | Auth token for GitHub API | -
`GITLAB_TOKEN` | Auth token for GitLab API | -
`BITBUCKET_TOKEN` | Auth token for Bitbucket API | -
`FORGEJO_TOKEN` | Auth token for Forgejo/Gitea API | -
`GITHUB_URL` | Custom GitHub API URL | https://api.github.com
`OCI_USERNAME` | Username for OCI Registries | -
`OCI_PASSWORD` | Password for OCI Registries | -

## Configuration File

Create a `.pinner.toml` file in your repository root to persist settings and share them with your team.

### Example .pinner.toml

    # Actions to exclude from processing
    ignore = ["actions/checkout", "my-org/private-repo"]

    # Execution settings
    concurrency = 5
    format = "text"

    # API URL overrides (for Enterprise)
    github_url = "https://github.mycompany.com/api/v3"
    gitlab_url = "https://gitlab.mycompany.com/api/v4"

    # Upgrade strategy
    upgrade_strategy = "major"