go-ci/README.md

Go CI/CD Composite Action

A reusable GitHub Action for Go projects, forged to handle various CI/CD scenarios like a true warrior of code. Supports protected branches, tagged releases, and minimal development flows — with optional Docker image publishing for applications.

🔧 Features

• Multiple workflow modes: protected, tag, and minimal
• Go version configuration
• Automatic test execution with code coverage
• Build support for both libraries and applications
• Conditional Docker image creation and publishing
• Composable and easy to integrate in any Go project

📥 Inputs

Input Name	Description	Required	Default
workflow-type	Type of CI/CD flow (protected, minimal, tag)	Yes	protected
go-version	Go version to install and use	No	1.24
build-type	Type of build (application, library)	No	application
container-registry	Container registry URL (used if publishing Docker image)	Yes	—
publish-docker	Whether to build and push Docker image (true / false)	No	true

⚙️ Workflow Types

• protected: Full CI/CD pipeline for mainline branches. Runs tests, builds the binary, and optionally publishes a Docker image.
• minimal: Lean setup for pull requests or early development. Runs tests and builds only.
• tag: Triggered on Git tags. Behaves like protected, ideal for versioned releases.

🚀 How to Use

name: Go CI/CD Pipeline
on: [push, pull_request, workflow_dispatch]

jobs:
  go-ci:
    runs-on: ubuntu-latest
    steps:
      - uses: your-org/go-ci-action@v1
        with:
          workflow-type: 'protected'
          go-version: '1.24'
          build-type: 'application'
          container-registry: ghcr.io/your-org
          publish-docker: 'true'

Replace your-org/go-ci-action and ghcr.io/your-org with your actual repository and registry.

🛠️ Step Breakdown

1. Checkout code – Pulls the code from your repo.
2. Set up Go – Installs and configures the specified Go version.
3. Download dependencies – Runs go mod tidy to sync modules.
4. Run tests – Executes unit tests with JSON and coverage output.
5. Build – Builds all packages (library) or compiles an app binary (application).
6. Generate image tag – Creates a Docker tag based on branch/tag/ref.
7. Login to registry – Authenticates with your container registry.
8. Build & push image – Pushes the image if publish-docker is enabled.

🔐 Requirements

You must configure these in your environment for the action to work correctly:

Environment Variables

• DEPLOYER_USERNAME: Your Docker registry username

Secrets

• DEPLOYER_TOKEN: Your Docker registry password or access token

🧙 Best Practices

• Use minimal for development and PRs to save resources.
• Use tag for releases to generate versioned images.
• Disable publish-docker when working on Go libraries or services not meant to be containerized.

---

Crafted with reusability, clarity, and precision in mind. May your builds be swift and your tests ever green.

“We don’t just build software — we forge legacy.”