README.md

Rust CI/CD template

Template to maintain a rust project running CI/CD with Github Workflows.

CI Workflow

ci.yaml

This workflow will run every time you push to main or make a pull request. You can also run the workflow manually in github.

It will run:

• cargo build: Compiling for ubuntu-latest.
• cargo fmt:
  • Rust Formatter.
  • Check for the file rustfmt.toml.
• cargo clippy:
  • Lints catch common mistakes and improve your Rust code.
  • Check for the sections [lints.rust] and [linsts.clippy] in the Cargo.toml file.
• cargo doc: Build the documentation.
• cargo doc --test: Run tests in the documentation, only if the crate is a lib.
• cargo-nextest: Execute unit and integration tests.
• cargo miri test: Help to detect certain classes of undefined behavior.
• typos:
  • Source code spell checker.
  • Check for the typos.toml file.
  • docs
• taplo fmt: Toml formatter.
• markdownlint-cli2:
  • Markdown linter and formatter.
  • Check for the file .markdownlint.yaml
• yamlfmt: Yaml formatter.
• cargo deny:
  • Check for licenses, bans, advisories and sources.
  • Check for the deny.toml file.
  • template
  • docs
• cargo audit:
  • Check for security vulnerabilities.
  • Uses the advisory-db
• cargo msrv: Keep the rustc version on check.

CD Workflow

build_and_release.yaml

This workflow will only run manually through GitHub.

It will:

• Validate your input version with regex (e.g. v3.1.4-alpha+159).
• Run the ci workflow.
• Run cargo semver-checks:
  • Lint your crate API changes for semver violations.
  • This will only run if you crate is a library.
  • Uses your previous tag as a baseline.
• Run add-notice:
  • Add header notices to your rust files.
  • Check for the NOTICEe file.
  • Auto-commit.
• Run cargo-bump:
  • Bump the current version of the Cargo.toml file.
  • Uses the input version if provided.
  • Auto-commit.
• Run cargo-attributions:
  • Comply with licenses distribution.
  • Add licenses, notices and metadata of your dependencies.
  • Crate an attribution folder
  • Auto-commit.
• Create a new tag:
  • Uses the input version if provided.
  • It's created only if the tag not exists.
• Create a new github release:
  • Uses create-gh-release-action
  • Includes your changelog if matches the same version.
  • Uses the created tag as a reference.
• Build and Release in Github:
  • Using upload-rust-binary-action
  • And setup-cross-toolchain-action
  • Only builds if your crate contains a binary crate.
  • Uses the created tag as a reference.
  • Bundle the attribution folder with licenses and notices.
  • Create checksum with sha256.
  • It builds for linux: gnu (x86_64|aarch64|riscv64gc) and musl (x86_64|aarch64).
  • It builds for windows: msvc (x86_64|aarch64) and gnu (x86_64).
  • It builds for mac-os (x86_64|aarch64).
• Publish the create to crates.io:
  • Only if you have the secrets.CARGO_REGISTRY_TOKEN variable added to repository secrets.
  • Path: Settings -> Security -> Secrets and variables -> Actions -> Repository secrets.

How to use the Build and Release workflow

You will run this directly in your Github repo -> Section Actions -> [Main] Build & Release workflow. -> Run workflow button.

Here you can do three things to run the workflow:

1. Write the new version you want to release: - The version is in the form of:
   • Version parts: ${MAJOR}.${MINOR}.${PATCH}-${PRE-RELEASE}+${BUILD}
   • Example: 3.1.4-alpha+159
2. Select the release_type you want:
   • patch, minor and major.
   • It will use your current crate version as a baseline.
   • Keep in none if you only want the writing version.
3. Keep all with the defaults (without version and release_type = none)
   • It will use your current crate version as a baseline.
   • Run if you already update your crate version.
   • Useful for testing when you already run the workflow.

The two booleans allow you to publish your crate to creates.io and overwrite your tag to add modifications to a release, respectively.

Dependabot

This template includes a setup for dependabot and a workflow for auto-merge.

• It will update packages for cargo and github-actions weekly.

• For rust:

  • It will create pull request in groups.
  • One group for patch updates, one for minor updates and one for major updates.
  • It will auto-merge the pull request if passes ci.

• For github-actions:

  • It will create a pull request in groups.
  • Only one group for the updates.
  • It will auto-merge the pull request if passes ci.

Other workflows

This template uses workflow call and workflow dispatch to reuse workflows and be able to run them individually. So you can run various jobs of the ci/cd workflows independently.

Some workflows to consider:

• weekly-workflow
  • Run the ci workflow.
  • Update Dependencies, Attributions and Notices.
• monthly-workflow
  • Run the build_and_release workflow.
  • Do a patch release and publish to crates.io
• update_msrv.yaml
  • It will run cargo-msrv to update your rust-version in Cargo.toml
  • If you uses the MSRV in your README.md it will also updated it.
• cargo_semver_checks
  • Test semver violations before releasing.
• cache.yaml
  • To clean the caches generated for the workflows.
  • Run if you have problems with the cache.
• add_notice.yaml
  • To replace and update your notices.
  • To apply notices to other kind of files.
  • To use different comment styles.
• publish.yaml
  • To publish your crate to crates.io.

What to change if you want to use this template

• Change this file.
• Change the metadata in Cargo.toml
• Change the licenses files. Right now uses LICENSE-CC0-1.0, LICENSE-MIT and LICENSE-Apache-2.0.
• Change the deny.toml file.
• Change the NOTICE file:
  • Remove the notice in main.rs.
  • Or you can run add-notice --remove before you update the NOTICE file.
• Change the FUNDING.yaml file.

Similar projects that might help you

• cargo-dist.
• cargo-release.
• release-plz.
• cargo-smart-release.

LICENSE

SPDX-License-Identifier: CC0-1.0 OR MIT OR Apache-2.0

Licensed under a triple license at your option:

• CC0-1.0 license.
• MIT license.
• Apache-2.0 license.