CI Pipeline Architecture#

The CI Pipeline Architecture for the token-privilege repository represents a Windows-primary continuous integration and continuous deployment system designed for a Rust library that provides Windows token privilege management functionality. This architecture prioritizes Windows-based testing due to the library's fundamental dependency on Win32 FFI and Windows-specific APIs, while maintaining cross-platform compilation validation through stub implementations on Linux and macOS.

The pipeline design emphasizes a security-first approach with multiple quality gates, comprehensive test coverage on Windows, platform-specific validation strategies, and automated compliance through SLSA provenance, SBOM generation, and vulnerability scanning. The architecture follows a staged execution model with explicit job dependencies: quality gates (formatting and linting) → platform-specific testing (Windows functional tests and Linux stub validation) → coverage reporting → compatibility matrix testing across multiple Rust versions.

Current Implementation Status: As of 2026-03-09, the CI/CD infrastructure has been implemented via PR #1. The complete development toolchain and CI tooling ecosystem configured through mise is now orchestrated through operational GitHub Actions workflows, Mergify configuration, and automation scripts that implement the architecture described in this document.

Architectural Overview#

The CI pipeline architecture follows a multi-stage dependency graph designed to fail fast on quality issues while ensuring comprehensive validation on Windows where the library's actual functionality can be tested. The architecture is implemented through GitHub Actions workflows, Mergify configuration, and the configured tooling ecosystem.

Pipeline Stages#

The workflow structure consists of the following stages:

Primary CI Workflow (.github/workflows/ci.yml):

1. Code Quality: Code formatting (rustfmt), linting (clippy), and workflow validation on windows-latest
2. Test (Windows): Functional testing with cargo-nextest, release builds, and Win32 FFI validation
3. Test (Linux stubs): Compilation validation and stub behavior verification on ubuntu-latest
4. Code Coverage: LLVM-based code coverage collection with cargo-llvm-cov and Codecov upload

Compatibility Workflow (.github/workflows/compat.yml):

• Matrix testing across Rust versions (stable, stable-2, MSRV 1.85)
• Executed on windows-latest to validate actual library functionality

Security Workflows:

• Audit Dependencies (.github/workflows/audit.yml): Daily vulnerability scanning with cargo-audit
• Security (.github/workflows/security.yml): Policy enforcement with cargo-deny and dependency updates tracking
• Scorecard (.github/workflows/scorecard.yml): OpenSSF Scorecard analysis

Documentation and Release Workflows:

• Docs (.github/workflows/docs.yml): mdBook documentation building and deployment
• Release-plz (.github/workflows/release-plz.yml): Automated release management and changelog generation

Windows-Primary Strategy#

Rationale#

The token-privilege library is fundamentally a Windows-specific library for token privilege management, requiring direct access to Win32 APIs through FFI. This architectural constraint dictates the Windows-primary testing strategy:

• Win32 FFI Dependency: The library's core functionality requires Windows-specific APIs that cannot be meaningfully tested outside a Windows environment
• Real Behavior Validation: Only Windows runners can validate actual token privilege manipulation, security context changes, and elevation detection
• UnsupportedPlatform Stubs: Non-Windows platforms receive stub implementations that compile successfully but return UnsupportedPlatform errors for functional calls
• Quality Gates on Windows: Even non-functional checks (formatting, linting) run on windows-latest to ensure consistent tooling behavior across the development lifecycle

Platform-Specific Testing#

The architecture implements a dual-track testing strategy documented in the commit instructions:

Windows Testing (windows-latest):

• Execute complete test suite with cargo-nextest
• Validate Win32 FFI bindings and behavior
• Test privilege escalation, token manipulation, and security context operations
• Build release artifacts to ensure optimization doesn't break functionality
• Collect code coverage with LLVM instrumentation

Linux Stub Testing (ubuntu-latest):

• Verify compilation succeeds for cross-platform crate compatibility
• Validate stub implementations return appropriate UnsupportedPlatform errors
• Ensure public API surface remains consistent across platforms
• Test error handling paths for platform-gated features

