Run reports

The Prodgator report action for GitHub Actions, the Prodgator component for GitLab CI, the Prodgator pipe for Bitbucket Pipelines and the Prodgator task for Azure Pipelines each send a job's summary, test results, coverage, SBOMs, scan results, custom evidence and artifacts to Prodgator. The first three authenticate with their CI system's OIDC token; Azure Pipelines uses the pipeline's job token. No API key to create or rotate.

Other CI systems (CircleCI, Buildkite, Jenkins and more) use the prodgator-report command line with an OIDC trust or an API key. That data is self-reported. See Any CI.

WhyCopy Anchor Link

GitHub does not expose a job's $GITHUB_STEP_SUMMARY through any API. The only way to get it, or test results and other evidence, into Prodgator is a step in the workflow that sends them directly. The action does that.

GitHub ActionsCopy Anchor Link

Add permissions: id-token: write and a step that runs after your tests and build:

permissions:
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm test
      - run: npm run build

      - uses: prodgator/prodgator-action@v1
        if: always()
        with:
          junit: 'reports/**/*.xml'
          artifacts: 'dist/**'

Action inputsCopy Anchor Link

Outputs: report-id (the Prodgator report id) and report-url (a link to the run in Prodgator). These are the only inputs: an attestation's kind, name, status and data go in the attestations JSON.

if: always() sends the report even when an earlier step fails, so a broken build still shows its test results. A scan or sbom attestation can also name the scanner's own output file (for example a SARIF file); the action uploads it with the report and links it from the attestation. See the action README for every input, all six attestation kinds, matrix jobs and troubleshooting.

GitLab CICopy Anchor Link

Include the Prodgator component. It adds a prodgator-report job that runs after every other stage, even when a job fails, with the artifacts of the earlier jobs:

include:
  - component: gitlab.com/prodgator/prodgator-component/report@1
    inputs:
      junit: test-results/**/*.xml
      artifacts: dist/*.tgz
      attestations: attestations.json

Make the files you report job artifacts (artifacts: when: always). For a summary, append Markdown to prodgator-summary.md in a job and keep it as an artifact. The project's top-level group must be connected to Prodgator. See the component README for every input and for reporting from inside a job with npx @prodgator/report.

Bitbucket PipelinesCopy Anchor Link

Give the step an OIDC token for the Prodgator API and run the pipe in after-script, which also runs when the step fails:

- step:
    name: Test
    oidc:
      audiences:
        - https://api.prodgator.io
    script:
      - npm test
    after-script:
      - pipe: prodgator/prodgator-pipe:1.0.0
        variables:
          JUNIT: 'test-results/**/*.xml'

The workspace must be connected to Prodgator. Prodgator names the report after the step. See the pipe README for every variable.

Both the GitLab component and the Bitbucket pipe run the public image ghcr.io/prodgator/report at their own version. Each version is tagged X.Y.Z, X.Y and X. The image holds the same CLI as the npm package @prodgator/report. If your runners can only pull from an internal registry, mirror that image there, or run npx @prodgator/report inside a job instead.

Azure PipelinesCopy Anchor Link

Azure DevOps has no OIDC token Prodgator can verify, so the report is authenticated with the pipeline's own job token (System.AccessToken). Prodgator checks the token with Azure DevOps once to confirm which organization, project and build it belongs to, and discards it. The organization must be connected to Prodgator.

Install the Prodgator report extension from the Visual Studio Marketplace into your organization, then add the task after your tests. condition: always() sends the report even when an earlier step fails:

# azure-pipelines.yml
- task: ProdgatorReport@1
  condition: always()
  inputs:
    junit: 'test-results/**/*.xml'
    artifacts: 'dist/*.tgz'

Without the extension, run the CLI in a script step and map the job token yourself. The token is not in the step's environment unless you add it:

- script: npx --yes @prodgator/report --junit 'test-results/**/*.xml'
  condition: always()
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

If the token is not mapped, the CLI stops and tells you to add the env line. The public image ghcr.io/prodgator/report holds the same CLI, for agents that cannot reach npm.

