Skip to content

Forges and CI templates

Since 2.0 (#56) the harness proposes and reports a governed change on GitHub, GitLab, Bitbucket, Azure DevOps and Gitea (or Forgejo) through one interface. Nothing is decided on a forge: the comment, the quality report and the commit status inform the reviewers, and the approval is the run's digest-bound decision, which harness verify-approval checks in CI.

Which forge

The forge is detected from the origin remote; delivery.forge or --forge override it.

Remote host Forge REST API base Token variable
github.com (or a host starting with github.) github https://api.github.com (GitHub Enterprise: https://HOST/api/v3) GITHUB_TOKEN
gitlab.com, or a host with gitlab in its name gitlab https://HOST/api/v4 GITLAB_TOKEN
bitbucket.org bitbucket https://api.bitbucket.org/2.0 BITBUCKET_TOKEN
dev.azure.com, ssh.dev.azure.com, *.visualstudio.com azure-devops https://dev.azure.com/ORGANIZATION AZURE_DEVOPS_TOKEN
codeberg.org, or a host with gitea or forgejo in its name gitea https://HOST/api/v1 GITEA_TOKEN

A self-hosted forge on another host needs delivery.forge.kind (and repository when there is no origin). harness pr forge shows what the workspace resolves to and calls nothing.

delivery:
  forge:
    kind: gitlab                 # auto (default), github, gitlab, bitbucket, azure-devops, gitea
    transport: api               # api (HTTPS, token from tokenEnv) or cli (gh or glab)
    repository: team/shop        # default: from origin
    apiUrl: https://code.example.com/api/v4
    tokenEnv: CI_FORGE_TOKEN     # default: per forge, see the table
    baseBranch: main             # target of harness pr create
    labels: [governed]
    template: .gitlab/merge_request_templates/Default.md
    draft: false
    codeQuality: true

Tokens are read only from the environment variable tokenEnv, never from project.yaml and never logged or recorded. The cli transport uses the forge's own CLI (gh api, glab api) with the authentication it already has; Bitbucket, Azure DevOps and Gitea use api.

Commands

Command What it does
harness pr publish --pr N One comment per run on the pull or merge request with the decision brief, updated when published again (marker governed-harness:RUN), and the findings as the forge's quality report. Without delivery.forge and with a GitHub origin it is the GitHub publisher of 1.1 unchanged.
harness pr create [--base B] [--label L]... [--draft] A pull or merge request from the closure branch of the run (delivery.branch, default harness/RUN): the title is the task title, the description is the repository's pull request template followed by the decision brief, the labels are delivery.forge.labels plus --label. Push the branch first. Recorded as a delivery.pull-request.created event.
harness pr status --commit SHA The commit status governed-harness: success once the run closed approved, pending while it waits for a decision, failure otherwise.
harness pr forge The resolved forge, API URL, transport and token variable.
harness trace --format codequality The findings as a GitLab Code Quality report, with the same fingerprints as the SARIF report.

Complete delivery at CLOSURE (#55, delivery.push, delivery.pullRequest.create and delivery.comment, when the task's operational contract authorises them) goes through the same forge: after the push it creates the pull or merge request as harness pr create does (base delivery.forge.baseBranch, else the remote's default branch) and posts the run's comment as harness pr publish does, without the quality report. See complete delivery.

What each forge receives as the quality report:

Forge Report
GitHub SARIF uploaded to code scanning (code-scanning/sarifs).
GitLab None through the API: GitLab reads gl-code-quality-report.json from the pipeline (artifacts:reports:codequality), see the template below.
Bitbucket A Code Insights report on the commit with one annotation per finding (at most 100).
Azure DevOps None through the API: publish harness.sarif as the CodeAnalysisLogs build artifact.
Gitea None.

The pull request templates looked for, in order, when template is not set: .github/pull_request_template.md (GitHub), .gitlab/merge_request_templates/Default.md (GitLab), PULL_REQUEST_TEMPLATE.md (Bitbucket), .azuredevops/pull_request_template.md (Azure DevOps) and .gitea/pull_request_template.md (Gitea), among others listed in governed_harness.forges.TEMPLATE_CANDIDATES.

The providers are covered by tests/unit/test_forges.py (requests of every provider through a recording fake transport) and tests/integration/test_forge_delivery.py; the gitlab flow of scripts/demo_flows.py runs the commands against a local fake GitLab server. They have not been run against the live forges.

CI templates

The templates verify, on a pull or merge request, that the merged tree is a ChangeSet a person approved: the run's evidence bundle (harness export --bundle) is kept on a branch harness-evidence that is never merged, harness verify --bundle checks it and harness verify-approval recomputes the ChangeSet digest of the range and requires an approval bound to it (see CI integration). They show the commands; they have not been run as part of this repository's CI, so adapt the install step and the branch names.

GitHub Actions

name: approved-change

on:
  pull_request:

permissions:
  contents: read

jobs:
  verify-approval:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
          fetch-depth: 0
      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.12"
      - name: Install the harness
        run: python -m pip install governed-agent-harness  # pin the version you use
      - name: Verify that the merged tree is an approved ChangeSet
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          git fetch --no-tags origin harness-evidence
          run_id=$(git log --format='%(trailers:key=Harness-Run,valueonly)' "origin/${BASE_REF}..HEAD" | sed -n '/./{p;q}')
          git show "origin/harness-evidence:${run_id}.tar.gz" > approval.tar.gz
          harness verify --bundle approval.tar.gz
          harness verify-approval --base "origin/${BASE_REF}" --head HEAD \
            --bundle approval.tar.gz --no-workspace

GitLab CI

The second job attaches the Code Quality report of a governed run kept in the evidence branch; GitLab shows it in the merge request widget.

stages: [verify]

verify-approval:
  stage: verify
  image: python:3.12
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - python -m pip install governed-agent-harness  # pin the version you use
    - git fetch --no-tags origin harness-evidence "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
    - run_id=$(git log --format='%(trailers:key=Harness-Run,valueonly)' "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD" | sed -n '/./{p;q}')
    - git show "origin/harness-evidence:${run_id}.tar.gz" > approval.tar.gz
    - git show "origin/harness-evidence:${run_id}.codequality.json" > gl-code-quality-report.json
    - harness verify --bundle approval.tar.gz
    - harness verify-approval --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --head HEAD --bundle approval.tar.gz --no-workspace
  artifacts:
    when: always
    reports:
      codequality: gl-code-quality-report.json

Where the run happened, harness trace --run RUN --format codequality --output RUN.codequality.json writes the report kept next to the bundle.

Jenkins

pipeline {
  agent { docker { image 'python:3.12' } }
  options { timeout(time: 10, unit: 'MINUTES') }
  stages {
    stage('Verify approval') {
      when { changeRequest() }
      steps {
        sh '''
          python -m pip install governed-agent-harness  # pin the version you use
          git fetch --no-tags origin harness-evidence "$CHANGE_TARGET"
          run_id=$(git log --format='%(trailers:key=Harness-Run,valueonly)' "origin/$CHANGE_TARGET..HEAD" | sed -n '/./{p;q}')
          git show "origin/harness-evidence:${run_id}.tar.gz" > approval.tar.gz
          harness verify --bundle approval.tar.gz
          harness verify-approval --base "origin/$CHANGE_TARGET" --head HEAD --bundle approval.tar.gz --no-workspace
        '''
      }
    }
  }
}

Azure Pipelines

trigger: none
pr:
  branches:
    include: ["*"]

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    fetchDepth: 0
    persistCredentials: false
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "3.12"
  - script: |
      python -m pip install governed-agent-harness  # pin the version you use
      target="${SYSTEM_PULLREQUEST_TARGETBRANCH#refs/heads/}"
      git fetch --no-tags origin harness-evidence "$target"
      run_id=$(git log --format='%(trailers:key=Harness-Run,valueonly)' "origin/$target..HEAD" | sed -n '/./{p;q}')
      git show "origin/harness-evidence:${run_id}.tar.gz" > approval.tar.gz
      harness verify --bundle approval.tar.gz
      harness verify-approval --base "origin/$target" --head HEAD --bundle approval.tar.gz --no-workspace
    displayName: Verify that the merged tree is an approved ChangeSet

In every template the job fails (exit 5 or 6) when no approval in the bundle is bound to the digest of the range; a human decision is never made in CI.