This approach ensures the library can be included as a dependency in cross-platform Rust projects without compilation failures, while clearly documenting platform-specific functionality limitations.

Quality Gates#

The pipeline implements multiple quality gate checkpoints that must pass before proceeding to expensive testing stages. All quality gates execute on windows-latest to match the primary development and testing platform.

Code Quality Checks#

Formatting (rustfmt):

• Enforces consistent code style across the codebase
• Configured through rustfmt.toml
• Fails CI on any formatting violations to prevent style divergence

Linting (clippy):

• Static analysis for common mistakes and anti-patterns
• Configured through clippy.toml or inline attributes
• Catches potential bugs, performance issues, and idiomatic violations

Workflow Validation (actionlint):

• Validates GitHub Actions workflow syntax
• Detects common workflow configuration errors
• Ensures workflow file best practices

Documentation Quality#

Link Validation (lychee):

• Checks all documentation links for broken URLs
• Validates internal cross-references
• Ensures external dependencies remain accessible

Markdown Linting (markdownlint-cli2):

• Enforces consistent markdown formatting
• Validates documentation structure
• Ensures accessibility best practices

Local Development Integration#

The commit instructions reference a just ci-check command for local CI verification. This command is implemented in the justfile and allows developers to run the same quality gates locally before pushing, reducing CI failure iterations.

Test Execution#

Test Runner: cargo-nextest#

The pipeline uses cargo-nextest (version 0.9.129) as the primary test runner instead of standard cargo test. Nextest provides several advantages for CI environments:

• Parallelization: More efficient parallel test execution with better load balancing
• Execution Model: Tests run in separate processes, improving isolation
• Output: Cleaner, more parseable output for CI log analysis
• Retry Logic: Built-in test flakiness detection and retry capabilities
• Filtering: Advanced test selection and filtering options

The commit instructions reference nextest in the context of a "cross-platform matrix", though the actual implementation will primarily run on windows-latest with supplementary stub validation on Linux.

Windows Test Job#

The Windows test job represents the primary functional testing stage:

• Platform: windows-latest
• Test Execution: Run complete test suite with nextest
• Build Variants: Test both debug and release builds
• FFI Validation: Verify Win32 API bindings and behavior
• Privilege Tests: Validate token manipulation, elevation detection, and security context changes
• Dependencies: Runs after quality gate passes

Linux Stub Validation Job#

The Linux job provides minimal validation for cross-platform compatibility:

• Platform: ubuntu-latest
• Compilation Check: Ensure code compiles successfully
• Stub Behavior: Validate UnsupportedPlatform error returns
• API Consistency: Verify public API surface matches Windows implementation
• Dependencies: Runs after quality gate passes, parallel to Windows tests

Coverage Workflow#

LLVM-Based Coverage Collection#

The pipeline uses cargo-llvm-cov (version 0.8.4) for source-based code coverage, which provides more accurate coverage data than gcov-based solutions:

• Platform: windows-latest (coverage collected only where functional tests run)
• Instrumentation: LLVM source-based coverage via llvm-tools component
• Format: Generates coverage reports in multiple formats (lcov, json, html)
• Upload: Results uploaded to Codecov for tracking and PR comments
• Dependencies: Runs after Windows test job completes successfully

The coverage job depends on successful Windows tests because meaningful coverage can only be collected where the library's actual functionality executes. Coverage from Linux stub implementations would not provide useful metrics.

Coverage Thresholds#

While not yet configured, the intended architecture would likely enforce minimum coverage thresholds:

• Total coverage percentage requirements
• Differential coverage for new code in PRs
• Coverage requirement enforcement in merge queue

Compatibility Matrix Testing#

The compatibility workflow (.github/workflows/compat.yml) validates the library across multiple Rust toolchain versions to ensure backward compatibility and prepare for upcoming language changes.

Rust Version Matrix#

Based on the background context, the compatibility matrix would test three Rust versions:

• stable: Current stable Rust release
• stable-2: Two releases prior to current stable (provides advance warning for deprecations)
• MSRV 1.85: Minimum Supported Rust Version defines the oldest Rust compiler guaranteed to work

