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: Platform standard 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 (CI).

-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. markdown format is ideal for integration in PR comments.

--concurrency <NUM> Default: 10

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

--ignore <PATTERN> Multiple

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

--no-cache Flag | Conflicts with --cache-ttl

Disable persistent disk caching (cacache) and memory caching completely for this run. Forces fresh remote requests.

--cache-ttl <SECONDS> Default: 3600 | Conflicts with --no-cache

Set the cache Time-To-Live (TTL) in seconds. Cached entries older than this duration are automatically invalidated.

--offline Flag | Conflicts with --check-osv

Force offline mode, preventing any network requests. Only cached dependencies can be resolved. Fails on cache misses.

Subcommands

pin

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

upgrade

Updates pinned dependencies to newer versions based on the subcommand-specific --upgrade-strategy option.

Options:
  • --upgrade-strategy <STRATEGY>: Select bump strategy (latest, major, minor, commit).
  • -i, --interactive: Prompt and select upgrades individually.
Always review upgraded hashes to maintain security.

verify

Checks if all actions and images are pinned. Returns a non-zero exit code if unpinned dependencies are found. Perfect for CI/CD environments.

Options:
  • --check-osv: Query OpenSSF OSV to fail validation if any dependency hash has known vulnerabilities (requires online connection).
  • --strict: Fail validation if any dependency is not explicitly added to the vetted whitelist in .pinner.toml.

set <ACTION> <HASH>

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

install-hook

Installs a git pre-commit hook in your local repository that automatically runs pinner verify before every commit.

init

Automatically initializes a .pinner.toml configuration file for your repository with sensible defaults.

export-sbom

Generates and exports a Software Bill of Materials (SBOM) for all actions and container images used in your workflows.

scan

Queries OpenSSF OSV for vulnerabilities, performs Cosign provenance verification for OCI images, and prompts to save vetted whitelists and compromised blacklists in `.pinner.toml`.

Supports the --upgrade-strategy flag to scan candidates.

generate-completion [SHELL]

Generates shell completion scripts (Bash, Zsh, Fish, Powershell, Elvish). If the shell parameter is omitted, Pinner automatically detects your active shell environment.

Environment Variables

Pinner automatically reads these variables for authentication, caching overrides, and API configurations.

Authentication & APIs

Variable Description
GITHUB_TOKEN API authentication token for GitHub (bypasses low rate-limits)
GITLAB_TOKEN Auth token for GitLab API access
BITBUCKET_TOKEN Auth token for Bitbucket API access
FORGEJO_TOKEN Auth token for Forgejo/Gitea instances
CIRCLECI_TOKEN Token for CircleCI GraphQL API orb queries
PINNER_OCI_USERNAME Username for OCI Registries (use AWS for AWS ECR)
PINNER_OCI_PASSWORD Password or login token for OCI Registries authentication

Configuration Overrides

Variable Description
PINNER_NO_CACHE Set to true to disable persistent disk caching (caches are bypassed).
PINNER_CACHE_TTL Configure custom cache TTL duration in seconds.
PINNER_CONCURRENCY Override the number of concurrent API requests.
PINNER_IGNORE Override the list of ignored actions (comma-separated).
PINNER_GITHUB_URL Override default GitHub API URL. Also available for GitLab, Bitbucket, Forgejo, and CircleCI.

Cloud Provider Resolution

AWS ECR

To resolve private OCI digests from AWS ECR, pass the login token: 

PINNER_OCI_USERNAME=AWS \
PINNER_OCI_PASSWORD=$(aws ecr get-login-password) \
pinner pin

Azure Marketplace

Tasks are automatically resolved to the microsoft/azure-pipelines-tasks monorepo to safely query and map release commit hashes.

CircleCI Orbs

Pinner supports Docker images inside CircleCI configs. CircleCI Orbs use semantic version routing and are not hash-pinned.

Configuration File

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

Example .pinner.toml

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

# Execution and Caching settings
concurrency = 5
no_cache = false
cache_ttl = 3600 # Cache TTL in seconds

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

# Whitelist of vetted dependency hashes/references
vetted = [
    # Plain string format
    "actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332",

    # Structured format with original tag and insertion timestamp
    { ref = "actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10", tag = "v6.0.3", timestamp = "2026-06-18T15:28:25Z" }
]

# Blacklist of compromised dependency hashes/references
compromised = [
    "actions/checkout@badhash1234567890badhash1234567890bad",
    { ref = "actions/checkout@evilhash1234567890evilhash1234567890bad", tag = "v3.1.0", timestamp = "2026-06-18T15:28:25Z" }
]

# Disable visual security feedback (default: false)
no_security_feedback = false

Global Configuration Hierarchy

Pinner automatically aggregates whitelists and blacklists from standard configuration paths. Locations checked (from lowest to highest precedence):

Local Precedence Rules: A project-level .pinner.toml serves as a strict override. If a dependency reference is marked vetted locally, it overrides global compromised flags, and if marked compromised locally, it overrides global vetted entries.