Github Actions #
In a nutshell, add the following to your .github/workflows/ci.yml:
- name: Coderrect Scan uses: coderrect-inc/coderrect-github-action@main
Continuous Integration/Continuous Delivery (CI/CD) is a common practice now for developing software. In CI, typically tests and checks are run against every pull request and code commit to ensure the new code changes do not break anything or introduce new bugs. CI makes it easier to fix bugs quickly and often.
If your code is hosted on GitHub, you can create custom CI/CD workflows directly in your GitHub repository with GitHub Actions.
In this tutorial, we take memcached as an example project to demonstrate how to set up GitHub Actions.
To start, you can click the “Action“ tab above your GitHub Repository.
Once you enter the Action tab, GitHub will guide you to create your own CI/CD script by providing different template scripts based on different building system.
Here we select “set up a workflow yourself“ to use the basic template.
GitHub will automatically create a YAML file (main.yml by default) under .github/workflows and this is the path which you should put your future scripts under. The left-hand side is the script editor and the right-hand side is the place you can search different existing Action scripts published in GitHub Marketplace.
The default template script looks similar as below, we will explain it in detail:
# This is a basic workflow to help you get started with Actions name: CI # Controls when the action will run. on: push: branches: [ master ] pull_request: branches: [ master ] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # Defines the workflow of this action. jobs: # This workflow contains a single job called "build" build: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v2 # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project.
The definition of an action consists of two major parts: on and jobs.
Field on defines when this action will be triggered. The default template only triggers the action when there’s a push or pull request made upon the main branch.
For example, if you want the action to be triggered at any event on any branch, you can simply change the script to:
on: [push, pull_request]
If you only want to trigger actions manually, then you should specify workflow_dispatch instead. This will create a button in the Action Tab for you to trigger them manually later. Check out this blog on how to manually trigger GitHub Actions.
Field job defines the actual workflow of the action. The subfield build is a customized job name, and you can change it to something more meaningful, such as test-build-on-ubuntu.
runs-on specifies the system image on which you want to run your CI/CD tasks.
steps specifies the detailed sub-tasks performed in a job. You can compose your CI/CD job using the published Actions from GitHub Marketplace and your own customized scripts.
Integrating Coderrect into Github CI #
Coderrect provides a GitHub Action in Marketplace for you to integrate it into your CI/CD process easily.
In general, integrating Coderrect requires 3 steps:
steps: # step 1 - uses: actions/checkout@v2 # step 2 - name: Install deps run: | sudo apt-get update -y sudo apt-get install -y libevent-dev libseccomp-dev git libsasl2-dev - name: Build run: | gcc --version ./autogen.sh ./configure --enable-seccomp --enable-tls --enable-sasl --enable-sasl-pwdb make -j # step 3 - name: coderrect scan uses: coderrect-inc/coderrect-github-action@main
Step 1 checks out your GitHub repository, using an action provided by GitHub.
Step 2 installs all dependencies required for build the project (“Install deps”) and does a test build (“Build“). Note that including task “Build“ is not required for Coderrect to function, but it’s critical to make sure your project can successfully build before applying Coderrect.
Step 3 applies Coderrect to your project. You can search the GitHub Marketplace to obtain the most updated script and all available options.
Once this script is saved, the GitHub Action you just defined will be automatically triggered when you push new commits or merge pull requests. You can review them by entering the “Action“ tab.
By clicking the specific task (“Update ci.yml“ in the example above), you can view its detailed results.
To see Coderrect’s race detection report, you can click task “coderrect scan“ to expand its terminal output. Coderrect will output a list of summary for all executables it analyzes and also attach an report link at the end for you to view them in detail.
Configure Coderrect GitHub Action: #
If you are using a different building system (e.g., CMake) or a different language or compiler, then you need to properly configure Coderrect. Here we provide instructions for some commonly used configurations, more detailed instructions can be found on our GitHub Action page and Coderrect documentation.
For CMake projects
You will need to install and setup cmake first.
- name: download cmake run: | wget https://cmake.org/files/v3.18/cmake-3.18.2-Linux-x86_64.tar.gz tar xf cmake-3.18.2-Linux-x86_64.tar.gz mkdir build && cd build ../cmake-3.18.2-Linux-x86_64/bin/cmake ..
One significant difference for CMake projects is that you need to specify the build path. For example, if you are building your project under ./build, then you need to specify the build path using following script:
- name: Coderrect Scan uses: coderrect-inc/coderrect-github-action@main with: buildPath: "build"
For FORTRAN projects
You will need to install the FORTRAN compiler. For example:
- name: Install fortran run: | sudo apt-get update -y sudo apt-get install -y gfortran
Then it is likely that you need to specify the FORTRAN compiler when you use make.
If so, Coderrect provides an optional input called buildCommand to specify your customized build command.
- name: coderrect scan uses: email@example.com with: buildCommand: "make COMPILER=GNU MPI_COMPILER=gfortran C_MPI_COMPILER=gcc"
For customized analysis
Coderrect’s GitHub Action provides an input called options that allows you to provide arbitrary options supported in Coderrect’s CLI. A common use case is to provide Coderrect with a fully-customized JSON configuration using -conf.
In order to do so, check our documentation to see available configuration items. Once you write a configuration file (say coderrect.json). You can pass it to the scanner as below:
- name: coderrect scan uses: firstname.lastname@example.org with: options: "-analyzeAllBinaries -conf=/path/to/coderrect.json"
The path should be a relative path from your build directory (e.g., if your build directory is ./build/ and your config file is under the root path, then you should specify the config file as “-conf=../coderrect.json”).