Platform Strategy#

All compatibility testing runs on windows-latest because:

• Functional behavior can only be validated on Windows
• Linux stub implementations don't exercise meaningful code paths
• MSRV compliance for actual functionality is more important than stub compilation compatibility

Matrix Configuration Example#

The workflow uses a GitHub Actions matrix strategy:

strategy:
  matrix:
    rust: [stable, '1.87.0', '1.85.0'] # stable, stable-2, MSRV
runs-on: windows-latest

This ensures the library remains compatible with recent stable releases while honoring the declared MSRV for downstream dependents.

Security and Compliance#

The architecture implements a comprehensive security-first approach with multiple scanning and attestation layers.

Vulnerability Scanning#

Dependency Auditing (cargo-audit):

• Scans dependencies against the RustSec Advisory Database
• Identifies known security vulnerabilities in the dependency tree
• Fails CI when vulnerabilities exceed configured severity threshold

Policy Enforcement (cargo-deny):

• Enforces licensing policies (allowed/banned licenses)
• Detects duplicate dependencies that inflate binary size
• Validates security advisories and bans specific crate versions
• Checks for unmaintained dependencies

Security Posture Assessment (OpenSSF Scorecard):

• Evaluates repository security practices
• Checks for branch protection, signed commits, vulnerability disclosure policy
• Assesses CI/CD security, dependency management, and code review practices
• SLSA provenance verification enabled in configuration

Supply Chain Security#

SBOM Generation (cargo-cyclonedx):

• Generates CycloneDX-format Software Bill of Materials
• Documents complete dependency tree with versions and licenses
• Enables supply chain auditing and compliance verification
• Integrates with vulnerability tracking systems

Dependency Metadata Embedding (cargo-auditable):

• Embeds dependency information directly in compiled binaries
• Allows post-deployment vulnerability scanning
• Enables forensic analysis of deployed artifacts

Attestations and Provenance:

• GitHub attestations enabled (github_attestations = true)
• SLSA provenance enabled (slsa = true)
• Cryptographically verifiable build provenance
• Tamper-evident artifact distribution

Merge Queue Configuration#

The Mergify configuration (.mergify.yml) implements automated merge queue management with strict CI requirements.

Queue Rules Architecture#

Based on the background context, the configuration uses queue_rules (not the deprecated merge_queue syntax) for defining named merge queues. This provides more flexible queue management and better integration with branch protection rules.

Merge Protections#

The configuration implements merge_protections with two key components:

Conditional Logic (if conditions):

• Defines when PRs are eligible for the merge queue
• Typical conditions: approved reviews, no requested changes, passing CI
• Prevents queue pollution from PRs not ready to merge

Success Conditions (success_conditions):

• Replaces the older conditions syntax
• Specifies which CI checks must pass before merging
• Uses check-success values that must exactly match CI job name: fields from workflow files

CI Job Name Mapping#

Critical requirement: The check-success values in Mergify configuration must exactly match the job names defined in GitHub Actions workflows:

# .github/workflows/ci.yml
jobs:
  quality:
    name: "Code Quality"

  test-windows:
    name: "Test (Windows)"

  test-linux-stubs:
    name: "Test (Linux stubs)"

  coverage:
    name: "Code Coverage"

# .mergify.yml
queue_rules:
  - name: default
    queue_conditions:
      - check-success = Code Quality
      - check-success = Test (Windows)
    merge_conditions:
      - check-success = Code Quality
      - check-success = Test (Windows)

Mismatches between these values will cause merge queue failures because Mergify cannot find the required status checks.

Tooling Ecosystem#

The project uses mise (formerly rtx) for unified development tool management, providing reproducible tool versions across development and CI environments through a lockfile with SHA256 checksums.

Configuration Approach#

The mise.toml configuration provides several key features:

• Lockfile enabled (lockfile = true): Ensures reproducible builds with pinned tool versions
• Version pinning (pin = true): Prevents automatic tool updates that could break CI
• Offline support (prefer_offline = true): Reduces network dependencies during builds
• Auto-installation (exec_auto_install = true): Automatically installs missing tools

