CI/CD And Merge Queue Configuration#

Overview#

The CI/CD And Merge Queue Configuration for the libmagic-rs project implements a comprehensive, automated software development lifecycle infrastructure. The system combines GitHub Actions workflows, Mergify merge queue automation, and cargo-dist release automation to ensure code quality, security, and reliable distribution. This infrastructure enforces strict quality gates through continuous integration checks, automates dependency updates and releases, and maintains a clean git history through squash merging.

The system is built on several key principles: comprehensive cross-platform testing (Ubuntu, macOS, Windows), security-first dependency management through cargo-deny and cargo-audit, tiered merge automation prioritizing trusted contributors, and separation of concerns between crates.io publishing (release-plz) and binary distribution (cargo-dist). All pull requests must pass a suite of nine CI checks before merging, and the infrastructure explicitly avoids path filtering on critical workflows to ensure comprehensive validation.

The project requires DCO (Developer Certificate of Origin) sign-off on all commits, enforced through a GitHub DCO App. The configuration supports both Dependabot and release-plz automation with auto-queue rules while maintaining strict quality controls.

GitHub Actions Workflows#

Overview#

The repository contains 10 GitHub Actions workflow files that orchestrate continuous integration, security scanning, documentation, benchmarking, compatibility testing, and release automation. These workflows use mise for tool management and just as a command runner for consistent execution across local and CI environments.

Primary CI Workflow (ci.yml)#

The primary CI workflow runs on push to main and pull requests without path filtering. It includes concurrency controls to cancel in-progress runs when new commits are pushed.

Quality Job#

The quality job runs just lint-rust, which executes:

• cargo fmt --check - Ensures code formatting compliance
• cargo clippy -- -D warnings - Linting with all features enabled, treating warnings as errors

Test Job#

The test job runs on ubuntu-latest and performs:

• cargo nextest run --all-features - Fast test execution
• cargo build --release --all-features - Validates release builds

Test Cross-Platform Job#

The test-cross-platform job depends on the test job and uses a matrix strategy to test on:

• ubuntu-latest (Linux)
• ubuntu-22.04 (Linux)
• macos-latest (macOS)
• windows-latest (Windows)

Coverage Job#

The coverage job depends on the test job and generates test coverage using cargo llvm-cov, uploading results to Codecov.

Security Workflows#

Audit Workflow (audit.yml)#

The audit workflow runs cargo-audit to check for security vulnerabilities. It is triggered by:

• Push when dependency files change (path filtering enabled)
• Scheduled daily at midnight UTC
• Manual dispatch

Security Workflow (security.yml)#

The security workflow performs three security checks:

1. cargo deny check - License and dependency policy enforcement
2. cargo outdated - Identifies outdated dependencies
3. cargo dist check - Validates distribution configuration

It is triggered by:

• Workflow run completion of the CI workflow
• Scheduled daily at 6 AM UTC
• Manual dispatch

No path filtering is applied, ensuring comprehensive security checks on all changes.

Scorecard Workflow (scorecard.yml)#

The scorecard workflow performs supply-chain security analysis using OSSF Scorecard. It is triggered weekly and on branch protection changes.

Supporting Workflows#

Benchmarks Workflow (benchmarks.yml)#

The benchmarks workflow runs cargo bench and includes a benchmark comparison job for PRs. It uses path filtering to only run when performance-critical code changes.

Compatibility Tests Workflow (compatibility.yml)#

The compatibility workflow validates compatibility with the original libmagic across multiple platforms. It runs without path filtering on push and PR to main/develop and daily.

Documentation Workflow (docs.yml)#

The documentation workflow builds mdBook and rustdoc, combining them into unified documentation. The deploy job publishes to GitHub Pages on main branch pushes.

Path Filtering Strategy#

Path filtering is strategically applied only to workflows that are expensive or only relevant to specific changes:

• audit.yml: Filtered to dependency files
• benchmarks.yml: Filtered to performance-critical directories
• copilot-setup-steps.yml: Filtered to its own file

Critical workflows run unconditionally without path filtering:

