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

> Explore the CI/CD pipelines for macro-inc/macro. Discover how GitHub Actions, `just`, Nix, and Docker Compose streamline integration and deployment for efficient development.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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:

```bash

# 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:

```yaml
- 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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/Cargo.toml)** (workspace root) – Defines the multi-crate workspace structure that `cargo build` targets during the build stage.
- **[`README.md`](https://github.com/macro-inc/macro/blob/main/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.