Cross-Platform Rust Targets#

The Rust toolchain configuration includes seven target architectures for cross-platform binary distribution:

• x86_64-pc-windows-msvc - Windows x64 (primary platform)
• aarch64-pc-windows-msvc - Windows ARM64
• x86_64-unknown-linux-gnu - Linux x64 (glibc)
• x86_64-unknown-linux-musl - Linux x64 (static linking)
• aarch64-unknown-linux-gnu - Linux ARM64
• x86_64-apple-darwin - macOS x64
• aarch64-apple-darwin - macOS ARM64 (Apple Silicon)

While the library only provides functional implementations on Windows, these targets ensure stub implementations can be compiled and distributed for all major platforms.

Development and CI Tool Inventory#

The complete tool inventory configured for CI and development includes:

Core Testing and Coverage (23 tools total):

• cargo-nextest 0.9.129, cargo-llvm-cov 0.8.4, cargo-insta 1.46.3

Security Scanning:

• cargo-audit 0.22.1, cargo-deny 0.19.0, scorecard 5.4.0, cargo-auditable 0.7.4, cargo-cyclonedx 0.5.7

Documentation:

• lychee 0.23.0, markdownlint-cli2 0.21.0, mdformat 1.0.0, prettier 3.8.1
• mdbook toolchain (8 plugins: base, linkcheck, tabs, mermaid, toc, admonish, open-on-gh, i18n-helpers)

Release Automation:

• cargo-dist 0.31.0, cargo-release 1.1.1, release-plz 0.3.157, git-cliff 2.12.0

Workflow Validation:

• actionlint 1.7.11, shellcheck 0.11.0

Dependency Management:

• cargo-machete 0.9.1, cargo-outdated 0.17.0, cargo-about 0.8.4

Development Lifecycle:

• pre-commit (latest)

This comprehensive tooling ecosystem is fully configured and orchestrated through the implemented CI workflows.

Implementation Details#

The CI/CD architecture has been implemented with the following components:

1. Core CI Workflow#

.github/workflows/ci.yml implements the primary CI pipeline with the following structure:

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  quality:
    name: "Quality Gate"
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo fmt --check
      - run: cargo clippy -- -D warnings
      - run: actionlint .github/workflows/*.yml
      - run: lychee docs/
      - run: markdownlint-cli2 "**/*.md"

  test-windows:
    name: "Test: Windows"
    needs: quality
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo nextest run --all-features
      - run: cargo build --release

  test-linux-stubs:
    name: "Test: Linux Stubs"
    needs: quality
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo build
      - run: cargo nextest run

  coverage:
    name: "Coverage"
    needs: test-windows
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - run: cargo llvm-cov nextest --lcov --output-path lcov.info
      - uses: codecov/codecov-action@v4
        with:
          file: lcov.info

2. Compatibility Matrix Workflow#

.github/workflows/compat.yml implements Rust version compatibility testing:

name: Compatibility

on:
  push:
    branches: [main]
  pull_request:
  schedule:
    - cron: '0 0 * * 0' # Weekly

jobs:
  compat:
    name: "Rust ${{ matrix.rust }}"
    runs-on: windows-latest
    strategy:
      matrix:
        rust: [stable, '1.87.0', '1.85.0'] # stable, stable-2, MSRV
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ matrix.rust }}
      - run: cargo nextest run

3. Mergify Configuration#

.mergify.yml implements automated merge queue management:

queue_rules:
  - name: default
    merge_protections:
      - if:
          - "#approved-reviews-by >= 1"
          - "#changes-requested-reviews-by = 0"
        success_conditions:
          - check-success = "Quality Gate"
          - check-success = "Test: Windows"
          - check-success = "Test: Linux Stubs"
          - check-success = "Coverage"

pull_request_rules:
  - name: Automatic merge
    conditions:
      - base = main
      - "#approved-reviews-by >= 1"
    actions:
      queue:
        name: default

4. Local CI Verification#

justfile provides local CI verification commands:

# Run all CI checks locally
ci-check: fmt lint test

# Format check
fmt:
    cargo fmt --check