• ci.yml (quality, test, coverage)
• security.yml (deny, outdated, dist checks)
• compatibility.yml
• docs.yml

This ensures comprehensive validation on all changes while optimizing CI resource usage for non-critical checks.

Mergify Merge Queue Configuration#

Overview#

The .mergify.yml configuration implements a comprehensive merge automation strategy with a three-tier PR handling system and strict quality controls. All PRs pass through a single "default" merge queue.

Merge Method and Strategy#

All PRs are merged using squash merge, consolidating all commits into a single commit on the main branch for clean linear history.

The configuration includes an automatic update rule that keeps PRs up to date with the main branch for non-draft, non-conflicting PRs (excluding Dependabot).

Automatic Queueing#

PRs are automatically added to the merge queue when they meet their queue conditions. Auto-queueing is controlled globally via auto_merge_conditions: true in the merge_protections_settings section. This global setting applies to all queue rules (dosubot, dependabot, release-plz, and default), eliminating the need for manual queue actions or separate PR rules to trigger queueing.

The per-queue-rule autoqueue field is deprecated and was removed before the 2026-07-16 deadline. The behavior remains the same -- PRs that meet their queue_conditions are automatically queued -- only the configuration syntax changed from per-rule autoqueue: true to the global auto_merge_conditions: true setting.

The queue is configured with branch_protection_injection_mode: none, meaning Mergify does not inject its own branch protection rules. Instead, all protections are explicitly defined in the configuration.

Queue Conditions#

PRs are automatically queued when they satisfy the queue_conditions:

• DCO check passes (check-success = DCO)
• PR has the "lgtm" label (label = lgtm)
• OR the PR author is dependabot[bot] or dosubot[bot] (automated PRs bypass the lgtm requirement)

This ensures that all PRs require both DCO sign-off and human approval (via the lgtm label), except for trusted bot accounts that can be auto-queued.

Required Status Checks#

The merge queue requires nine CI checks to pass:

1. check-success = quality - Code quality checks (fmt, clippy)
2. check-success = test - General test suite
3. check-success = test-cross-platform (ubuntu-latest, Linux)
4. check-success = test-cross-platform (ubuntu-22.04, Linux)
5. check-success = test-cross-platform (macos-latest, macOS)
6. check-success = test-cross-platform (windows-latest, Windows)
7. check-success = coverage - Code coverage checks

These same checks are enforced in the merge_protections section to prevent manual merges that bypass the merge queue.

Release-Plz PR Exemption#

PRs with branch names matching ^release-plz- are exempt from the CI merge protection requirement. This exemption exists because:

• release-plz force-pushes when updating existing PRs
• GITHUB_TOKEN-triggered pushes suppress workflow events, so CI never runs on the new HEAD
• Without this exemption, the merge protection would hang indefinitely waiting for CI that never runs
• release-plz PRs only bump versions and changelogs — the underlying code was already tested on main before the release PR is created
• CI still runs in the merge queue as a final safety net before the PR merges to main

Three-Tier Approval System#

Tier 1: Maintainer PRs#

Maintainer PRs are queued when:

• Author is a maintainer (author=@maintainers)
• PR has the "lgtm" label
• No "do-not-merge" label

Tier 2: Trusted Bot PRs#

Automated PRs from release-plz and Dependabot are auto-queued without human approval.

Release-plz PRs are auto-queued when:

• Branch name matches head ~= ^release-plz-
• Base branch is main
• No "do-not-merge" label

Dependabot PRs are auto-approved and auto-queued when:

• Author is dependabot[bot]
• Base branch is main
• No "do-not-merge" label
• The PR does not modify .github/workflows/release.yml (-files~=\.github/workflows/release\.yml)

The safety measure blocking modifications to release.yml protects the auto-generated cargo-dist workflow from unintended changes that would break the release pipeline.

Dependabot PRs receive automatic approval with the message "Automatically approved by Mergify".

Dosu PRs follow similar rules and receive automatic approval.

Tier 3: External Contributor PRs#

External PRs require maintainer approval and are queued when:

