forge-ci

Workflow Status

Python

Go

General

Reusable GitHub Actions Workflows for Python and Go Projects

A collection of production-ready, reusable GitHub Actions workflows. Get CI/CD running in under 5 minutes with plug-and-play workflows, or compose custom pipelines from individual focused jobs.

Quick Links

• Quick Start - Get running in 5 minutes
• Examples - Example projects for Poetry, uv, and venv
• Usage Patterns - Common workflow configurations
• Version Pinning - Semantic versioning and upgrade strategies

Workflow Documentation

Python:

• python-dependency-manager - Install and cache dependencies
• python-ruff - Ruff linting
• python-mypy - Type checking
• python-pytest - Test execution
• python-pytest-cov - Test coverage
• python-sbom - SBOM generation
• python-validate-pr - Complete validation pipeline
• python-release - Package releases (PyPI + GitHub)

Go:

• go-setup - Go installation with caching
• go-mod-download - Download dependencies
• go-fmt - Code formatting validation
• go-vet - Static analysis
• go-golangci-lint - Comprehensive linting (50+ linters)
• go-test-cov - Tests with coverage
• go-build - Simple binary building (CI/validation)
• go-release - Multi-platform releases (GoReleaser)
• go-validate-pr - Complete validation pipeline

Quick Start

Python Projects

Add this to your .github/workflows/ci.yml:

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-validate-pr.yml@v1

That's it! This single workflow will:

• Install dependencies (poetry/uv/venv auto-detected)
• Run Ruff linting
• Run mypy type checking
• Run pytest with coverage reporting

Go Projects

Add this to your .github/workflows/ci.yml:

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    uses: whisller/forge-ci/.github/workflows/forge-ci-go-validate-pr.yml@v1

That's it! This single workflow will:

• Setup Go with caching
• Download dependencies with verification
• Check code formatting (go fmt)
• Run static analysis (go vet)
• Run tests with 80% coverage threshold
• Build binary with version injection

See examples in examples/python-poetry/ and examples/golang/ directories.

Releases

Python Releases:

Add this to your .github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-release.yml@v1
    with:
      publish-pypi: true  # Optional: also publish to PyPI
    secrets:
      release_token: ${{ secrets.GITHUB_TOKEN }}
      pypi_token: ${{ secrets.PYPI_TOKEN }}  # Optional

Push a tag to trigger: git tag v1.0.0 && git push origin v1.0.0

This will:

• Build Python packages (wheel + sdist)
• Create GitHub release with artifacts
• Optionally publish to PyPI

Go Releases:

Add this to your .github/workflows/release.yml:

name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    uses: whisller/forge-ci/.github/workflows/forge-ci-go-release.yml@v1
    secrets:
      release_token: ${{ secrets.GITHUB_TOKEN }}

Push a tag to trigger: git tag v1.0.0 && git push origin v1.0.0

This will:

• Build multi-platform binaries (Linux, macOS, Windows)
• Create GitHub release with all artifacts
• Generate changelog from git commits

Examples

Example projects demonstrating different dependency managers and languages:

• examples/python-poetry/ - Poetry-based Python project
• examples/python-uv/ - uv-based Python project
• examples/python-venv/ - pip/venv-based Python project
• examples/golang/ - Go project with HTTP server
• examples/_workflows/ - Example workflow customizations

Usage Patterns

Simple Usage (Defaults)

jobs:
  validate:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-validate-pr.yml@v1

Custom Python Version

jobs:
  validate:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-validate-pr.yml@v1
    with:
      python-version: '3.11'

Use uv Instead of Poetry

jobs:
  validate:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-validate-pr.yml@v1
    with:
      dependency-manager: 'uv'

Compose Custom Pipeline

jobs:
  deps:
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-dependency-manager.yml@v1

  lint:
    needs: deps
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-ruff.yml@v1
    with:
      dependencies-cache-key: ${{ needs.deps.outputs.dependencies-cache-key }}

  test:
    needs: deps
    uses: whisller/forge-ci/.github/workflows/forge-ci-python-tools-pytest-cov.yml@v1
    with:
      dependencies-cache-key: ${{ needs.deps.outputs.dependencies-cache-key }}
      coverage-threshold: 90

Copy-Paste for Custom Modifications

If you need extensive customization beyond what inputs allow, you can copy workflows directly into your repository:

1. Copy the workflow file from forge-ci into your .github/workflows/ directory
2. Modify as needed - add custom steps, change execution order, integrate additional tools

Version Pinning

Always pin to a specific version for stability:

# Recommended: Pin to exact version
uses: whisller/forge-ci/.github/workflows/forge-ci-python-validate-pr.yml@v1

# Good: Pin to major version (gets patches/features, no breaking changes)
uses: whisller/forge-ci/.github/workflows/forge-ci-python-validate-pr.yml@v1

# Risky: Use main branch (gets all changes, including breaking)
uses: whisller/forge-ci/.github/workflows/forge-ci-python-validate-pr.yml@main

Tool Versions

forge-ci does not pin tool versions. Your project's dependency manager configuration determines which versions of ruff, mypy, pytest, and other tools are installed.