build.yml

name: "Build and Push Docker Images"

# This reusable workflow handles Docker image builds and pushes to registries
# Supports both DockerHub and GHCR (GitHub Container Registry)
#
# Features:
# - Monorepo support with optional change detection via internal changed-paths composite
# - Multi-registry support (DockerHub and/or GHCR)
# - Platform strategy: beta/rc builds amd64 only, release builds amd64+arm64
# - Semantic versioning tags
# - GitOps artifacts upload for downstream gitops-update workflow
# - Helm chart dispatch for automatic version updates in Helm repositories

on:
  workflow_call:
    outputs:
      has_builds:
        description: 'Whether any components were detected for building (true/false). Use this to skip downstream jobs when no paths changed.'
        value: ${{ jobs.prepare.outputs.has_builds }}
    inputs:
      runner_type:
        description: 'Runner to use for the workflow'
        type: string
        default: 'blacksmith-4vcpu-ubuntu-2404'
      filter_paths:
        description: 'Newline-separated list of path prefixes to filter. If not provided, builds from root.'
        type: string
        required: false
        default: ''
      shared_paths:
        description: 'Newline-separated path patterns (e.g., "go.mod\ngo.sum") that trigger a build for ALL components when matched by any changed file.'
        type: string
        required: false
        default: ''
      path_level:
        description: 'Limits the path to the first N segments (e.g., 2 -> "apps/agent")'
        type: string
        default: '2'
      enable_dockerhub:
        description: 'Enable pushing to DockerHub'
        type: boolean
        default: true
      enable_ghcr:
        description: 'Enable pushing to GitHub Container Registry'
        type: boolean
        default: false
      dockerhub_org:
        description: 'DockerHub organization name'
        type: string
        default: 'lerianstudio'
      ghcr_org:
        description: 'GHCR organization name (defaults to repository owner)'
        type: string
        default: ''
      dockerfile_name:
        description: 'Name of the Dockerfile'
        type: string
        default: 'Dockerfile'
      app_name_prefix:
        description: 'Prefix for app names in monorepo (e.g., "midaz" results in "midaz-agent")'
        type: string
        default: ''
      app_name_overrides:
        description: 'Explicit app name mappings in "path:name" format. Use "path:" for prefix-only. Overrides default extraction for matched paths.'
        type: string
        default: ''
      build_context:
        description: 'Docker build context (defaults to repository root for monorepo)'
        type: string
        default: '.'
      enable_gitops_artifacts:
        description: 'Enable GitOps artifacts upload for downstream gitops-update workflow'
        type: boolean
        default: false
      # Helm dispatch configuration
      enable_helm_dispatch:
        description: 'Enable dispatching to Helm repository for chart updates'
        type: boolean
        default: false
      helm_repository:
        description: 'Helm repository to dispatch to (org/repo format, e.g., LerianStudio/helm)'
        type: string
        default: 'LerianStudio/helm'
      helm_chart:
        description: 'Helm chart name to update'
        type: string
        default: ''
      helm_target_ref:
        description: 'Target branch in Helm repository (e.g., develop, main)'
        type: string
        default: 'main'
      helm_components_base_path:
        description: 'Base path for components in source repo (default: components)'
        type: string
        default: 'components'
      helm_env_file:
        description: 'Env example file name relative to component path (default: .env.example)'
        type: string
        default: '.env.example'
      helm_detect_env_changes:
        description: 'Whether to detect new environment variables for Helm'
        type: boolean
        default: true
      helm_dispatch_on_rc:
        description: 'Enable Helm dispatch for release-candidate (rc) tags'
        type: boolean
        default: false
      helm_dispatch_on_beta:
        description: 'Enable Helm dispatch for beta tags'
        type: boolean
        default: false
      helm_values_key_mappings:
        description: 'JSON mapping of component names to values.yaml keys. If not mapped, uses component name as fallback. Example: {"my-app": "api", "my-app-worker": "worker"}'
        type: string
        default: ''
      # Path normalization
      normalize_to_filter:
        description: 'Normalize changed paths to their filter path (e.g., components/app/cmd -> components/app). Recommended for monorepos to avoid duplicate builds.'
        type: boolean
        default: true
      force_multiplatform:
        description: 'Force multi-platform build (amd64+arm64) even for beta/rc tags'
        type: boolean
        default: false

permissions:
  contents: read
  packages: write