• Author is NOT a maintainer (-author=@maintainers)
• Author is NOT dependabot[bot]
• Branch name does NOT match ^release-plz- (-head ~= ^release-plz-)
• Has approval from at least one maintainer (approved-reviews-by=@maintainers)
• No "do-not-merge" label

Additional Protections#

The merge_protections section enforces requirements on all merge attempts, preventing manual merges that bypass the merge queue. The protections are ordered as follows:

1. CI must pass - Requires all nine CI checks (quality, test, test-cross-platform matrix including ubuntu-22.04, coverage) to pass
2. Do not merge outdated PRs - Prevents merging PRs that are more than 10 commits behind the base branch
3. Enforce conventional commit - Validates PR titles follow the Conventional Commits specification with the pattern title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?:

Cargo-Deny Configuration#

Overview#

The deny.toml file configures cargo-deny to enforce dependency security, license compliance, and supply chain policies. The CI uses this default deny.toml without specifying custom config paths in the cargo deny check command.

Graph Configuration#

Targets multiple platforms:

• aarch64-apple-darwin
• aarch64-unknown-linux-gnu
• x86_64-unknown-linux-gnu
• x86_64-unknown-linux-musl
• x86_64-pc-windows-msvc

All checks run with all-features enabled and dev dependencies excluded.

Licenses#

Allows common open source licenses:

• Apache-2.0, Apache-2.0 WITH LLVM-exception
• MIT, BSD-3-Clause, ISC
• CC0-1.0, Unicode-3.0, Unlicense, Zlib

Uses a confidence threshold of 0.8 for license detection and includes dev dependencies in license checks.

Bans#

Denies multiple versions of the same crate and wildcards, enforcing dependency deduplication. Bans specific crates favoring pure-Rust alternatives:

• git2 (suggests gix instead)
• openssl and openssl-sys (suggests rustls instead)
• libssh2-sys
• cmake (suggests cc instead)

Advisories#

Denies yanked crates and uses workspace-level settings for unmaintained crates. No specific advisories are ignored.

Sources#

Denies unknown registries and git sources, allowing only the official crates.io registry. No GitHub/GitLab/Bitbucket organizations are whitelisted for git sources.

Cargo-Dist Release Automation#

Overview#

The project uses cargo-dist for automated release management, with configuration stored in a dedicated dist-workspace.toml file rather than in Cargo.toml.

Configuration#

cargo-dist v0.31.0 is configured with:

• CI Backend: GitHub
• Installers: shell and homebrew
• Target Platforms: 7 targets including aarch64 and x86_64 for Apple, Linux, and Windows
• Features: GitHub attestations, cargo-auditable, cargo-cyclonedx (SBOM generation)
• Homebrew tap: EvilBit-Labs/homebrew-tap

The Release Workflow#

The .github/workflows/release.yml is a 373-line auto-generated GitHub Actions workflow. The first line clearly states:

This file was autogenerated by dist: https://axodotdev.github.io/cargo-dist#

Why release.yml Should NEVER Be Manually Modified#

Key reasons NOT to manually edit this file:

1. Automatic Regeneration: cargo-dist regenerates this file when you run dist init or dist generate-ci. Any manual changes will be overwritten.

2. Configuration-Driven: The workflow is generated from settings in dist-workspace.toml. Changes should be made there, not in the generated workflow.

3. Complex Logic: The workflow contains intricate logic for cross-platform builds, artifact handling, and conditional execution that cargo-dist manages automatically.

4. Version-Specific: The workflow is tied to cargo-dist v0.31.0. Manual modifications could break compatibility.

5. Local Enforcement: The project includes a hookify rule (hookify.block-release-workflow-edit.local.md) that blocks attempts to modify release.yml locally, catching this mistake before it reaches CI.

Release Process#

The workflow is triggered when a git tag matching a version pattern is pushed:

1. Plan Phase: Runs dist plan or dist host to determine build requirements
2. Build Local Artifacts: Builds platform-specific binaries across a matrix of runners
3. Build Global Artifacts: Generates checksums, installers, and SBOM files
4. Host: Uploads artifacts and creates the GitHub Release
5. Publish Homebrew: Updates the homebrew-tap repository