Do not use that image as an Azure Pipelines container job (container: on a job). It is Alpine with an ENTRYPOINT, which Azure DevOps cannot run its agent steps in. Run it from a script step on the agent instead, with the sources mounted and the variables the CLI reads passed through:

- script: |
    docker run --rm \
      -v "$(Build.SourcesDirectory):/work" -w /work \
      -e TF_BUILD -e SYSTEM_ACCESSTOKEN -e SYSTEM_COLLECTIONURI -e SYSTEM_TEAMPROJECTID \
      -e SYSTEM_JOBID -e SYSTEM_JOBATTEMPT -e SYSTEM_JOBDISPLAYNAME \
      -e BUILD_BUILDID -e BUILD_SOURCEVERSION -e AGENT_NAME -e BUILD_SOURCESDIRECTORY=/work \
      --entrypoint prodgator-report \
      ghcr.io/prodgator/report:1.2.3 --junit 'test-results/**/*.xml'
  condition: always()
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)

Use a version tag from the image's tags (X.Y.Z, X.Y or X). -e NAME passes a variable from the step's environment into the container; TF_BUILD is how the CLI knows it runs in Azure Pipelines.

Task inputsCopy Anchor Link

failOnError (--fail-on-error when you run npx @prodgator/report yourself, in GitLab, Bitbucket and Azure Pipelines alike) covers a report that cannot be sent. A usage error, such as a mistyped command or an argument the command line does not take, always fails the step, whatever failOnError says.

The run's page in Prodgator shows the Summary and attestations once the report arrives.

Classic pipelinesCopy Anchor Link

A classic (designer) build pipeline sends the same report from one Command line task after your test tasks:

1. In the agent job settings, turn on Allow scripts to access the OAuth token.

2. Add a Command line task with this script:

   Copy Text

   npx --yes @prodgator/report --junit "test-results/**/*.xml"

3. Under the task's Environment Variables, add SYSTEM_ACCESSTOKEN with the value $(System.AccessToken).

4. Under Control Options, set Run this task to Even if a previous task has failed.

Classic release pipelines are not supported: Prodgator does not read them, and a report from a release does not map to a run. Use YAML pipelines with environments for deployments.

If your pipeline has approvalsCopy Anchor Link

Send the report before the first step that waits for a person, so the run in Prodgator shows the summary and attestations while the approval is pending, and the AI release risk can read them. If the pipeline has no manual or approval-gated steps, the end of the pipeline is the right place and the examples above already do that. A report cannot include results of steps that run after the approval, such as the deployment itself.

Your CI system, not Prodgator, knows which steps wait, so you place the report yourself:

• GitHub Actions: a job that uses an environment with required reviewers does not start until someone approves. Report from the build or test job, or from a report job that needs: the build and test jobs, never the deploy job.

  Copy Text

  jobs:
    build:
      runs-on: ubuntu-latest
      steps:
        - run: npm test
        - uses: prodgator/prodgator-action@v1
          if: always()
          with:
            junit: 'reports/**/*.xml'
    deploy:
      needs: build
      runs-on: ubuntu-latest
      environment: production   # required reviewers
      steps:
        - run: ./deploy.sh

• GitLab CI: the component's prodgator-report job runs in .post, which does not start while a manual or protected-environment job is blocking the pipeline. Add needs to the report job so it starts as soon as the jobs that make your files finish:

  Copy Text

  include:
    - component: gitlab.com/prodgator/prodgator-component/report@1
      inputs:
        junit: test-results/**/*.xml
  
  prodgator-report:
    needs: [build, test]   # not the gated deploy job
  
  deploy:
    stage: deploy
    environment: production   # protected environment with approvers
    script: ./deploy.sh

  The job gets artifacts only from the jobs in needs. As an alternative, set the stage input to a stage that sits before the deploy stage in your stages: list. The default stays .post because it is valid in every pipeline.

