GB
Start 30-day trial

Guardrail Ledger documentation

Connect your pipeline

The scanners run on your agents or runners. The task or Action collects their SARIF, sends it to your workspace and reads the gate result.

1. Mint an ingest token

An owner or admin opens the Pipeline page, enters a token name and chooses Mint ingest token. The token is shown once. Store it as the secret variable GUARDRAIL_TOKEN in Azure Pipelines, or as the repository secret GUARDRAIL_INGEST_TOKEN on GitHub.

2. Install the four scanners

Trivy, Gitleaks, Checkov and Opengrep must be on the PATH of the agent or runner. The task does not install them.

3a. Azure DevOps

  1. On the Pipeline page, enter your Azure DevOps organisation name (the name in dev.azure.com/<organisation>) and choose Share the extension with this organisation.
  2. Open the Marketplace link that appears there, choose Get it free and pick the organisation. Installing needs permission to manage extensions in that organisation. Until the extension is shared, the link is not shown.
  3. Add the step to azure-pipelines.yml and run the pipeline on pull requests.
- task: GuardrailLedgerScan@0
  inputs:
    guardrailUrl: 'https://<workspace>.guardrail-ledger.com'
    ingestToken: '$(GUARDRAIL_TOKEN)'
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

The env line lets the task comment the gate result on the pull request. The project's build service identity also needs the Contribute to pull requests permission on the repository.

3b. GitHub Actions

  1. On the Pipeline page, download action.yml and index.js. Commit them as .github/actions/guardrail-ledger/action.yml and .github/actions/guardrail-ledger/dist/index.js.
  2. Add the workflow that the Pipeline page shows. It installs the scanners, then runs the Action with your workspace address and the secret GUARDRAIL_INGEST_TOKEN.
  3. Run the scan on pull requests from branches in the repository. On forks, GitHub gives the job no secrets.

The job needs these permissions so the Action can read the code and comment on the pull request:

permissions:
  contents: read
  pull-requests: write

Any other CI

Any CI that writes SARIF can post it to your workspace. The body is JSON with repo and sarif, and the token goes in a Bearer header.

curl -sS -X POST 'https://<workspace>.guardrail-ledger.com/api/v1/ingest/sarif' \
  -H "Authorization: Bearer $GUARDRAIL_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"repo":"example-repo","sarif":{"version":"2.1.0","runs":[...]}}'

When a scanner fails

The step fails, and names the scanner, when a scanner is missing, crashes, exits with an error or writes no usable SARIF. Nothing is sent in that case. To continue with the other scanners, set allowMissingScanners: true on the Azure DevOps task, or allow-missing-scanners: true on the Action. The run is then sent as incomplete, so no finding is resolved on it and the gate does not pass on what is missing.

What is sent

The task sends the scanners' SARIF results, the repository name, commit, pull request number, the login of the person who ran the build and the paths of AI tooling files such as AGENTS.md or mcp.json. It removes code snippets and context lines from the SARIF before sending. It does not upload the repository. Scanner output is written to the agent's temporary directory, outside the sources, and deleted after it is read.