jobs:
  prepare:
    runs-on: ${{ inputs.runner_type }}
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
      has_builds: ${{ steps.set-matrix.outputs.has_builds }}
      platforms: ${{ steps.set-platforms.outputs.platforms }}
      is_release: ${{ steps.set-platforms.outputs.is_release }}
    steps:
      - name: Get changed paths (monorepo)
        if: inputs.filter_paths != ''
        id: changed-paths
        uses: LerianStudio/github-actions-shared-workflows/src/config/changed-paths@v1.18.0
        with:
          filter-paths: ${{ inputs.filter_paths }}
          shared-paths: ${{ inputs.shared_paths }}
          path-level: ${{ inputs.path_level }}
          get-app-name: 'true'
          app-name-prefix: ${{ inputs.app_name_prefix }}
          app-name-overrides: ${{ inputs.app_name_overrides }}
          normalize-to-filter: ${{ inputs.normalize_to_filter }}

      - name: Set matrix
        id: set-matrix
        run: |
          if [ -z "${{ inputs.filter_paths }}" ]; then
            # Single app mode - build from root
            APP_NAME="${{ github.event.repository.name }}"
            echo "matrix=[{\"name\": \"${APP_NAME}\", \"working_dir\": \".\"}]" >> "$GITHUB_OUTPUT"
            echo "has_builds=true" >> "$GITHUB_OUTPUT"
          else
            MATRIX='${{ steps.changed-paths.outputs.matrix }}'
            if [ "$MATRIX" == "[]" ] || [ -z "$MATRIX" ]; then
              echo "matrix=[]" >> "$GITHUB_OUTPUT"
              echo "has_builds=false" >> "$GITHUB_OUTPUT"
            else
              echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"
              echo "has_builds=true" >> "$GITHUB_OUTPUT"
            fi
          fi

      - name: Set platforms based on tag type
        id: set-platforms
        run: |
          TAG="${GITHUB_REF#refs/tags/}"

          if [[ "$TAG" == *"-beta"* ]] || [[ "$TAG" == *"-rc"* ]]; then
            if [ "${{ inputs.force_multiplatform }}" == "true" ]; then
              echo "platforms=linux/amd64,linux/arm64" >> "$GITHUB_OUTPUT"
              echo "is_release=false" >> "$GITHUB_OUTPUT"
              echo "Building for amd64 and arm64 (beta/rc tag with force_multiplatform)"
            else
              echo "platforms=linux/amd64" >> "$GITHUB_OUTPUT"
              echo "is_release=false" >> "$GITHUB_OUTPUT"
              echo "Building for amd64 only (beta/rc tag)"
            fi
          else
            echo "platforms=linux/amd64,linux/arm64" >> "$GITHUB_OUTPUT"
            echo "is_release=true" >> "$GITHUB_OUTPUT"
            echo "Building for amd64 and arm64 (release tag)"
          fi

  build:
    needs: prepare
    if: needs.prepare.outputs.has_builds == 'true'
    runs-on: ${{ inputs.runner_type }}
    name: Build ${{ matrix.app.name }}
    strategy:
      max-parallel: 2
      fail-fast: false
      matrix:
        app: ${{ fromJson(needs.prepare.outputs.matrix) }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Set up QEMU
        if: contains(needs.prepare.outputs.platforms, 'arm64')
        uses: docker/setup-qemu-action@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v4

      - name: Log in to DockerHub
        if: inputs.enable_dockerhub
        uses: docker/login-action@v4
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Log in to GHCR
        if: inputs.enable_ghcr
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.MANAGE_TOKEN }}

      - name: Normalize repository owner to lowercase
        id: normalize
        run: |
          echo "owner_lower=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> "$GITHUB_OUTPUT"

      - name: Set image names
        id: image-names
        run: |
          IMAGES=""
          GHCR_ORG="${{ inputs.ghcr_org }}"
          if [ -z "$GHCR_ORG" ]; then
            GHCR_ORG="${{ steps.normalize.outputs.owner_lower }}"
          else
            GHCR_ORG=$(echo "$GHCR_ORG" | tr '[:upper:]' '[:lower:]')
          fi

          if [ "${{ inputs.enable_dockerhub }}" == "true" ]; then
            IMAGES="${{ inputs.dockerhub_org }}/${{ matrix.app.name }}"
          fi

          if [ "${{ inputs.enable_ghcr }}" == "true" ]; then
            if [ -n "$IMAGES" ]; then
              IMAGES="${IMAGES},ghcr.io/${GHCR_ORG}/${{ matrix.app.name }}"
            else
              IMAGES="ghcr.io/${GHCR_ORG}/${{ matrix.app.name }}"
            fi
          fi

          echo "images=$IMAGES" >> "$GITHUB_OUTPUT"

      - name: Extract version from tag
        id: version
        run: |
          TAG="${GITHUB_REF#refs/tags/}"
          # Strip app prefix by finding -v and extracting from there
          # e.g., agent-v1.0.0-beta.1 -> v1.0.0-beta.1
          # e.g., control-plane-v1.0.0-beta.1 -> v1.0.0-beta.1
          # shellcheck disable=SC2001
          VERSION=$(echo "$TAG" | sed 's/.*-\(v[0-9]\)/\1/')
          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
          echo "Extracted version: $VERSION from tag: $TAG"

      - name: Docker metadata
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ steps.image-names.outputs.images }}
          tags: |
            type=semver,pattern={{version}},value=${{ steps.version.outputs.version }}
            type=semver,pattern={{major}}.{{minor}},value=${{ steps.version.outputs.version }}
            type=semver,pattern={{major}},value=${{ steps.version.outputs.version }},enable=${{ needs.prepare.outputs.is_release }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v7
        with:
          context: ${{ inputs.build_context }}
          file: ${{ matrix.app.working_dir }}/${{ inputs.dockerfile_name }}
          platforms: ${{ needs.prepare.outputs.platforms }}
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          sbom: generator=docker/scout-sbom-indexer:latest
          provenance: mode=max
          cache-from: type=gha
          cache-to: type=gha,mode=max
          secrets: |
            github_token=${{ secrets.MANAGE_TOKEN }}

      # GitOps artifacts for downstream gitops-update workflow
      - name: Create GitOps tag artifact
        if: inputs.enable_gitops_artifacts
        run: |
          set -euo pipefail
          mkdir -p gitops-tags
          # Extract version without leading 'v'
          VERSION="${{ steps.version.outputs.version }}"
          VERSION="${VERSION#v}"
          printf "%s" "$VERSION" > "gitops-tags/${{ matrix.app.name }}.tag"
          echo "Created artifact: gitops-tags/${{ matrix.app.name }}.tag with version: $VERSION"

      - name: Upload GitOps tag artifact
        if: inputs.enable_gitops_artifacts
        uses: actions/upload-artifact@v7
        with:
          name: gitops-tags-${{ matrix.app.name }}
          path: gitops-tags/

  # Slack notification
  notify:
    name: Notify
    needs: [prepare, build]
    if: always() && needs.prepare.outputs.has_builds == 'true'
    uses: ./.github/workflows/slack-notify.yml
    with:
      status: ${{ needs.build.result }}
      workflow_name: "Build & Push Docker Images"
      failed_jobs: ${{ needs.build.result == 'failure' && 'Build' || '' }}
    secrets:
      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

  # Dispatch to Helm repository for chart updates
  # By default only runs on production releases (non-beta, non-rc tags)
  # Can be enabled for rc/beta via helm_dispatch_on_rc and helm_dispatch_on_beta inputs
  dispatch-helm:
    name: Dispatch Helm Update
    needs: [prepare, build]
    if: |
      inputs.enable_helm_dispatch &&
      needs.prepare.outputs.has_builds == 'true' &&
      needs.build.result == 'success' &&
      inputs.helm_chart != '' &&
      (
        needs.prepare.outputs.is_release == 'true' ||
        (contains(github.ref, '-rc') && inputs.helm_dispatch_on_rc) ||
        (contains(github.ref, '-beta') && inputs.helm_dispatch_on_beta)
      )
    uses: ./.github/workflows/dispatch-helm.yml
    with:
      helm_repository: ${{ inputs.helm_repository }}
      chart: ${{ inputs.helm_chart }}
      target_ref: ${{ inputs.helm_target_ref }}
      version: ${{ github.ref_name }}
      components_json: ${{ needs.prepare.outputs.matrix }}
      components_base_path: ${{ inputs.helm_components_base_path }}
      env_file: ${{ inputs.helm_env_file }}
      detect_env_changes: ${{ inputs.helm_detect_env_changes }}
      values_key_mappings: ${{ inputs.helm_values_key_mappings }}
      runner_type: ${{ inputs.runner_type }}
    secrets:
      helm_repo_token: ${{ secrets.HELM_REPO_TOKEN }}