Docs · GitHub Action

Add risk comments to pull requests.

Beta

The Ledgerful GitHub Action runs a risk scan on each pull request and posts a structured comment with impact and risk data.

GitHub Action vs GitHub App (planned)

The Ledgerful GitHub Action is a self-managed CI workflow you add to your own repository. A hosted GitHub App is a separate, hosted-planned feature that does not exist yet.

GitHub Action (this page): A reusable workflow step that runs inside your own GitHub Actions CI environment. You control the workflow YAML, the permissions, and the token. It is implemented in source as a beta, but is not publicly installable yet.

Hosted GitHub App: Hosted planned A future hosted control-plane integration that would allow installing Ledgerful as a GitHub App without managing workflow YAML. This is hosted planned and does not exist yet.

Version and release status

Not publicly installable. When a public version is verified, pin to it using the format shown below.

Version pending: Replace <version> in the workflow YAML below with the latest published release tag from github.com/Ryan-AI-Studios/Ledgerful/releases. The v0.1.8 release is publicly available on GitHub with binary archives for 4 platforms, SHA-256 checksums for each, CycloneDX SBOM (engine + MCP), cosign keyless signing (Sigstore Fulcio), SLSA build-provenance attestation, SBOM attestation, and cargo-auditable dependency embedding.

Workflow YAML

Add this step to a workflow triggered on pull_request events. The action needs two permissions: pull-requests: write to post comments, and contents: read to check out the repository.

name: Ledgerful Risk Scan

on:
  pull_request:
    branches: [main]

permissions:
  pull-requests: write
  contents: read

jobs:
  risk-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: Ryan-AI-Studios/Ledgerful/action@<version>    # pending — replace with latest tag
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          risk-threshold: TRIVIAL
          fail-on-risk: HIGH

Token value: Always use ${{ secrets.GITHUB_TOKEN }} — the built-in token provided by GitHub Actions. Do not create a personal access token for this purpose. The action only needs pull-requests: write to post PR comments and contents: read to access the repository. The checks: write permission is not required.

Inputs reference

All inputs except github-token are optional. Defaults are shown where applicable.

Input	Required	Default	Description
`github-token`	Yes	—	GitHub token used to post and update PR risk comments. Use secrets.GITHUB_TOKEN.
`project-path`	No	`.`	Workspace-relative path to the repository root. Defaults to the workspace root.
`base-ref`	No	—	Git ref to compare against. Defaults to the PR base branch.
`risk-threshold`	No	`TRIVIAL`	Minimum risk level to include in the comment (TRIVIAL, LOW, MEDIUM, HIGH).
`fail-on-risk`	No	—	Set to LOW, MEDIUM, or HIGH to fail the job when risk meets or exceeds this level.
`ledgerful-version`	No	—	Git tag to install. Defaults to the latest published release.
`post-on-clean`	No	`false`	When true, posts a comment even when no risk is detected.

← MCP setup Compliance export →