CI and pull requests

There are two ways to put PkgFire in front of a team: a check on every pull request, connected in the dashboard, and the CLI in a CI job. They can be used together.

Pull request checks

PkgFire reads the lockfiles a pull request changes, at the exact base and head commits, and reports a verdict on the pull request. Nothing runs in your CI and no repository code is executed: only the dependency files are read.

Connect a repository under Settings → Connections in the dashboard. Only an account owner can connect one.

• GitHub. Choose *Connect GitHub*, install the PkgFire app on the repositories you want, then pick a repository and the directory holding its lockfile. Only repositories you administer are offered.
• Forgejo, Gitea and Codeberg. Enter the instance's https address and an access token with read:user, write:repository and write:issue. PkgFire lists the repositories that token's user administers, and creates a pull request webhook on the one you choose. Disconnecting removes the webhook again.

What a pull request gets:

• A check (GitHub) or a commit status (Forgejo and Gitea) on the head commit. ALLOW passes. BLOCK fails. WARN is neutral on GitHub, so it does not fail a required check, and a warning on Forgejo and Gitea. A check that could not finish, or could not reserve credits, asks for attention and never passes.
• A pull request is judged on what it changes. Findings on packages it did not add, upgrade, downgrade or re-point are listed as already on the base branch and do not decide its verdict. Malware, your always-block list, an invalid registry signature and a provenance mismatch count on every package regardless.
• A summary listing the changed packages with their verdicts and reasons. Text taken from a registry is escaped, so a package cannot plant links or mentions in it.
• A pull request that adds the first lockfile has every package checked as new. One that changes no lockfile is not checked.

Checks run when a pull request is opened, reopened, updated or marked ready for review. Connecting a repository does not check pull requests that are already open.

A pull request check is charged like any other scan: one credit for every package in the head lockfile, not only the changed ones, because every package is checked. Pull request checks and scheduled re-scans stay inside the account's limits for automatic checks. See Pricing.

The CLI in a CI job

Any pipeline that can run a shell can run PkgFire. It needs an API key, kept as a secret, and the service address:

PKGFIRE_API_KEY=<your key> PKGFIRE_API_URL=https://pkgfire.org pkgfire scan .

pkgfire scan reads the lockfile already committed in the checkout. It installs nothing and runs no package code, so it is safe to run before any dependency installation. The project is named from the checkout's git remote, so no --project is needed.

A GitHub Actions job that fails on a BLOCK or an error and lets a WARN through:

name: Dependency firewall
on:
  pull_request:
  push:
    branches: [main]

jobs:
  pkgfire:
    runs-on: ubuntu-latest
    env:
      PKGFIRE_API_URL: https://pkgfire.org
      PKGFIRE_API_KEY: ${{ secrets.PKGFIRE_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL "$PKGFIRE_API_URL/install.sh" | sh
      - run: pkgfire scan . || [ $? -eq 1 ]

The same in a GitLab CI or Forgejo Actions job, or any other runner, is the same two commands: install the CLI, then pkgfire scan .. Drop || [ $? -eq 1 ] to fail on warnings too.

To install dependencies through the check in a build job, use the wrapper instead of the bare command:

pkgfire npm ci

If the verdict is BLOCK nothing is installed and no script runs, and the job fails with exit code 2.

Capping what a job can spend

PKGFIRE_MAX_CREDITS sets the most one scan from this job may cost. The CLI asks for a quote before it submits anything, and stops with an error if the scan would cost more.

Recommended policy for CI

Set When a scanner cannot run to *Block*, so a scanner outage fails the pipeline instead of passing quietly, and keep the release cooldown on *Block*. A project can have its own policy, so a CI-only project can be stricter than the account.