Reusable Workflows & Composite Actions

# ── REUSABLE WORKFLOW: .github/workflows/build-and-push.yml ──────────────────

# (can be in the same repo or a shared .github repo)

name: Build and Push Docker Image (Reusable)



on:

  workflow_call:                    # makes this workflow callable

    inputs:

      image-name:

        required: true

        type: string

      environment:

        required: false

        type: string

        default: staging

    secrets:

      registry-token:

        required: true

    outputs:

      image-digest:

        description: "SHA256 digest of the pushed image"

        value: ${{ jobs.build.outputs.digest }}



jobs:

  build:

    runs-on: ubuntu-latest

    outputs:

      digest: ${{ steps.push.outputs.digest }}

    steps:

      - uses: actions/checkout@v4

      - uses: docker/setup-buildx-action@v3

      - uses: docker/login-action@v3

        with:

          registry: ghcr.io

          password: ${{ secrets.registry-token }}

      - name: Build and push

        id: push

        uses: docker/build-push-action@v5

        with:

          push: true

          tags: ghcr.io/${{ inputs.image-name }}:latest

          cache-from: type=gha

          cache-to: type=gha,mode=max



# ── CALLER WORKFLOW: in any repo ─────────────────────────────────────────────

name: Release



on:

  push:

    branches: [main]



jobs:

  build:

    uses: my-org/.github/.github/workflows/build-and-push.yml@main

    with:

      image-name: my-org/my-app

      environment: production

    secrets:

      registry-token: ${{ secrets.GITHUB_TOKEN }}



  deploy:

    needs: build

    runs-on: ubuntu-latest

    steps:

      - run: echo "Deployed image digest: ${{ needs.build.outputs.image-digest }}"

# .github/actions/setup-node-project/action.yml

name: Setup Node Project

description: Checkout, setup Node, restore cache, install deps



inputs:

  node-version:

    description: Node.js version

    default: '20'

  working-directory:

    description: Project directory

    default: '.'



outputs:

  cache-hit:

    description: Whether node_modules cache was hit

    value: ${{ steps.cache.outputs.cache-hit }}



runs:

  using: composite               # composite = multiple steps

  steps:

    - uses: actions/checkout@v4



    - uses: actions/setup-node@v4

      with:

        node-version: ${{ inputs.node-version }}



    - name: Restore cache

      id: cache

      uses: actions/cache@v4

      with:

        path: ${{ inputs.working-directory }}/node_modules

        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}



    - name: Install dependencies

      if: steps.cache.outputs.cache-hit != 'true'

      shell: bash

      working-directory: ${{ inputs.working-directory }}

      run: npm ci



# Use the composite action in any workflow:

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

      - uses: ./.github/actions/setup-node-project    # local reference

        with:

          node-version: '20'

      - run: npm test



  lint:

    runs-on: ubuntu-latest

    steps:

      - uses: ./.github/actions/setup-node-project

      - run: npm run lint

# When to use self-hosted runners:

# - Need access to private network (internal databases, private registries)

# - Need specific hardware (GPU for ML, large RAM, fast NVMe)

# - Cost at scale (GitHub-hosted is ~$0.008/minute; self-hosted is free)

# - Compliance: code must not leave your infrastructure



# Register a self-hosted runner (manual, for one machine):

# Settings → Actions → Runners → New self-hosted runner

# Follow the curl+configure+run instructions on your machine



# Actions Runner Controller (ARC) — Kubernetes-based auto-scaling runners

helm install arc \

  --namespace arc-systems \

  --create-namespace \

  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set-controller



helm install arc-runner-set \

  --namespace arc-runners \

  --create-namespace \

  --set githubConfigUrl=https://github.com/my-org \

  --set githubConfigSecret=arc-controller-manager \

  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set



# Use self-hosted runner in workflow:

jobs:

  build:

    runs-on: self-hosted             # any available self-hosted runner

    # or with labels:

    runs-on: [self-hosted, linux, gpu, high-memory]



# ARC scales runners from 0 to N based on queue depth

# Each runner pod is ephemeral — starts fresh per job (no persistent state)