• Bitbucket Pipelines: run the pipe in the after-script of a step before the trigger: manual or permissioned deployment step, not in the gated step or after it.

  Copy Text

  - step:
      name: Build and test
      oidc:
        audiences:
          - https://api.prodgator.io
      script:
        - npm test
      after-script:
        - pipe: prodgator/prodgator-pipe:1.0.0
          variables:
            JUNIT: 'test-results/**/*.xml'
  - step:
      name: Deploy
      deployment: production
      trigger: manual
      script:
        - ./deploy.sh

• Azure Pipelines: put the report in a job of a stage before the stage that deploys to a gated environment, not in the deployment job. A stage waits for the environment's approvals and checks, the Prodgator gate included, before it starts.

  Copy Text

  stages:
    - stage: Build
      jobs:
        - job: Test
          steps:
            - script: npm test
            - task: ProdgatorReport@1
              condition: always()
              inputs:
                junit: 'test-results/**/*.xml'
    - stage: Deploy
      dependsOn: Build
      jobs:
        - deployment: Production
          environment: production
          strategy:
            runOnce:
              deploy:
                steps:
                  - script: ./deploy.sh

Secrets in summariesCopy Anchor Link

GitHub masks secrets in the step summaries it stores, and the action sends those masked copies. GitLab masked variables and Bitbucket secured variables are masked in job logs only: a file a job writes keeps what was written to it. The GitLab component and the Bitbucket pipe replace the values of the OIDC token, the GitLab job token family and every variable you list in redact-variables (GitLab) or REDACT_VARIABLES (Bitbucket) with *** in the summary and in attestations. Azure Pipelines secret variables are masked in logs only, the same way. The Prodgator task and CLI replace the job token and every variable you list in redactVariables with ***. Artifact files are sent as they are: do not upload files that contain secrets.

Files outside the workspaceCopy Anchor Link

The action, component, pipe, task and CLI read files only from the job's workspace (the checkout directory): the summary file, the attestations file, JUnit files, scanner files, the ownership file and artifacts. A file whose real path is somewhere else, such as a symlink in the repository that points at a file on the runner, is skipped with a warning and the report is sent without it. An attestations file that is skipped stops the report the same way a missing one does. Nothing under a .git directory is read. Write a summary file inside the workspace, not in the runner's temp directory: an absolute path outside the workspace is skipped too.

What appears whereCopy Anchor Link

• The pipeline card and the pipeline detail page show a Summary section with the job's markdown summary and its attestations.
• A deployment's approval card shows the same attestations, plus any recorded for the release's commit from other runs, in an evidence row.

Attestation kinds and statusCopy Anchor Link

Prodgator derives the status of every attestation kind except custom, so a report can't claim pass while its own numbers say otherwise:

When a scan attestation names a SARIF file and gives no counts, the report client counts the file the way Prodgator reads its findings, so the attestation and the Security page agree: the security-severity score on the result, else on its rule (rules inside tool.extensions included, as ASH writes them), else the level (error is high, warning medium, note low). Suppressed results (every suppression with no status or status accepted) go in a separate suppressed count, which is shown in the attestation headline and never changes the status. Results of kind pass, notApplicable or informational, and results with baselineState absent, are not counted, and a result repeated across runs counts once.

Each attestation is { "kind": ..., "name": ..., "status": ..., "data": { ... } }. An optional "sourcePath" names the file the result came from (workspace-relative, up to 200 characters; the report is rejected if it is absolute or leaves the workspace). status is required for custom and ignored for the kinds Prodgator derives. To bring an outside check such as a ServiceNow change ticket into a release policy, see Send a custom attestation.

Test results and source pathsCopy Anchor Link

Every matched JUnit file is summed into one test-results attestation, so a failing file always counts in the totals. Its name is the junit-name setting when you give one, otherwise junit, so a release policy that names the junit attestation keeps working. To choose the name yourself, set:

Every attestation can carry a source path: where it was read from, relative to the workspace. For JUnit it is the pattern when you passed one, otherwise the file when only one was read, and is left out when several files were read by several patterns. It is never an absolute path, never contains .., and is at most 200 characters. A request with an invalid source path is rejected. The path is kept with the attestation but is not part of the data policies read.