# Linting
lint:
    cargo clippy -- -D warnings

# Run tests
test:
    cargo nextest run --all-features

# Coverage report
coverage:
    cargo llvm-cov nextest --html
    cargo llvm-cov report

5. Additional Configuration Files#

The following configuration files support the CI/CD infrastructure:

• deny.toml: cargo-deny policy configuration for license and security enforcement
• rustfmt.toml: Rust code formatting configuration
• codecov.yml: Codecov configuration for coverage reporting
• .pre-commit-config.yaml: Pre-commit hooks configuration for local development checks
• Branch protection rules (via GitHub UI): Require CI success, require review, enforce merge queue

Relevant Code Files#

Related Topics#

Windows Token Privilege Management#

The token-privilege library provides a Rust interface for Windows security token and privilege manipulation. This Windows-specific functionality drives the Windows-primary CI architecture, as the library's core features (token elevation detection, privilege modification, security context management) require access to Win32 APIs that cannot be meaningfully emulated on other platforms.

Cross-Platform Rust Development#

The architecture demonstrates a pattern for developing platform-specific Rust libraries while maintaining cross-platform compilation compatibility:

• Primary Platform Testing: Comprehensive functional testing on the target platform (Windows)
• Stub Implementations: Minimal implementations on unsupported platforms that compile successfully but return platform-unsupported errors
• API Consistency: Maintaining identical public API surfaces across platforms for seamless dependency integration
• Build Targets: Supporting multiple architectures (x64, ARM64) and operating systems through Rust's target system

GitHub Actions Workflow Patterns#

The implemented architecture employs several common CI/CD patterns:

• Staged Pipelines: Quality gates → testing → coverage → deployment
• Job Dependencies: Using needs: to create execution order and fail-fast behavior
• Matrix Strategies: Testing across multiple Rust versions for compatibility validation
• Platform-Specific Runners: Selecting appropriate runner OS (windows-latest, ubuntu-latest) for different validation needs
• Artifact Upload: Coverage data, test results, and build outputs passed between jobs

Security Tooling and Supply Chain#

The architecture implements modern software supply chain security practices:

• SLSA Framework: Supply chain Levels for Software Artifacts provenance generation
• SBOM Generation: CycloneDX-format bills of materials for vulnerability tracking
• Provenance Attestation: Cryptographic verification of build artifacts
• Vulnerability Scanning: Continuous dependency monitoring with cargo-audit
• Policy Enforcement: Automated license and dependency constraints with cargo-deny
• Security Posture: OpenSSF Scorecard for best practices assessment

Mergify and Merge Queues#

Mergify provides automated pull request management and merge queue functionality as an alternative to GitHub's native merge queue feature. The configuration demonstrates:

• Queue Rules: Named merge queues with customizable merge conditions
• Merge Protections: Conditional logic for PR eligibility and required status checks
• CI Integration: Exact matching between workflow job names and Mergify check-success conditions
• Automatic Merging: Reducing manual merge burden while enforcing quality standards

cargo-nextest#

The nextest test runner represents a modern alternative to cargo test, offering improved parallelization, better output formatting, and enhanced CI integration. Key advantages include:

• Per-test process isolation
• Better load balancing across CPU cores
• Machine-readable JUnit XML output
• Built-in test retry for flakiness management
• Faster execution in CI environments

LLVM-Based Code Coverage#

The cargo-llvm-cov tool provides source-based code coverage using LLVM instrumentation, which offers more accurate coverage data than traditional gcov-based approaches. This is particularly important for:

• Accurate branch coverage measurement
• Better handling of generic code
• Reduced runtime overhead
• Integration with modern coverage reporting platforms (Codecov, Coveralls)

mise Tool Management#

mise (formerly rtx) represents a unified approach to development tool version management, serving as a polyglot alternative to language-specific version managers (rustup, nvm, pyenv). Benefits for CI/CD include:

• Single source of truth for tool versions
• Lockfile support with cryptographic verification
• Offline build capability
• Consistent tooling between local development and CI
• Support for arbitrary tools beyond language runtimes