Triggering CI and third-party tools via the web application

You often want to integrate various tools into your workflow, or show status badges. QA-Board lets you connect to those third-party tools on each commit's page and on commit index pages:

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

Adding badges and external links

Configure your project's qaboard.yaml like so to display direct links to docs, build artifacts, coverage reports, etc:

qaboard.yaml

# Show basic links
integrations:
- text: Docs
  href: https://my-project/docs

# Show images, commonly used to display "badges"
- src: https://gitlab.com/my/project/badges/develop/coverage.svg
  href: https://my-project/docs
  alt: Coverage Report
  # if you want to display items in the side-bar directly,
  # not within the "Integrations" menu, you can use:
  in_menu: false

# A GitHub Actions badge, on branch pages
- 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

note

QA-Board loads images through its 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.

tip

The menu item will be disabled if the link doesn't work (HTTP HEAD request). To show a link but run the check on an other URL, you can provide url, method (e.g. POST), etc. If you add allow_failed: true the link is always enabled.

Styling the integrations

Optionnaly you can style each menu item:

integrations:
  - text: Styled Integration
    # Full list of icons: https://blueprintjs.com/docs/#icons
    icon: build
    # Full list of options: https://blueprintjs.com/docs/#core/components/menu
    label: docs
    disabled: false
    intent: danger

You can add dividers to group integration:

integrations:
  # --snip--
  - divider: true
    title: Section Title
  # --snip--

Show nested items with:

integrations:
- text: "level 1"
  sub:
  - text: level 1: A
  - text: level 1: B

Using webhooks

You can use webhooks to trigger a variety of external tools:

integrations:
  - text: Jenkins Triggered Build
    sub:
    - text: 'Windows'
      icon: build
      webhook:
      # all the options are sent straight to the python requests library. For reference:
      # https://requests.readthedocs.io/en/latest/api/#requests.request
         url: "https://my-application/${project}"
         method: POST
         json: # use "data" for a x-www-form-url-encoded body
           branch: "${commit.branch}"

If the response is in JSON format, users will see a status badge pointing to its url field. It will open automatically if the response has a open: true field. You can specify additionnal properties like explained below.

Dynamic integrations using "variables"

You can use some special variables in your strings with some ${VARIABLE} templating:

• Commit: commit.id, commit.branch, commit.branch_slug... Also branch and ref_commit.id.
• Project: project (full project name), subproject (project name relative to the root project),
• Git repository data with git, 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, e.g. git.id.
• Artifacts are saved under commit.artifacts_url = commit.repo_artifacts_url / subproject.
• Outputs are saved under commit.outputs_url
• Selected runs: with batch, ref_batch, filter, ref_filter, ref_project...
• User properties: user.user_name (you will get null if logged out), or other fields like email, full_name, is_logged...
• etc

tip

If you use use ${branch} in any of the fields, the integration will only appear on project/branch pages. You can add a dummy only: {branch}.

Start 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 (you 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.

Play GitlabCI manual jobs

Configure your project with:

qaboard.yaml

integrations:
  - text: Gitlab Job
    gitlabCI:
      job_name: build-linux

An older recording: the menu is now named Integrations.

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.

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.

Badges that fail to load (e.g. for private projects, or projects without CI) are hidden.

Trigger Jenkins builds

qaboard.yaml

integrations:
  - text: Jenkins Triggered Build
    jenkins:
      build_url: $JENKINS_URL/job/my-project-linux
      # You can include the token from the job's configuration page
      # token: qaboard   # default value # FIXME: make it empty in the OSS version
      parameters:
        commit: "${commit.id}"

You must enable "triggering the build via scripts/webhooks" in the job's configuration. Parameters are optional.

Once a build is triggered, its status (queued, running, success, failure...) is updated every 10 seconds next to the menu item. It is remembered by your browser, so it survives page refreshes (for the last 50 commits).

Webhook Example: Jenkins integration via Webhooks

warning

The out-of-the-box jenkins integration above is much better! This is just an example with webhooks!

1. If you don't have one, get an API token for your user

$JENKINS_URL/me/descriptorByName/jenkins.security.ApiTokenProperty/generateNewToken
# Enter "OK to retry using POST" and get the "tokenValue"

caution

Since you'll commit those credentials with the code, make sure you don't have too many privileges... At some point QA-Board will support secrets.

2. Get a crumb to handle Jenkins' CSRF, eg at $JENKINS_URL/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,%22:%22,//crumb)

3. Go to your Jenkins project configuration page at $JENKINS_URL/$PROJECT/configure and allow triggered builds:

4. Configure your project with:

qaboard.yaml

integrations:
  - text: Jenkins Triggered Build
    webhook:
      method: post
      url: $JENKINS_URL/job/$PROJECT/buildWithParameters
      headers:
        Jenkins-Crumb: $JenkinsCrumb
      params:
        token: $TOKEN
      auth:
        # this needs to be hardcoded with jenkins credentials
        # hopefully of limited scope
        username: <the-jenkins-username>
        password: api-token    # keep as-is
      data:
        commit: "${commit.id}"
        cause: Triggered on the QA web app

Alternatively, you can also send users to the build page:

integrations:
  - text: Build
    label: With Parameters
    icon: build
    href: $JENKINS_URL/view/my-view/job/my-job/build?delay=0sec
    # Jenkins behaves wtf and returns 405 errors...
    # https://issues.jenkins-ci.org/browse/JENKINS-3121
    allow_failed: true