The source path shows in the Details line of a report in the provenance tree and in the tooltip of an attestation badge on the pipeline and deployment pages. Attestations sent before this was added show their name and job name only.

Build provenance reportsCopy Anchor Link

Send an actions/attest-build-provenance bundle with {"kind":"provenance","name":"build","data":{"bundle":"build-provenance.json"}} in the attestations input. Copy the bundle into the workspace first if the action wrote it outside the checkout. The client also accepts a bare DSSE envelope or an in-toto statement, as JSON no larger than 1 MiB. A Sigstore bundle can be at most 64 KiB, and the report stops with an error when it is larger. Unreadable files, paths outside the workspace and malformed statements stop the report.

The client sends only a summary: SLSA predicate type (v1 or v0.2), up to 64 named SHA-256 subjects, source repository, full source commit, source ref, workflow path, builder id and invocation id, together with the Sigstore bundle itself. Other producers may supply that summary directly using predicateType, subjects (each with name and sha256), sourceRepository, sourceCommit, sourceRef, workflowPath, builderId and invocationId, and the bundle as bundle. A summary with no bundle is stored, unverified. A signed value sent by a client is ignored. Subject names allow 200 characters, repository, builder and invocation strings allow 2,000, and ref and workflow path allow 1,000.

The server ignores a supplied status and compares the source against the authenticated report's commit and repository. When the bundle verifies, it rebuilds the summary from the signed statement first. Missing or different source identities are stored as fail, with data.mismatch set to commit or repository. URL and owner/name repository forms are accepted; comparisons ignore case. Empty subjects also fail.

The run's existing trust rules still apply: a verified signature does not make a fork or pull_request_target report trusted.

Signature checksCopy Anchor Link

A provenance attestation counts as signed only when Prodgator verified the Sigstore bundle itself. The report client sends the bundle that actions/attest-build-provenance wrote (at most 64 KiB), and Prodgator checks it offline against pinned trust roots, with no outside request:

