Customer developer docs

Authority previews for pull requests

Run report-only PR checks that compare agent authority manifests, evaluate representative scenarios, and save dashboard-visible reports.

Authority previews for pull requests

Authority previews show how an agent's effective tool authority would change if a pull request merged. They are report-only: Ledgix evaluates representative tool-call scenarios and persists a preview report, but does not mint A-JWTs, create review work items, or append production clearance ledger events.

Use this when teams change agent tools, prompts, SDK wrappers, MCP configuration, or workflow code that can alter what an agent is allowed to do.

What the preview checks

The GitHub Action reads ledgix.authority.json from the pull request, fetches the base version of the same file through the GitHub API, and sends both manifests to Vault.

Ledgix then records:

  • static manifest changes such as new tools, removed tools, changed policies, new destinations, and unguarded tools
  • generated scenarios from tool argument schema examples
  • explicit trace scenarios from optional JSONL files
  • before/after decisions from the same deterministic evaluator used by runtime clearance
  • summary counts, warnings, material findings, and a Markdown report for GitHub

The saved report appears in the dashboard under Authority Previews.

Add the authority manifest

Create ledgix.authority.json at the root of the repository that owns the agent.

text
{
  "version": "0",
  "agent_id": "payments-agent",
  "tools": [
    {
      "name": "stripe_refund",
      "policy_id": "refund-policy",
      "description": "Issue Stripe refunds",
      "args_schema": {
        "type": "object",
        "properties": {
          "amount": { "type": "number", "examples": [50, 5000] },
          "reason": { "type": "string", "examples": ["late shipment"] }
        },
        "required": ["amount"]
      },
      "data_categories": ["transaction"],
      "purpose": "customer_support",
      "destinations": [
        { "provider": "stripe", "account_ref": "prod" }
      ]
    }
  ]
}

Required fields:

  • version
  • tools[].name

Recommended fields:

  • agent_id
  • tools[].policy_id
  • tools[].description
  • tools[].args_schema.properties.*.examples
  • tools[].data_categories
  • tools[].purpose
  • tools[].destinations

Unknown fields are preserved in the saved report so you can add team-specific metadata without breaking V0.

Add representative traces

Schema examples are enough to start. For more realistic coverage, commit an optional JSONL trace file such as .ledgix/authority-trace.jsonl.

text
{"id":"refund-small","tool_name":"stripe_refund","tool_args":{"amount":50,"reason":"late shipment"},"agent_id":"payments-agent"}
{"id":"refund-large","tool_name":"stripe_refund","tool_args":{"amount":5000,"reason":"goodwill"},"agent_id":"payments-agent"}

Bad trace rows are skipped and reported as warnings in GitHub and the dashboard. A trace row must be a JSON object and must include tool_name.

Install the GitHub Action

Add this workflow to .github/workflows/authority-preview.yml.

text
name: Ledgix Authority Preview
 
on:
  pull_request:
 
permissions:
  contents: read
  pull-requests: write
 
jobs:
  authority-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - uses: ledgix/authority-action@v0
        with:
          vault-url: ${{ secrets.LEDGIX_VAULT_URL }}
          vault-api-key: ${{ secrets.LEDGIX_VAULT_API_KEY }}
          authority-path: ledgix.authority.json
          trace-path: .ledgix/authority-trace.jsonl
          dashboard-url: https://app.ledgix.dev
          github-token: ${{ github.token }}

Required repository secrets:

  • LEDGIX_VAULT_URL
  • LEDGIX_VAULT_API_KEY

Fork pull requests without Ledgix secrets are skipped successfully and write a local summary instead of failing the PR.

Read the result

Each successful run writes two GitHub surfaces:

  • the job summary
  • a PR comment with the hidden marker <!-- ledgix-authority-preview -->

The comment is updated in place on later pushes to the same PR. If dashboard-url is set and Vault returns a run_id, the Action appends a link to the dashboard detail page.

In the dashboard, open Authority Previews to see recent runs. The detail page includes:

  • repo and pull request metadata
  • base and head SHAs
  • risk level
  • summary counts
  • warnings
  • findings grouped by severity
  • scenario before/after decision table
  • compact base/head manifest previews

Risk levels

High risk:

  • unguarded tool
  • destination expansion
  • oversight reduction from manual review to auto-approve

Medium risk:

  • authority expansion from denied, no-match, missing-tool, or review to approved
  • data category expansion
  • newly added purpose

Low risk:

  • changed or removed tools without expanded authority

No risk:

  • no material findings beyond unchanged scenario decisions

Operational guarantees

Authority previews do not execute the protected action. Preview requests go through Vault and Judge preview routes, not /request-clearance.

Preview evaluation:

  • does not mint an A-JWT
  • does not consume an A-JWT
  • does not append to the production decision ledger
  • does not create manual-review queue items
  • does not reserve regular runtime judge quota

The preview report is stored in tenant-local product tables separate from the production clearance ledger.

Troubleshooting

Head authority file was not found

: The PR does not include the configured authority-path. The Action writes a skipped summary and does not call Vault.

contains invalid JSON

: Fix the manifest or trace JSON. Invalid head manifests are shown as skipped reports instead of stack traces.

Vault authority preview failed

: Confirm LEDGIX_VAULT_URL and LEDGIX_VAULT_API_KEY are set for the repository and that the tenant has a reachable active rule pack.

No scenarios were evaluated

: Add args_schema examples or a .ledgix/authority-trace.jsonl file with realistic tool calls.