GitLab CI template for Rust

This project implements a GitLab CI/CD template to build, test, and analyse your Rust projects with Cargo.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/rust/gitlab-ci-rust@1.0.0
    # 2: set/override component inputs
    inputs:
      # ⚠ this is only an example
      build-args: "--all-targets --all-features"

Use as a CI/CD template (legacy)

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: "to-be-continuous/rust"
    ref: "1.0.0"
    file: "/templates/gitlab-ci-rust.yml"

variables:
  # 2: set/override template variables
  # ⚠ this is only an example
  RUST_BUILD_ARGS: "--all-targets --all-features"

Global configuration

The Rust template uses some global configuration used throughout all jobs.

Input / Variable	Description	Default value
image / RUST_IMAGE	The Docker image used to run cargo	docker.io/library/rust:latest
rustflags / RUST_RUSTFLAGS	Compiler flags to pass to all rustc invocations.	none
project-dir / RUST_PROJECT_DIR	Cargo project root directory	.

Jobs

rust-build-test job

This job performs build and tests running cargo build and cargo test.

It uses the following variable:

Input / Variable	Description	Default value
build-args / RUST_BUILD_ARGS	Arguments used by cargo build	none
build-rustflags / RUST_BUILD_RUSTFLAGS	Compiler flags for rust-build rustc	none
test-args / RUST_TEST_ARGS	Arguments used by cargo test	none
test-binary-args / RUST_TEST_BINARY_ARGS	Arguments used by the test binary (see cargo test -- -h)	none
test-rustflags / RUST_TEST_RUSTFLAGS	Compiler flags for rust-test rustc	none

[!information] The Rust template doesn't support yet the integration of either a unit test report or code coverage report.

SonarQube analysis

If you're using the SonarQube template to analyse your Rust code, here is a sample sonar-project.properties file:

# see: https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/languages/rust/
# disable Clippy analysis and supply JSON report
sonar.rust.clippy.enable=false
sonar.rust.clippy.reportPaths=reports/rust-clippy.native.json

More info:

• Rust language support

rust-clippy job

This job runs Clippy to analyze your code. It is mapped to the build stage.

It uses the following variables:

Input / Variable	Description	Default value
clippy-disabled / RUST_CLIPPY_DISABLED	Set to true to disable the Clippy analysis	none (enabled)
clippy-args / RUST_CLIPPY_ARGS	Clippy options and arguments. Be sure to prefix with -- for clippy arguments.	--all-targets --all-features -- --deny warnings

In addition to logs in the console, this job produces the following report:

Report	Format	Usage
$RUST_PROJECT_DIR/reports/rust-clippy.native.json	JSON	SonarQube integration This report is generated only if SonarQube template is detected

rust-audit job

This job runs cargo audit to scan for vulnerabilites in the dependencies. It is mapped to the test stage.

It uses the following variables:

Input / Variable	Description	Default value
audit-disabled / RUST_AUDIT_DISABLED	Set to true to disable the Audit (dependency vulnerability scanner)	none (enabled)
audit-args / RUST_AUDIT_ARGS	Arguments for cargo audit (see cargo audit -h)	none

rust-publish job

This job is disabled by default and performs a cargo publish of your cargo project.

It uses the following variables:

Input / Variable	Description	Default value
publish-enabled / RUST_PUBLISH_ENABLED	Set to true to enable publish	none (disabled)
publish-args / RUST_PUBLISH_ARGS	Arguments used by cargo publish	none
RUST_PUBLISH_TOKEN	crates.io API Token used by cargo publish	must be defined when using crates.io
CARGO_REGISTRIES_<registry_name>_TOKEN	registry_name API Token used by cargo publish	must be defined when using an alternate registry

Currently, GitLab does not support cargo registries.

Using an alternate registry

An alternate registry (other than crates.io) can be configured in the in a .cargo/config.toml. More information is available here

Example configuration:

# .cargo/config.toml

[registries]
my-registry = { index = "https://my-intranet:8080/git/index" }

Specify the registry token with CARGO_REGISTRIES_MY_REGISTRY_TOKEN.

Secrets management

Here are some advices about your secrets (variables marked with a ):

1. Manage them as project or group CI/CD variables:
2. masked to prevent them from being inadvertently displayed in your job logs,
3. protected if you want to secure some secrets you don't want everyone in the project to have access to (for instance production secrets).
4. In case a secret contains characters that prevent it from being masked, simply define its value as the Base64 encoded value prefixed with @b64@: it will then be possible to mask it and the template will automatically decode it prior to using it.
5. Don't forget to escape special characters (e.g.: $ -> $$).