Release-Plz Automation#

Overview#

The project uses release-plz for managing Rust package releases to crates.io. Release-plz and cargo-dist work together: release-plz handles versioning and crates.io publishing, while cargo-dist handles binary distribution.

Configuration#

release-plz.toml configures:

• Git tag creation: Enabled
• Git releases: Disabled - cargo-dist handles GitHub releases
• crates.io publishing: Enabled
• Semver checking: Enabled
• Changelog configuration: Uses cliff.toml

Workflow Triggers#

The release-plz workflow triggers on every push to main and contains two jobs:

1. release-plz-release: Executes the release command to publish packages to crates.io and create git tags
2. release-plz-pr: Executes the release-pr command to create/update release PRs with concurrency control

Integration with Mergify#

Mergify auto-queues release-plz PRs when the branch name matches ^release-plz- pattern, enabling fully automated releases once CI passes.

Dependabot Configuration#

Overview#

Dependabot monitors three ecosystems with a weekly update schedule:

1. Cargo (Rust dependencies): Monitors the root directory
2. GitHub Actions: Monitors workflow dependencies
3. Devcontainers: Monitors development container configurations

All ecosystems are configured with:

• Update interval: Weekly
• Rebase strategy: Disabled
• Grouping: No explicit grouping configured

Integration with Mergify#

Mergify auto-approves and auto-queues Dependabot PRs with one critical safety measure: PRs modifying .github/workflows/release.yml are blocked from auto-merge (-files~=\.github/workflows/release\.yml). This protects the auto-generated cargo-dist workflow from unintended modifications.

DCO and Commit Signing Requirements#

DCO (Developer Certificate of Origin)#

The project requires DCO sign-off on all commits, enforced through the DCO GitHub App.

Contributors must use git commit -s:

git commit -s -m "feat: add new feature"

This adds a Signed-off-by line certifying agreement with the Developer Certificate of Origin.

DCO Configuration#

The .github/dco.yml configuration allows remediation commits:

allowRemediationCommits:
  individual: true
  thirdParty: true

This allows contributors to fix missing DCO sign-offs after the fact.

GPG Commit Signing#

While the background context mentions GPG commit signing as mandatory, no configuration or enforcement for GPG commit signing was found in the repository configuration files. The repository currently only enforces DCO sign-off (legal certification), not GPG cryptographic signatures.

Local Enforcement Hooks#

The project includes several hookify rules to prevent common CI/CD and contribution mistakes locally:

• hookify.block-release-workflow-edit.local.md - Blocks manual edits to .github/workflows/release.yml, preventing accidental modifications to the auto-generated cargo-dist workflow
• hookify.block-unsigned-commits.local.md - Blocks commits without DCO sign-off (git commit without -s), catching missing sign-offs before they reach CI
• hookify.block-unsigned-tags.local.md - Blocks unsigned tags, requiring git tag -s for GPG-signed tags
• hookify.warn-emoji-in-prs.local.md - Warns when creating PRs that may contain emoji characters, which violate the project's style guidelines

These hooks complement the CI/CD enforcement by catching issues in the local development environment before code is pushed.

PR Checklist#

The PR checklist in CONTRIBUTING.md includes verification of DCO sign-off:

• [ ] Commits signed off (git commit -s)

Relevant Code Files#

Related Topics#

• GitHub Actions: The CI/CD infrastructure is built entirely on GitHub Actions workflows
• Mergify: Third-party merge queue service providing automated PR management
• cargo-dist: Tool for automating Rust binary distribution across platforms
• release-plz: Tool for automating Rust package releases to crates.io
• cargo-deny: Dependency security and license compliance tool
• cargo-audit: Security vulnerability scanner for Rust dependencies
• DCO (Developer Certificate of Origin): Legal certification for open source contributions
• mise: Development tool version management (formerly rtx)
• just: Command runner for project task automation
• cargo-nextest: Next-generation test runner for Rust
• OSSF Scorecard: Open Source Security Foundation supply-chain security assessment
• Dependabot: GitHub's automated dependency update service
• SBOM (Software Bill of Materials): Inventory of software components for security tracking