Required Checks

This document describes how we use GitHub Required Checks and how to configure them

Purpose

We're using GitHub Required Checks to make sure that no errors are skipped during our CI process. If a Required Check failed in the Pull Request, GitHub will block the PR from being merged.

How to use GitHub Required Checks

There are different ways of how Required Checks can be used and configured. We're using these two ways:

• Job name to Required Check mapping
• Using special job

Job name to Required Check mapping

This is the standard and straightforward way of using Required Checks. It should be used when you have 1 or 2 jobs (where 1st job is a check of changes) inside a workflow. If you have more dependent jobs or the number of jobs is more than 2 or the conditions to trigger are not just one folder, it is recommended to use "Special job" way. Examples are ClickHouse Build, NPM Size Build, Python.

To configure it:

• Copy name of the job that is required
• Ask @zaibon or someone else with GH repository admin rights to add this name to the list of Required Checks

Special job

This is a small hack that will allow to check all required jobs in the workflow without adding all of them to the list of Required Checks. It should be used when your workflow is not that simple and "Job name to Required Check mapping" would have side effects. Examples are Build Backend, Browser Extension Build v2, VS Code Extension, Build WebApp, Infrastructure.

Let's take a look at "Build Backend" workflow as an example of how it is configured.

There are 3 steps:

• configure required job with "success" output
• add new job that will check "success" outputs from all jobs in a workflow
• add the name of new job as Required Check using the previous "Job name to Required Check mapping" approach

Configure required job with "success" output

To add "success" to the output of the job you need to add two parts.

Add "output" field with description of "success" variable:

go-lint:
  name: 'Lint: Go Applications'
  runs-on: ubuntu-latest
  outputs:
    success: ${{ steps.setoutput.outputs.success }}
  needs: vars

Add the step to set this output as the last step of the job:

- name: Set success output
  id: setoutput
  run: echo "success=true" >> $GITHUB_OUTPUT

Add new job that will check "success" outputs from all jobs in a workflow

As the last job of the workflow or before jobs that will run only for QA env, add a job using this as an example:

status-check:
  name: 'Check: Build Backend'
  runs-on: ubuntu-latest
  if: needs.changes.outputs.positive == 'true' && always() # always run, so we never skip the check
  needs:
    - go-lint
    - go-test
    - go-integration
    - go-pipeline-integration
    - docker-build-db-migrations
    - docker-build-api
    - docker-build-spider
    - docker-build-dataflow

  steps:
    - name: Check go-lint
      run: |
        passed="${{ needs.go-lint.outputs.success }}"
        if [[ $passed != "true" ]]; then
          exit 1
        fi

    - name: Check go-test
      run: |
        passed="${{ needs.go-test.outputs.success }}"
        if [[ $passed != "true" ]]; then
          exit 1
        fi

    - name: Check go-integration
      run: |
        passed="${{ needs.go-integration.outputs.success }}"
        if [[ $passed != "true" ]]; then
          exit 1
        fi

    - name: Check go-pipeline-integration
      run: |
        passed="${{ needs.go-pipeline-integration.outputs.success }}"
        if [[ $passed != "true" ]]; then
          exit 1
        fi

    - name: Check docker-build-db-migrations
      run: |
        passed="${{ needs.docker-build-db-migrations.outputs.success }}"
        if [[ $passed != "true" ]]; then
          exit 1
        fi

    - name: Check docker-build-api
      run: |
        passed="${{ needs.docker-build-api.outputs.success }}"
        if [[ $passed != "true" ]]; then
          exit 1
        fi

    - name: Check docker-build-spider
      run: |
        passed="${{ needs.docker-build-spider.outputs.success }}"
        if [[ $passed != "true" ]]; then
          exit 1
        fi

    - name: Check docker-build-dataflow
      run: |
        passed="${{ needs.docker-build-dataflow.outputs.success }}"
        if [[ $passed != "true" ]]; then
          exit 1
        fi

Let's break down important parts.

if statement:

• needs.changes.outputs.positive == 'true' is needed to run it only if there are changes that should trigger this workflow
• always() is needed to run it regardless of the status of other jobs
• combining both together gives us: "run always if there are changes that should trigger this workflow"

needs - a list of all jobs that should finish before this job will start. Remember that always() in the if statement allows us to ignore the status of the jobs - we just need them to be processed and report any status.

steps - a list of steps to perform. For this particular job, each step is a verification of another job in the workflow. You need to write appropriate name of the job for the passed variable using this syntax: needs.JOB_NAME.outputs.success. If the required job ran and passed successfully, the success output will be true and these steps will check that. If required job didn't ran successfully for any reason, the step of this job will fail and this will fail the whole Check job.

Add the name of new job as Required Check

Using the previous "Job name to Required Check mapping" approach add the Check job to the list of Required Check in GitHub Repository settings.