Skip to content

build.yml

Artifact building workflow that creates distributable packages and container images.

Overview

File: .github/workflows/build.yml Class: BuildWorkflow in pyrig.dev.configs.workflows.build
Inherits: Workflow

The build workflow runs after successful health checks on the main branch. It builds platform-specific artifacts (executables, wheels) across OS matrix and creates a container image. These artifacts are uploaded for the release workflow to create releases.

Triggers

Workflow Run

  • Workflow: Health Check
  • Event: completed
  • Branches: main
  • Condition: Only runs if health check succeeded and was not cron-triggered

Why workflow_run? Ensures artifacts are only built after all tests pass on main branch.

Why exclude cron? Scheduled health checks validate dependencies daily but shouldn't trigger releases. Only actual code changes (push) should create new releases.

Workflow Dispatch

  • Purpose: Manual trigger for testing

Job Flow

graph TD A[Trigger: Health Check Success on main] --> B[build_artifacts] A --> C[build_container_image] B --> B1[Ubuntu] B --> B2[Windows] B --> B3[macOS] B1 -.->|Upload| D[pyrig-Linux] B2 -.->|Upload| E[pyrig-Windows] B3 -.->|Upload| F[pyrig-macOS] C -.->|Upload| G[container-image] style A fill:#a8dadc,stroke:#333,stroke-width:2px,color:#000 style B fill:#f4a261,stroke:#333,stroke-width:2px,color:#000 style C fill:#e76f51,stroke:#333,stroke-width:2px,color:#000 style B1 fill:#f4a261,stroke:#333,stroke-width:1px,color:#000 style B2 fill:#f4a261,stroke:#333,stroke-width:1px,color:#000 style B3 fill:#f4a261,stroke:#333,stroke-width:1px,color:#000 style D fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style E fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style F fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style G fill:#9d84b7,stroke:#333,stroke-width:1px,color:#000

Jobs

1. build_artifacts

Runs on: Matrix of OS (Ubuntu, Windows, macOS) Strategy: fail-fast: true Condition: Health check succeeded and not cron-triggered

Step Flow:

graph TD S1[1. Checkout Repository] --> S2[2. Setup Version Control] S2 --> S3[3. Setup Package Manager] S3 --> S4[4. Patch Version] S4 --> S5[5. Add Version Bump To Version Control] S5 --> S6[6. Update Dependencies] S6 --> S7[7. Install Dependencies] S7 --> S8[8. Add Dependency Updates To Version Control] S8 --> S9[9. Build Artifacts] S9 --> S10[10. Upload Artifacts] style S1 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S2 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S3 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S4 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S5 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S6 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S7 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S8 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S9 fill:#f4a261,stroke:#333,stroke-width:1px,color:#000 style S10 fill:#9d84b7,stroke:#333,stroke-width:1px,color:#000

Steps:

  1. Checkout Repository (actions/checkout@main)

  2. Clones the repository code

  3. Setup Version Control

  4. Configures git user as github-actions[bot]

  5. Setup Package Manager (astral-sh/setup-uv@main)

  6. Installs uv package manager

  7. Uses the default Python version (latest supported)

  8. Patch Version

  9. Bumps patch version: uv version --bump patch

  10. Updates pyproject.toml with new version

  11. Add Version Bump To Version Control

  12. Stages pyproject.toml and uv.lock

  13. Update Dependencies

  14. Updates lock file: uv lock --upgrade

  15. Install Dependencies

  16. Installs dependencies: uv sync

  17. Add Dependency Updates To Version Control

  18. Stages pyproject.toml and uv.lock

  19. Build Artifacts

  20. Runs uv run pyrig build
  21. Executes configured builder classes (e.g., myapp/dev/builders/ in a consumer repo)
  22. Creates platform-specific executables, wheels, etc.

  23. Outputs to dist/ directory

  24. Upload Artifacts (actions/upload-artifact@main)

    • Uploads dist/ directory
    • Artifact name: pyrig-{OS} (e.g., pyrig-Linux, pyrig-Windows, pyrig-macOS)
    • Available for download in release workflow

Why matrix? Different OS produce different artifacts (Linux ELF, Windows EXE, macOS Mach-O).

2. build_container_image

Runs on: Ubuntu latest Condition: github.event.workflow_run.conclusion == 'success'

Step Flow:

graph TD S1[1. Checkout Repository] --> S2[2. Setup Version Control] S2 --> S3[3. Setup Package Manager] S3 --> S4[4. Patch Version] S4 --> S5[5. Add Version Bump To Version Control] S5 --> S6[6. Install Container Engine] S6 --> S7[7. Build Container Image] S7 --> S8[8. Make Dist Folder] S8 --> S9[9. Save Container Image] S9 --> S10[10. Upload Artifacts] style S1 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S2 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S3 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S4 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S5 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S6 fill:#90be6d,stroke:#333,stroke-width:1px,color:#000 style S7 fill:#e76f51,stroke:#333,stroke-width:1px,color:#000 style S8 fill:#f4a261,stroke:#333,stroke-width:1px,color:#000 style S9 fill:#f4a261,stroke:#333,stroke-width:1px,color:#000 style S10 fill:#9d84b7,stroke:#333,stroke-width:1px,color:#000

Steps:

  1. Checkout Repository (actions/checkout@main)

  2. Clones the repository code

  3. Setup Version Control

  4. Configures git user as github-actions[bot]

  5. Setup Package Manager (astral-sh/setup-uv@main)

  6. Installs uv package manager

  7. Uses the default Python version (latest supported)

  8. Patch Version

  9. Bumps patch version: uv version --bump patch

  10. Updates pyproject.toml with new version

  11. Add Version Bump To Version Control

  12. Stages pyproject.toml and uv.lock

  13. Install Container Engine (redhat-actions/podman-install@main)

  14. Installs Podman container engine

  15. Uses GITHUB_TOKEN for authentication

  16. Build Container Image

  17. Runs podman build -t pyrig .
  18. Uses Containerfile in repository root

  19. Tags image as pyrig

  20. Make Dist Folder

  21. Creates dist/ directory: mkdir -p dist

  22. Save Container Image

  23. Exports image to tarball: podman save -o dist/pyrig.tar pyrig

  24. Creates portable image archive

  25. Upload Artifacts (actions/upload-artifact@main)

    • Uploads dist/pyrig.tar
    • Artifact name: container-image
    • Available for distribution or deployment

Why Podman? Daemonless, rootless container engine preferred over Docker for security and simplicity.

Environment Variables

  • PYTHONDONTWRITEBYTECODE: 1 (prevents .pyc files)
  • UV_NO_SYNC: 1 (prevents automatic sync on uv commands)

Artifacts Produced

Platform Artifacts

  • pyrig-Linux: Linux executables and wheels
  • pyrig-Windows: Windows executables and wheels
  • pyrig-macOS: macOS executables and wheels

Container Image

  • container-image: Podman/Docker image tarball (pyrig.tar)

Usage

Automatic Trigger

Runs automatically when health check succeeds on main branch.

Manual Trigger

GitHub Actions tab → Build → Run workflow

Downloading Artifacts

  1. Go to workflow run in GitHub Actions
  2. Scroll to "Artifacts" section
  3. Download platform-specific or container artifacts

Best Practices

  1. Define builders: Create builder classes in myapp/dev/builders/ for custom artifacts
  2. Test locally: Run uv run pyrig build before pushing
  3. Check all platforms: Verify artifacts build successfully on all OS
  4. Keep Containerfile updated: Ensure container image builds correctly