Getting Started with Pinner - Secure Your CI/CD Workflows

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 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
OCI / Docker	`OCI_USERNAME`, `OCI_PASSWORD`	Multiple Registries

4 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"

5 Verify in CI

Prevent unpinned actions from being merged into your codebase by adding Pinner to your CI pipeline.

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

6 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

Learn about Upgrades: Use pinner upgrade to move to newer versions.
Security Note: Automatic upgrades can undermine your security. Use upgrade as an intentional step followed by a review to ensure you are only running vetted code.
API Reference: Check out the Rust API documentation for library usage.