Getting Started

Secure your CI/CD pipelines in minutes with this comprehensive guide to Pinner.

Copied to clipboard!

1 Installation

Choose the installation method that best fits your environment.

Shell (macOS & Linux)

curl -LsSf https://raw.githubusercontent.com/ffalcinelli/pinner/main/install.sh | sh

PowerShell (Windows)

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/ffalcinelli/pinner/main/install.ps1 | iex"

Cargo (Rust)

cargo install pinner

2 Pin Your First Workflow

Navigate to your repository and run the pin command. By default, Pinner looks for files in .github/workflows/.

$ pinner pin

Searching for workflows in .github/workflows/...

Found 2 workflow files.

actions/checkout@v4 -> actions/checkout@8f4b7f84... # v4

Successfully pinned 3 actions! ✅

Tip: Use --dry-run to see changes without writing to files.

3 Security Scan & Vetting

Audit your dependencies for vulnerabilities. Pinner queries the OpenSSF OSV database for both current pinned hashes and proposed upgrade candidates, and executes Sigstore/Cosign signature/provenance checks on OCI container images automatically. Run the scan command to inspect your dependencies:

$ pinner scan

Scanning dependencies with OSV database...

✔ Clean Dependencies:

actions/checkout@8f4b7f84... (Upgrade candidate: df4cb1c0... # v6.0.3)

alpine@sha256:12345... (Upgrade candidate: sha256:67890...)

Select clean dependencies to add to the vetted whitelist in .pinner.toml: [actions/checkout@8f4b7f84..., actions/checkout@df4cb1c0...]

This adds vetted hashes to your whitelist in .pinner.toml. When proposing upgrades or pinning, Pinner displays visual feedback (e.g. [✓ vetted]) to ensure supply-chain integrity.

4 Supported Platforms & Forges

Pinner is designed for multi-forge environments and enterprise setups.

Forge API Environment Variable Default URL
GitHub GITHUB_TOKEN https://api.github.com
GitLab GITLAB_TOKEN https://gitlab.com
Bitbucket BITBUCKET_TOKEN https://api.bitbucket.org/2.0
Forgejo/Gitea FORGEJO_TOKEN https://codeberg.org
Azure Marketplace GITHUB_TOKEN Monorepo Mapping
AWS ECR PINNER_OCI_PASSWORD Private Registries
CircleCI CIRCLECI_TOKEN Docker Image Pinning

5 Configuration File

Create a .pinner.toml file in your repository root to customize behavior globally. 

# List of actions to ignore during pinning/upgrading
ignore = ["actions/checkout", "my-org/private-action"]

# Number of concurrent API requests (default: 10)
concurrency = 5

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

6 Verify in CI

Prevent unpinned actions from being merged into your codebase by adding Pinner to your CI pipeline. You can use the native GitHub Action: 

name: Pinning Check
on: [pull_request]

jobs:
  verify-pinning:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # v4
      - name: Verify Pinning
        uses: ffalcinelli/pinner/action@main
        with:
          command: 'verify'

Pinnerception Warning Recursive

Remember to pin the pinner! Trusting a security tool to verify your pinned dependencies using a mutable tag is like hiring a security guard who leaves the keys under the doormat. If we didn't pin the pinner, who would pin the pinner's pinners? (Warning: may cause mild existential dread or recursive loops in your CI logs).

Alternatively, you can install the CLI tool directly: 

name: Pinning Check
on: [pull_request]

jobs:
  verify-pinning:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3 # v4
      - name: Install Pinner
        run: curl -LsSf https://raw.githubusercontent.com/ffalcinelli/pinner/main/install.sh | sh
      - name: Verify Pinning
        run: pinner verify

7 Shell Completion

Enhance your terminal experience by generating tab-completion scripts for your favorite shell.

Bash

pinner generate-completion bash > /etc/bash_completion.d/pinner

Zsh

pinner generate-completion zsh > "${fpath[1]}/_pinner"

Fish

pinner generate-completion fish > ~/.config/fish/completions/pinner.fish

Next Steps