Run Veriom in CI

This page is for the person who looks after a repository's CI. It shows how to add Veriom to GitHub Actions with no stored secret, how to check pull requests, and how to use Veriom on GitLab CI or Bitbucket Pipelines.

Before you startCopy Anchor Link

• The repository is connected to Veriom through the GitHub App. See Connect a repository.
• The repository has finished at least one audit, so Veriom knows its services.
• You have the Admin or Owner role in the workspace.

Set up keyless CI in one clickCopy Anchor Link

1. In Veriom, open Integrations and select the Repositories tab.
2. On the repository's row, click Set up keyless CI.
3. If Veriom asks you to confirm your identity, confirm it. This action needs a recent sign-in check.
4. Veriom shows Draft pull request opened. Click Open #<number> to see it on GitHub.
5. Review the pull request on GitHub and merge it. Veriom never merges it for you.

After the merge, every push to the default branch records a deployment of each service in Veriom. You see them under Architecture in the Services tab.

If a setup pull request is already open, Veriom shows Draft pull request already open and links to it instead of opening a second one.

What the setup pull request addsCopy Anchor Link

The pull request is titled Record deployments in Veriom (keyless). It is opened as a draft from the branch veriom/ci-setup and adds one file, .github/workflows/veriom.yml:

name: Veriom
on:
  push:
    branches: ["main"]
permissions:
  contents: read
  id-token: write
jobs:
  deployment-record:
    runs-on: ubuntu-latest
    steps:
      - name: "Record the checkout-api deployment"
        uses: Veriom/actions/deployment-record@v2
        with:
          api-url: https://api.veriom.ai
          workspace-id: 7f3c9a52-1b4e-4d8a-9c61-2e5f0a7b8d13
          service-id: 3c2b1a09-8f7e-4d6c-b5a4-938271605f4e
          environment: production

Veriom fills in your default branch, workspace ID, and one step per service. Two things to check before you merge:

• The file lists at most 10 services. Add a step for each extra service.
• Every step records the production environment. Change environment if this branch deploys somewhere else.

How keyless sign-in worksCopy Anchor Link

The workflow holds no Veriom token. Each run proves which repository it comes from instead:

1. id-token: write lets the job ask GitHub for a signed OIDC token with the audience veriom.
2. The action sends that token to Veriom, which checks GitHub's signature, the issuer, and the expiry.
3. Veriom accepts it only when the repository is connected through the GitHub App in your workspace, is enabled, and belongs to the account that installed the App.
4. Veriom returns a short-lived workspace token. It lasts 15 minutes by default and each GitHub token can be exchanged once.

That token works only for its own repository. It can start and read audits, record deployments, and send cloud inventory. Any other request gets 403 ci_token_route_not_allowed.

Check pull requests on GitHubCopy Anchor Link

The GitHub App can post a check on each pull request. It needs no workflow file. This check is off until you turn it on:

1. Open Audits, select the Schedules tab, then the GitHub events tab.
2. Click Edit on the repository's policy. Veriom created it when you connected the repository.
3. Under Listen for, select Pull request checks.
4. Click Save policy.

The next time a pull request opens or changes, Veriom audits it and posts a check named Veriom architecture guard. The check result follows the release gate:

To make the check a merge gate, add Veriom architecture guard as a required status check in your GitHub branch protection rule.

The App needs the Pull requests: read and Checks: write permissions to post the check. If it lacks them, Veriom records a github.architecture_check.permission_required event in the Activity log and posts nothing.

Check merge requests on GitLab or BitbucketCopy Anchor Link

GitLab CI and Bitbucket Pipelines have no keyless option. They use a workspace API token.

1. Create a token under Settings → API tokens with the audits:read, audits:write, and repositories:read scopes. See API tokens.

2. Copy the check into your repository:

   Copy Text

   git clone https://github.com/Veriom/actions.git veriom-actions
   ./veriom-actions/install-architecture-check.sh gitlab /path/to/your/repository

   Use bitbucket instead of gitlab for Bitbucket. The script writes .veriom/architecture-check.cjs and .veriom/gitlab-architecture-check.yml.

3. On GitLab, include the template from .gitlab-ci.yml:

   Copy Text

   include:
     - local: .veriom/gitlab-architecture-check.yml

   On Bitbucket, copy the step from .veriom/bitbucket-architecture-check.yml into bitbucket-pipelines.yml.

4. Store the token as the VERIOM_API_TOKEN CI variable. On GitLab, make it Masked but not Protected. Merge request pipelines run on unprotected branches and cannot read protected variables.

The job fails when the result is review, blocked, or insufficient_evidence. Set VERIOM_FAIL_ON to change that list, or to none to never fail.

The actionsCopy Anchor Link

All three actions live in Veriom/actions.

api-url defaults to https://api.veriom.ai/v1. The actions find the workspace, repository, and commit from the token and the CI run, so you rarely set workspace-id, repository-id, or commit-sha.

If something goes wrongCopy Anchor Link

See Troubleshooting for more codes.