Docs · GitHub Action

Add risk comments to pull requests.

Available · Runs locally

Public self-hosted Action. The public Action runs the real Ledgerful engine binary in your runner over a PR diff and posts a change-risk summary. Pin a version — this is not a Marketplace listing and not the planned hosted GitHub App.

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. Install from the public repo Ryan-AI-Studios/ledgerful-action (opens in new tab) with a pinned ref. Not listed on the GitHub Marketplace.

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

Version and pin honesty

Public self-hosted Action. Pin both the Action ref and the engine binary version you trust.

Action package: Use uses: Ryan-AI-Studios/ledgerful-action@a867acedfb80798c4d96bea9f68020b2f899b3bd (or a commit SHA). Prefer a pin you have reviewed; do not assume Marketplace or floating @latest.

Engine binary: Set ledgerful-version to a published engine tag (current Latest is v0.2.14). The Action default tracks the published engine tag last written into action.yml at the last Action-repo bump; later engine tags require another Action bump. Prefer also setting ledgerful-checksum from the matching release .sha256 asset.

Public repo Ryan-AI-Studios/ledgerful-action ships action.yml at the repository root (name: Ledgerful PR Risk Report). Install with uses: Ryan-AI-Studios/ledgerful-action@<sha> and pin ledgerful-version (and preferably ledgerful-checksum). Not listed on the GitHub Marketplace. Not the planned hosted GitHub App.

Workflow YAML

Add this step to a workflow triggered on pull_request events. The action needs pull-requests: write (and often checks: write) to post results, and contents: read to check out the repository and download the pinned release.

name: Ledgerful Risk Scan

on:
  pull_request:
    branches: [main]

permissions:
  pull-requests: write
  checks: 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@a867acedfb80798c4d96bea9f68020b2f899b3bd
        # note: pin Action ref (40-char SHA) + ledgerful-version; not Marketplace
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          ledgerful-version: v0.2.14
          # ledgerful-checksum: <sha256 of the matching platform archive>
          report-path: ledgerful-pr-report.json
          fail-on: 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 the permissions required for release download and PR / check posting. Prefer pinning a commit SHA for the Action ref in production workflows when supply-chain policy requires it.

Inputs reference

Inputs match the public Ryan-AI-Studios/ledgerful-action action.yml. Defaults are shown where the Action declares them.

Input	Required	Default	Description
`ledgerful-version`	No	`v0.2.14`	Pinned Ledgerful engine release version to run. Default is the published engine tag last written into action.yml (currently v0.2.14); pin explicitly for supply-chain hygiene. Not `latest`.
`ledgerful-checksum`	No	—	SHA-256 checksum of the pinned release archive (.tar.gz/.zip) for the runner OS/arch. Verified against the downloaded archive before extraction. Required in Workflow A (scan); not used in Workflow B.
`github-token`	No	`${{ github.token }}`	GITHUB_TOKEN used to authenticate the release download (Workflow A) and to post the PR comment / check-run (Workflow B). Prefer secrets.GITHUB_TOKEN in workflow YAML.
`report-path`	No	`ledgerful-pr-report.json`	Path to the JSON report file. Workflow A writes it; Workflow B reads it (relative to GITHUB_WORKSPACE).
`fail-on`	No	—	Optional non-blocking fail condition (low\|medium\|high). Reporting only — policy enforcement is out of scope here.

← MCP setup Compliance export →