Rust CI with GitHub Actions

Table of Contents

1. Workflows
   • Check and Lint (check-and-lint.yaml)
   • Test with Code Coverage (test.yaml)
   • Release Packaging (release-packaging.yaml)
2. How to Use
3. License

Workflows

The CI process is separated into 3 workflows: Check and Lint, Test, and Release Packaging.

All jobs run on ubuntu-latest, and are run in parallel.

All jobs use actions/checkout@v2 and actions-rs/toolchain@v1.

Check and Lint (check-and-lint.yaml)

This workflow checks for compiler errors and code style inconsistencies. It runs on pull requests and main branch push.

Check job

This job runs cargo check on the stable toolchain.

It checks if there are compiler errors.

Rustfmt job

This job runs rustfmt with the --check option through cargo fmt on the stable toolchain.

By default, it checks inconsistencies with the Rust style guide. You can add a rustfmt.toml or .rustfmt.toml to configure the style.

Clippy job

This job runs clippy on the stable toolchain through actions-rs/clippy-check@v1. You can add a clippy.toml or .clippy.toml to configure the style.

• The action outputs result (Clippy Output added to a random workflow), and
• For pull requests, it adds annotations on the diff.

Test with Code Coverage (test.yaml)

This workflow run tests, outputs test results, publishes code coverage results on CodeCov. Publishing test results and code coverage data is in one job to avoid running the tests twice. It runs on pull requests and main branch push.

Test job

This job:

1. Caches dependencies,
2. Runs tests and generate test results and code coverage data,
3. Uploads test results, and
4. Uploads to CodeCov.

Environment variables used in this job:

• PROJECT_NAME_UNDERSCORE - project name with hyphens(-) as underscores(_) needed for code coverage
• CARGO_INCREMENTAL, RUSTFLAGS, RUSTDOCFLAGS - added to CARGO_OPTIONS in cargo test needed for code coverage

Steps:

1. Cache dependencies. It caches download and compilation of dependencies based on a hash of Cargo.lock to shorten build time with actions/cache@v2.

   • The key is ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('Cargo.lock') }} where env.cache-name: cache-dependencies.
   • Cache is stored at the end of the job on cache miss. Cache is not updated on cache hit.

2. Generate test results and code coverage data.

   1. It installs cargo2junit needed for formatting the test result and grcov for code coverage.
   2. It runs cargo test in the nightly toolchain.
   • $CARGO_OPTIONS includes CARGO_INCREMENTAL, RUSTFLAGS, and RUSTDOCFLAGS options needed for code coverage.
   • -Z unstable-options --format json formats the test result into json.
   • | cargo2junit > results.xml converts the json result into junit format for EnricoMi/publish-unit-test-result-action to understand and saves it as results.xml.
   4. It generates code coverage data in lcov format through grcov saved as lcov.info.

3. Upload test results. It uploads the test result (results.xml) through EnricoMi/publish-unit-test-result-action@v1.

   • The action outputs the test result (Test Results added to a random workflow).
   • For pull requests, the action adds a comment containing the test results.

4. Upload to CodeCov. It uploads the code coverage result (lcov.info) to CodeCov through codecov/codecov-action@v1.

   • For pull requests, the actions adds a comment containing the code coverage report.
   • For private repositories, add your token from CodeCov repository setting on GitHub Secrets and uncomment the line: token: ${{ secrets.CODECOV_TOKEN }}.

Release Packaging (release-packaging.yaml)

This workflow builds the package in release mode and uploads resulting file as a GitHub artifact. It runs on main branch push.

Release Packaging job

This job builds the project in release mode and uploads the binary as an artifact through actions/upload-artifact@v2.

The binary target/release/${{ env.PROJECT_NAME_UNDERSCORE }} is uploaded as ${{ env.PROJECT_NAME_UNDERSCORE }}.

How to Use

1. Replace the value of PROJECT_NAME_UNDERSCORE with your project name (replace hyphens(-) as underscores(_)).

2. Customize when to call the workflows (like branch names)

3. Customize options:

   • Configure rustfmt and clippy with TOML files.
   • Customize cargo test options (like excluding certain tests).
   • Configure paths to upload from release build (like uploading multiple binary artifacts).

Notes:

• secrets.GITHUB_TOKEN is needed by some actions to create GitHub checks & annotations. it is added automatically by GitHub.
• uses cache for GitHub actions.
• clippy html output and test result output are added to random workflows for a certain commit due to limitations in the GitHub Actions API.

License

MIT