CI/CD Pipelines and Setup for macro-inc/macro: A Complete Guide

The macro-inc/macro repository orchestrates its continuous integration and deployment through a three-stage pipeline managed by GitHub Actions, utilizing the just task runner, Nix environments, and Docker Compose for comprehensive testing.

The macro-inc/macro project maintains code quality across its multi-crate Rust workspace using automated CI/CD pipelines that execute on every push to the main branch. This setup ensures that all code passes compilation, integration tests, and linting checks before deployment. The pipeline relies heavily on the just command runner to provide consistent interfaces between local development and cloud-based GitHub Actions runners.

The Three-Stage CI/CD Pipeline Architecture

The CI/CD workflow centers on three distinct stages that validate every change to the codebase.

Build Stage

During the build stage, the CI system compiles the entire Rust workspace in release mode using cargo build and constructs all required Docker images. This step guarantees that the code compiles cleanly in a fresh environment without local artifacts. In the justfile, this corresponds to the just build command, which handles both the Rust compilation and Docker image creation.

Test Stage

The test stage executes unit tests, integration tests, and database-dependent validations. The pipeline spins up a local PostgreSQL instance along with Redis and OpenSearch using docker-compose -f docker/docker-compose-databases.yml up -d before running cargo test across the workspace crates. This ensures tests run against real database services rather than mocks, catching integration issues early.

Lint and Quality Stage

The final stage enforces code quality through formatting and static analysis. The just clippy command runs cargo clippy for linting alongside cargo fmt for formatting checks. Additionally, just prepare_db refreshes the SQLx query cache, generating .sqlx/query-*.json files that enable offline compilation and type checking.

Local Development with the Just Task Runner

The justfile at the repository root defines the task runner commands that power both local development and CI execution. These commands provide a consistent interface for all build operations.

The most common CI commands include:

# Lint and format code

just clippy

# Run all tests including database integration

just test

# Build all services in release mode

just build

# Refresh SQLx offline query cache

just prepare_db

Running just test locally executes the same Docker Compose setup used in CI, ensuring that integration tests against PostgreSQL, Redis, and OpenSearch behave identically across environments.

GitHub Actions Workflow Implementation

The CI/CD pipelines for macro-inc/macro are defined in YAML files within the .github/workflows/ directory. These workflows orchestrate the just commands within a reproducible Nix environment.

Environment Setup with Nix

The workflows install a pinned Nix development environment using cachix/install-nix-action, ensuring that all dependencies remain consistent across runs. This approach eliminates "works on my machine" issues by providing identical toolchains for every build.

Standard Workflow Steps

A typical GitHub Actions job follows this sequence:

- name: Checkout repository
  uses: actions/checkout@v4

- name: Install Nix
  uses: cachix/install-nix-action@v22

- name: Run CI steps
  run: |
    just check
    just clippy
    just test
    just build

The workflow first executes just check for initial validation, followed by linting, comprehensive testing against live services, and finally release builds.

Docker Compose Integration

The test stage specifically relies on docker/docker-compose-databases.yml to provision PostgreSQL, Redis, and OpenSearch containers. The GitHub Actions runner executes these services as background processes, allowing the Rust test suite to connect to real database instances during cargo test execution.

Artifact Publishing

When the pipeline runs for a release, built Docker images are pushed to the container registry after successful completion of all three stages. This ensures only validated artifacts reach production deployments.

Key Configuration Files

Understanding the CI/CD setup requires familiarity with these specific files:

• justfile – Defines the task runner commands (just build, just test, just clippy) that abstract CI logic into reproducible scripts.
• docker/docker-compose-databases.yml – Orchestrates PostgreSQL, Redis, and OpenSearch containers required for integration testing.
• .github/workflows/*.yml – Contains the GitHub Actions workflow definitions that execute the pipeline on every push to main.
• Cargo.toml (workspace root) – Defines the multi-crate workspace structure that cargo build targets during the build stage.
• README.md – Documents the "Development Commands" section listing available just tasks for CI reproduction.

Summary

The macro-inc/macro CI/CD pipelines provide a robust automation framework for its Rust workspace:

• Three-stage validation ensures code compiles, passes integration tests, and meets quality standards before deployment.
• just task runner unifies local development and CI execution through commands defined in the repository justfile.
• Docker Compose integration enables realistic testing against PostgreSQL, Redis, and OpenSearch during the test stage.
• Nix-based GitHub Actions guarantee reproducible build environments across all pipeline runs.

Frequently Asked Questions

What role does the just task runner play in the CI/CD pipelines?

The just task runner serves as the primary interface for the CI/CD pipelines, encapsulating complex commands like cargo build, Docker image creation, and test execution into simple, reproducible tasks. Both local developers and GitHub Actions workflows invoke identical just commands from the justfile, ensuring consistency between development and production environments.

How does the test stage handle database dependencies?

The test stage spins up real database services using docker-compose -f docker/docker-compose-databases.yml up -d, which launches PostgreSQL, Redis, and OpenSearch containers. This allows cargo test to execute integration tests against actual database instances rather than mocks, validating SQL queries and connection logic that would otherwise pass in unit tests but fail in production.

Where are the GitHub Actions workflows defined?

The workflow files reside in the .github/workflows/ directory at the repository root. These YAML files define the pipeline stages that execute on every push to main, including the Nix environment setup, just command execution, and Docker image publishing for releases.

How is the SQLx offline cache maintained in the CI pipeline?

The just prepare_db command generates .sqlx/query-*.json files that cache validated SQL queries for offline compilation. The CI pipeline runs this command to ensure the query cache stays synchronized with the database schema, enabling the Rust compiler to verify SQL correctness during builds without requiring a live database connection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}