• the signature over the in-toto statement, made with the key in the signing certificate
• the certificate chain up to the Fulcio certificate authority of the trust root
• a trusted signing time: a Rekor transparency log entry for the public Sigstore instance, or GitHub's timestamp authority for repositories that sign with GitHub's own root. The certificate must have been valid at that time
• the certificate issuer is GitHub Actions (https://token.actions.githubusercontent.com)
• the source repository in the certificate is the repository of the run that sent the report, and its repository and owner ids are the ids in the run's sign-in token
• the source commit in the certificate is the commit the attestation is filed under, and agrees with the commit named in the statement. For a pull_request run the attestation is filed under the pull request head while GitHub builds and signs a temporary merge commit (refs/pull/N/merge): the commit in the run's sign-in token is accepted too, and the verified result keeps the commit the certificate names
• the statement is SLSA provenance and every subject has a SHA-256 digest
• the builder id agrees with the certificate. The workflow writes the builder id itself, so an id that is a workflow URL must be the workflow the certificate names, and an id or runner_environment that names a runner type (github-hosted or self-hosted) must be the certificate's runner type

A verified attestation reports a builder id only when the certificate proves it: the signer workflow URL (https://github.com/<owner>/<repo>/.github/workflows/<file>@<ref>, what actions/attest-build-provenance writes), or exactly https://github.com/actions/runner/github-hosted or https://github.com/actions/runner/self-hosted matching the certificate's runner type. Any other id is not trusted: the attestation still verifies, but verification.builderId is null and the id is stored as claimedBuilderId, so a rule with builders fails. A signer workflow URL says nothing about the runner type; read verification.runnerEnvironment in custom Rego to require one.

The subjects, source commit, workflow, builder id and invocation id shown for a verified attestation come from the signed statement, not from what the client sent. The client's own signed field is ignored. The result is stored with the attestation as data.verification: state is verified (with the signer workflow, trust root, signing time, the certificate's runner type and whether the certificate was issued to the run that sent the report) or unverified (with a reason code and a reasonText). A bundle another run signed for the same commit, such as a separate release workflow, still verifies; policies can tell it apart with verification.sameRun.

On a provenance attestation that is not verified, policies see the fields the client wrote under other names (claimedBuilderId, claimedWorkflowPath, claimedSourceRef, claimedInvocationId), and data.signed is always the server's result, so custom Rego cannot mistake a client's claim for a checked value.

Private repositories sign with GitHub's trust root, public repositories with the public Sigstore instance. Both roots are built into Prodgator. GitHub Enterprise Cloud with data residency signs with an issuer of its own (https://token.actions.githubusercontent.com/<name>), which Prodgator does not support yet: those attestations stay unverified with the reason "the certificate was not issued to a GitHub Actions workflow".

The status of the attestation (pass or fail) still depends only on the subjects, commit and repository. Whether the signature verified is a separate result, and a policy decides what to do with it: the Build provenance rule has a Require a verified signature setting.

Why a signature is not verifiedCopy Anchor Link

A bundle may hold at most 64 KiB and the whole provenance attestation at most 96 KiB (other attestation kinds keep 32 KiB). A statement can name up to 64 subjects.

Ownership reportsCopy Anchor Link

Code owners rules on pull requests read your CODEOWNERS file from an ownership report. Send it with the ownership input of the GitHub Action, from a workflow that runs on pushes to your base branches:

on:
  push:
    branches: [main]
jobs:
  ownership:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: prodgator/prodgator-action@v1
        with:
          ownership: .github/CODEOWNERS

The action uploads the file as an artifact of the report and adds an ownership attestation with format (codeowners, or json for a .json file) and artifact (the file's path). Once the upload completes, Prodgator reads the file and stores it for the commit. For a push to a branch it also becomes the branch's latest report, and open pull requests into that branch are evaluated again (up to 20, most recently updated first).

The file can be at most 256 KB with 5,000 rules. Owners are @user or @org/team; email owners are skipped. When the file cannot be read, the report shows a warning such as ownership "codeowners": The ownership file is larger than 256 KB and nothing is stored. A .json file uses this format:

{ "version": 1, "rules": [{ "pattern": "infra/**", "owners": ["@acme/platform"] }] }

Untrusted sourcesCopy Anchor Link

A report from a pull_request_target or workflow_run event, or from a pull_request whose head repository is a fork, is stored but marked untrusted. These contexts run with the base repository's identity while commonly processing fork-supplied data. On GitLab, a merge request pipeline whose source project is a fork, and external pull request pipelines, are marked untrusted. Bitbucket does not run pull request pipelines for forks in the target repository, so Bitbucket reports are trusted. The attestations rule of a release policy counts only trusted attestations by default; whoever edits the policy can turn that off per rule.

Reports from other CI systemsCopy Anchor Link

Reports sent from CircleCI, Buildkite, Jenkins or another CI system through Any CI are self-reported, not trusted. A policy ignores them unless its rule sets Count self-reported results from other CI (not verified), and even then it uses one only when the commit has no matching result from a connected provider. Prodgator refuses build provenance and ownership reports from other CI systems.

Limits by planCopy Anchor Link

Every plan is also capped at 20 attestations and 50 artifacts per report, and 300 report requests per minute per organization.

RetentionCopy Anchor Link

Reports, attestations and artifacts follow your plan's data retention, the same as pipeline runs: 7 days on Free, 30 on Team, 90 on Business, 365 on Enterprise. Moving to a shorter retention does not shorten data already written; it expires on the old schedule.

Learn moreCopy Anchor Link

• Any CI: run, report and gate commands for CircleCI, Buildkite, Jenkins and other CI systems.
• Action README: every input, all attestation kinds with examples, matrix jobs and troubleshooting.
• Component README: every input for GitLab CI.
• Pipe README: every variable for Bitbucket Pipelines.
• Send a custom attestation: check ServiceNow, Jira or a release window in CI and require the result in a policy.
• Deployment Approvals: where attestations show up on a pending deployment.
• Release Policies: require passing attestations before a deployment is approved.