Integrations: links, badges and CI jobs

The sidebar's Integrations menu links each commit to your other tools: docs, dashboards, coverage reports, and buttons that start a CI job or call a webhook for the commit people are looking at. List them under integrations in qaboard.yaml.

The Integrations menu with links and a webhook: after a click, the webhook's tag shows its job's status.

Add links

The camera ISP's menu has two links to its team's docs, a divider, and a webhook:

qaboard.yaml

integrations:
  - text: K3 calibration report
    icon: document
    href: https://docs.kitefin.example/imaging/k3-calibration
  - text: ISP tuning guide
    icon: manual
    href: https://docs.kitefin.example/imaging/isp-tuning-guide
  - divider: true
  - text: Send to the tuning bench
    icon: send-to
    webhook:
      url: http://tuning-bench.kitefin.example/api/jobs
      method: POST
      json:
        project: ${project}
        commit: ${commit.id}
        batch: ${batch}

From examples/image-quality/qaboard.yaml

Each item has a text, and an href to open in a new tab, or an action (below). icon is one of Blueprint's icons.

A link is greyed out when its target doesn't answer: QA-Board's server checks it with a HEAD request (links to QA-Board's own pages, like /s/... files, are checked by the browser). Add allow_failed: true to always enable it, for instance when the target refuses HEAD requests. To check another URL than the one you open, give it as url, with a method if needed.

Which hosts the server calls

The server only checks links, and sends webhooks, to the hosts of the integrations of the project's, the commit's or the batch's qaboard.yaml, the git hosts, the Jenkins hosts of JENKINS_AUTH, and QABOARD_PROXY_HOSTS, also when they redirect. A template in a host, like https://ci-${project_name}.example.com, allows the hosts that end with its last part (.example.com). A host that is only a template, like ${server}/x, isn't known: put such hosts in QABOARD_PROXY_HOSTS. When a link redirects to another host, for instance to a sign-in page, the server doesn't follow it, and the link still works.

Use the commit, the branch or the batch in links

Strings can use ${...} templates, filled with what the page shows. For instance, a link to the commit's checks on GitHub, and a CI badge on branch pages:

qaboard.yaml

integrations:
- text: Checks
  href: "${git.web_url}/commit/${commit.id}/checks"
- src: "${git.web_url}/actions/workflows/ci.yml/badge.svg?branch=${branch}"
  href: "${git.web_url}/actions/workflows/ci.yml?query=branch%3A${branch}"
  alt: CI

When a template uses a value the page doesn't have, the item is hidden. ${branch} is only set on the commit list and on History pages (the branch you look at, else the reference branch): items that use it don't show on commit pages. To show an item only on those pages, add only: "${branch}" to it.

Commit pages show the integrations of the commit's qaboard.yaml, so a change shows on the commits that make it. The commit list and History pages show those of the reference branch's latest qaboard.yaml.

Every variable

Variable	Value
commit	The commit: commit.id, commit.branch, commit.branch_slug (the branch in a URL- and file-friendly form), commit.message, commit.committer_name, commit.outputs_url (where its runs save their outputs), commit.artifacts_url (its artifacts, commit.repo_artifacts_url / subproject)... On the commit list and History pages, the latest commit.
ref_commit	The reference commit: ref_commit.id...
branch, branch_slug	On the commit list and History pages, the branch you look at, else the reference branch.
project	The project's full name, like kitefin/camera-isp.
subproject, project_name	The project's name relative to its repository (see monorepos), and its last part. project_parts and subproject_parts split them on /, and _tolower variants are lowercase.
git	The repository, the same for all git hosts: git.web_url, git.path_with_namespace, git.default_branch, git.hosting_type (github, gitlab, gitea, bitbucket)... GitLab projects also have the other fields of GitLab's push events, like git.id.
batch, ref_batch	On commit pages, the label of the selected batch and of the reference's.
filter, ref_filter, ref_project	On commit pages, the filters of the new and reference runs, and the reference's project.
user	The logged-in user: user.user_name, user.full_name, user.email, user.is_logged. Without a login, user.user_name is null.

Templates are JavaScript template literals: ${encodeURIComponent(branch)} or ${commit.id.slice(0, 8)} work too. The code is make_eval_templates_recursively in webapp/src/utils.js.

Show badges

An item with src shows an image, often a status badge: coverage, pipeline status, the latest release.

qaboard.yaml

integrations:
- src: "${git.web_url}/badges/${branch}/coverage.svg"
  href: https://docs.kitefin.example/coverage
  alt: Coverage report
  # in the sidebar itself, not in the Integrations menu
  in_menu: false

Badges that fail to load, for private projects or projects without CI for instance, are hidden.

note

Images from GitHub, Bitbucket, Codeberg and your git hosts other than GitLab load directly. The others load through QA-Board's server, which only fetches them from your git hosts and Gravatar: to show images from other hosts, ask your admins to add them to QABOARD_PROXY_HOSTS.

Start CI jobs

People start the jobs from the menu, for the commit they're looking at: a status tag next to the item shows whether the job is pending, running, successful or failed, and opens the job's page. The tags refresh every 5 seconds while the menu is open, and each browser remembers the jobs it started on the last 50 commits.

GitHub Actions workflows

The workflow needs a workflow_dispatch trigger. Configure your project with:

qaboard.yaml

integrations:
  - text: Benchmark
    githubActions:
      workflow: benchmark.yml  # the file name in .github/workflows, or the workflow's id
      # optional: the workflow's inputs
      inputs:
        commit: "${commit.id}"
      # optional: the branch or tag to run it on. Default: the commit's branch
      # ref: main

The menu shows the status of the workflow's latest run for the commit, with a link to it. Clicking starts the workflow (users need to be logged in), and QA-Board follows the run it started.

The server starts workflows with its own token, so it only shows and starts the workflows that the project's qaboard.yaml lists (the one of its reference branch), on the project's repository, and only for users who can access the project. To start one, the inputs must be those of the integration (the same names), and the ref too if you set one. ${...} templates in workflow, inputs and ref match any value.

note

GitHub runs workflows on the latest commit of a branch or tag, not on a given commit. If the branch moved on, use an input to tell your workflow which commit to check out.

GitHub doesn't say which run a dispatch started: QA-Board follows the latest run started by a dispatch on that branch or tag since you clicked. If someone else starts the same workflow on the same branch at the same time, it may show their run.

The QA-Board server needs a GitHub token that can read the repository's actions, and write them to start workflows (fine-grained token: Actions: Read and write). See Git hosts.

GitLab CI manual jobs

qaboard.yaml

integrations:
  - text: Linux build
    gitlabCI:
      job_name: build-linux

Clicking plays the job of that name in the commit's latest pipeline (users need to be logged in, and to be developers of the project). The server uses its own token, so it only shows and plays the jobs of the project's repository, for users who can access the project. The QA-Board server needs a GitLab token with the api scope to play jobs (read_api is enough to show their status). See Git hosts.

Jenkins builds

qaboard.yaml

integrations:
  - text: Windows build
    jenkins:
      build_url: https://jenkins.kitefin.example/job/camera-isp-windows
      # optional: the job's parameters (`parameters` works too)
      params:
        commit: "${commit.id}"
      # optional: the token of "Trigger builds remotely" in the job's configuration
      # token: ...

Clicking starts the build: users need to be developers of the project. In the job's configuration, enable Trigger builds remotely (e.g., from scripts). The QA-Board server triggers the build with the credentials of the Jenkins host in its JENKINS_AUTH environment variable:

{"jenkins.kitefin.example": {"user": "<user>", "token": "<api-token>", "crumb": "<crumb>"}}

<api-token> is an API token of that Jenkins user, created in their Jenkins settings, and <crumb> the answer of <jenkins>/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb), which handles Jenkins' CSRF protection. See the server's environment variables. To check the builds' status, the server only uses these credentials on the hosts of JENKINS_AUTH, on the default ports of http and https, or with the scheme and port of a Jenkins job of the projects' qaboard.yaml (e.g. http://jenkins:8080/job/x).

token is the Authentication Token of the job's Trigger builds remotely. Without token, the server sends the token in its JENKINS_BUILD_TOKEN environment variable, if it's set, and none otherwise; token: "" never sends one. qaboard.yaml is in your repository: when the token is a secret, keep it in JENKINS_BUILD_TOKEN.

Call a webhook

A webhook sends a request when people click, from QA-Board's server (users need to be logged in). Its options are those of Python's requests: url, method, json (or data for a form), params, headers, and auth with a username and a password. The server only calls the hosts of the integrations, and doesn't send users' cookies or pass back the answer's.

qaboard.yaml

integrations:
  - text: Send to the tuning bench
    icon: send-to
    webhook:
      url: http://tuning-bench.kitefin.example/api/jobs
      method: POST
      json:
        project: ${project}
        commit: ${commit.id}
        batch: ${batch}

After a click, a tag next to the item shows the answer's status. If the answer is JSON:

• a status field (pending, running, success, failed...) shows as an icon, like for CI jobs;
• a url field makes the tag a link to it;
• with open: true too, the link opens right away.

caution

qaboard.yaml is in your repository: don't put credentials in webhooks. To start Jenkins builds, use the Jenkins integration, whose credentials stay on the server.

Default integrations

If your qaboard.yaml has no integrations, branch pages show defaults for your git host, when QA-Board knows which kind it is (from its push events, or the server's git hosts): GitLab's pipeline status badge, or a link to GitHub Actions. Set integrations: [] to hide them.

Organize the menu

Items take the options of Blueprint's menu items: icon, label (shown on the right), intent (primary, success, warning, danger), disabled...

qaboard.yaml

integrations:
  - text: Release checklist
    icon: build
    label: docs
    intent: danger
  # a divider, with an optional title
  - divider: true
    title: Benchmarks
  # a submenu
  - text: Builds
    sub:
    - text: Linux
      gitlabCI:
        job_name: build-linux
    - text: Windows
      jenkins:
        build_url: https://jenkins.kitefin.example/job/camera-isp-windows

• in_menu: false shows an item in the sidebar itself, outside the menu.
• With more than 5 items, a search box appears at the top of the menu.