Getting Started with Pinner - Secure Your CI/CD Workflows

# 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 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.