TrustCheck GitHub Action

Run TrustCheck in GitHub Actions to evaluate the trust posture of a PyPI package before it is installed, promoted, or approved.

This action is a lightweight wrapper around the core trustcheck CLI. It installs the CLI and runs trustcheck inspect inside your workflow so you can surface provenance, publisher, repository, vulnerability, and policy-related signals during CI.

Why TrustCheck

Traditional dependency checks usually answer "is this package known to be vulnerable?"

TrustCheck helps answer earlier questions, such as:

• does this release have verified provenance?
• do attested publisher details point to the expected repository and workflow?
• do declared repository URLs line up with attested evidence?
• are there vulnerability records or higher-risk trust signals that should block adoption?

The core CLI combines PyPI metadata, provenance availability, cryptographic attestation verification, Trusted Publisher identity hints, repository matching, release drift signals, and vulnerability records into a single report.

What This Action Does

This action currently:

1. installs trustcheck from PyPI
2. runs trustcheck inspect <package>
3. fails the workflow step if the CLI exits with a non-zero status

That makes it a simple way to bring TrustCheck into GitHub Actions today while keeping the heavy lifting in the core project.

Quick Start

name: TrustCheck Scan

on:
  pull_request:
  workflow_dispatch:

jobs:
  trustcheck:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Inspect package with TrustCheck
        uses: Halfblood-Prince/trustcheck-action@v1
        with:
          package: requests

Input

Name	Required	Description
package	Yes	PyPI package name to inspect

Example Use Cases

Review a package during pull requests:

name: Dependency Trust Check

on:
  pull_request:

jobs:
  trustcheck:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Inspect requests
        uses: Halfblood-Prince/trustcheck-action@v1
        with:
          package: requests

Run an on-demand inspection:

name: Manual TrustCheck

on:
  workflow_dispatch:

jobs:
  trustcheck:
    runs-on: ubuntu-latest

    steps:
      - name: Inspect sampleproject
        uses: Halfblood-Prince/trustcheck-action@v1
        with:
          package: sampleproject

What The Core CLI Can Evaluate

According to the core TrustCheck documentation, trustcheck inspect can evaluate:

• project and release metadata from PyPI
• declared repository URLs
• provenance envelopes for release artifacts
• attestation verification against artifact digests
• Trusted Publisher identity details such as repository and workflow
• expected repository matching
• publisher repository and workflow drift between releases
• vulnerability records for the selected version
• text or JSON output for operators and automation

Recommendation tiers in the core project include verified, metadata-only, review-required, and high-risk.

Important Note About This Action

The current GitHub Action is intentionally minimal. It only exposes the package input and runs the default trustcheck inspect command.

If you need advanced TrustCheck behavior documented in the core project, such as:

• --version
• --expected-repo
• --strict
• --policy or --policy-file
• --format json
• --verbose
• --config-file
• --cache-dir or --offline

use the core CLI directly in your workflow today, or extend this action to expose those flags as additional inputs.

Recommended Advanced Workflow

If you want stricter policy enforcement right now, install and run the CLI directly:

name: Verify Dependency Trust

on:
  pull_request:
  workflow_dispatch:

jobs:
  trustcheck:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Install TrustCheck
        run: python -m pip install --upgrade pip trustcheck

      - name: Inspect pinned release with strict policy
        run: |
          trustcheck inspect sampleproject \
            --version 4.0.0 \
            --expected-repo https://github.com/pypa/sampleproject \
            --strict

Exit Behavior

From the core CLI documentation:

• 0 means success
• 1 means upstream PyPI or network failure
• 2 means command usage error
• 3 means invalid response or internal processing failure
• 4 means policy failure

In CI, a policy failure is useful: it means TrustCheck ran correctly and intentionally blocked the package under the selected policy.

Documentation

• Core project: https://github.com/Halfblood-Prince/trustcheck
• Documentation: https://halfblood-prince.github.io/trustcheck/
• PyPI package: https://pypi.org/project/trustcheck/

License

This repository is source-available under the TrustCheck Action Personal Use License.

Private and commercial use of the official published Halfblood-Prince/trustcheck-action GitHub Action is permitted under the GitHub Action Use Exception included in LICENSE.

The exception applies to using the official action in workflows. It does not grant broad rights to copy, modify, redistribute, sublicense, or republish this repository's source code outside that context.