Composite GitHub Actions Reference

Reusing 3–10 steps that always run together → composite action
Reusing an entire job that needs its own runner → reusable workflow
Need secrets:inherit or secrets:inherit shortcut → reusable workflow
Need a matrix strategy defined inside the reused unit → reusable workflow
Caller needs the result as a step output → composite action
Reused unit needs different permissions from caller → reusable workflow

# Reusable workflow — top-level jobs key, not inside steps:
jobs:
  call-build:
    uses: org/actions/.github/workflows/build.yml@v1
    with:
      image_name: my-service
    secrets:
      registry_token: ${{ secrets.REGISTRY_TOKEN }}

# Composite action — inside a job's steps:
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: org/actions/docker-build-push@v1
        with:
          image_name: my-service

# Caller workflow in the same repo as the action
steps:
  - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
  - uses: ./.github/actions/my-action    # relative path — resolves to the checked-out repo

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # 1. Generate a short-lived installation token for the actions repo
      - name: Get GitHub App token
        id: app-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.ACTIONS_APP_ID }}
          private-key: ${{ secrets.ACTIONS_APP_PRIVATE_KEY }}
          repositories: actions   # the repo containing the composite action

      # 2. Check out the actions repo so the runner can find action.yml
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
        with:
          repository: org/actions
          ref: v1
          token: ${{ steps.app-token.outputs.token }}
          path: .actions   # check out into a subdirectory

      # 3. Reference the local copy
      - uses: ./.actions/docker-build-push
        with:
          image_name: my-service

- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
  with:
    repository: org/actions
    token: ${{ secrets.ORG_ACTIONS_PAT }}   # fine-grained PAT, Contents:Read
    path: .actions
- uses: ./.actions/my-action

Error: Can't find 'action.yml', 'action.yaml', or 'Dockerfile' under '/home/runner/work/...'

org/actions/
├── docker-build-push/action.yml
├── notify-slack/action.yml
├── setup-env/action.yml
└── .github/
    ├── dependabot.yml          (one file — updates all action SHAs)
    └── workflows/
        ├── test-docker-build-push.yml
        ├── test-notify-slack.yml
        └── release.yml         (tags: v1.2.3 → updates org/actions@v1)

- uses: org/actions/docker-build-push@v1
- uses: org/actions/notify-slack@v2

org/action-docker-build-push/action.yml   → org/action-docker-build-push@v1
org/action-notify-slack/action.yml        → org/action-notify-slack@v1

< 5 actions, same team owns all of them    → mono-repo
> 10 actions or multiple owning teams      → per-action repos or domain-grouped repos
Some actions go to Marketplace             → those actions get their own repos; internal ones in mono-repo
Actions have vastly different release cadences → per-action repos

# On release of v1.2.3:
git tag v1.2.3
git tag -f v1             # update floating major tag
git push origin v1.2.3
git push origin v1 --force

# Callers pinning to @v1 automatically get v1.2.3
# Callers pinning to SHA are unaffected — intentional

name: 'Setup Node with Cache'                      # shown in the Marketplace and action picker
description: 'Install Node.js, restore npm cache'  # one sentence
author: 'Platform Team'

inputs:
  node_version:
    description: 'Node.js version (e.g. 20.x)'
    required: false
    default: '20.x'
  enable_cache:
    description: 'Restore npm cache keyed on package-lock.json'
    required: false
    default: 'true'
    type: boolean    # still arrives as a string — compare with == 'true'

outputs:
  node_version:
    description: 'The Node.js version that was installed'
    value: ${{ steps.setup.outputs.node-version }}
  cache_hit:
    description: 'true if the npm cache was restored'
    value: ${{ steps.cache.outputs.cache-hit }}

runs:
  using: 'composite'       # required — must be the literal string "composite"
  steps:
    - name: Restore npm cache
      id: cache
      uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684  # v4.2.3
      with:
        path: ~/.npm
        key: ${{ runner.os }}-node-${{ inputs.node_version }}-${{ hashFiles('**/package-lock.json') }}

    - name: Setup Node.js
      id: setup
      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4.4.0
      with:
        node-version: ${{ inputs.node_version }}

    - name: Install dependencies
      shell: bash          # required on every run: step — composite has no inherited default
      run: npm ci --prefer-offline

branding:
  icon: 'package'          # Feather icon name
  color: 'green'           # white | yellow | blue | green | orange | red | purple | gray-dark

Caller's secrets store
        │
        │  with:
        │    webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}
        ▼
inputs:
  webhook_url:          ← declared as required: true in action.yml
    required: true
        │
        │  env: WEBHOOK_URL: ${{ inputs.webhook_url }}
        ▼
Shell step            ← reads $WEBHOOK_URL — never ${{ inputs.webhook_url }} directly

# action.yml
inputs:
  webhook_url:
    description: 'Slack incoming webhook URL — pass ${{ secrets.SLACK_WEBHOOK_URL }}'
    required: true

runs:
  using: 'composite'
  steps:
    - name: Send notification
      shell: bash
      env:
        WEBHOOK_URL: ${{ inputs.webhook_url }}    # safely isolated from shell parsing
      run: |
        echo "::add-mask::$WEBHOOK_URL"           # mask it from logs immediately
        curl -s -X POST "$WEBHOOK_URL" \
          -H 'Content-Type: application/json' \
          -d '{"text":"Build complete"}'

# Caller job — matrix is defined here
jobs:
  build:
    strategy:
      matrix:
        environment: [dev, staging, production]
    steps:
      - uses: org/actions/deploy@v1
        with:
          environment: ${{ matrix.environment }}   # thread matrix value as an input
          previous_sha: ${{ needs.setup.outputs.sha }}  # thread needs output as an input

# action.yml — receives the values as plain inputs
inputs:
  environment:
    description: 'Target environment'
    required: true
  previous_sha:
    description: 'SHA from the setup job'
    required: false

# Caller
- name: Compute version
  id: version
  run: echo "value=1.2.3" >> "$GITHUB_OUTPUT"

- uses: org/actions/release@v1
  with:
    version: ${{ steps.version.outputs.value }}   # thread caller step output as input

# action.yml — steps.version is NOT visible here; use inputs.version instead

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:org/repo:*"
        }
      }
    }
  ]
}

aws iam create-open-id-connect-provider \
  --url https://token.actions.githubusercontent.com \
  --client-id-list sts.amazonaws.com \
  --thumbprint-list 6938fd4d98bab03faadb97b34396831e3780aea1

az ad app federated-credential create \
  --id <app-object-id> \
  --parameters '{
    "name": "github-actions-prod",
    "issuer": "https://token.actions.githubusercontent.com",
    "subject": "repo:org/repo:environment:production",
    "audiences": ["api://AzureADTokenExchange"]
  }'

az role assignment create \
  --assignee <service-principal-id> \
  --role "Contributor" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/<rg>"

# AWS — reads OIDC token from ACTIONS_ID_TOKEN_REQUEST_URL automatically
provider "aws" {
  region = var.aws_region
  # No access_key / secret_key — relies on ambient OIDC credentials set by the action
}

# Azure — uses env vars set by azure/login
provider "azurerm" {
  features {}
  use_oidc = true
  # ARM_CLIENT_ID, ARM_TENANT_ID, ARM_SUBSCRIPTION_ID set by the action
}

- name: Configure AWS credentials via OIDC
  uses: aws-actions/configure-aws-credentials@8df5847569e6427dd6c4fb1cf565c83acfa8afa7  # v6.0.0
  with:
    role-to-assume: ${{ vars.AWS_ROLE_ARN }}
    aws-region: us-east-1

- name: Update kubeconfig for EKS
  shell: bash
  run: aws eks update-kubeconfig --name my-cluster --region us-east-1

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: github-actions-deploy
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: edit
subjects:
  - kind: User
    name: arn:aws:iam::123456789012:role/github-actions-deploy
    apiGroup: rbac.authorization.k8s.io

- name: Azure login via OIDC
  uses: azure/login@532459ea530d8321f2fb9bb10d1e0bcf23869a43  # v3.0.0
  with:
    client-id: ${{ vars.AZURE_CLIENT_ID }}
    tenant-id: ${{ vars.AZURE_TENANT_ID }}
    subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

- name: Install kubelogin
  shell: bash
  timeout-minutes: 3
  run: |
    az aks install-cli --only-show-errors \
      --kubelogin-install-location /usr/local/bin/kubelogin

- name: Get AKS credentials
  shell: bash
  run: |
    az aks get-credentials \
      --resource-group my-rg \
      --name my-cluster \
      --overwrite-existing
    kubelogin convert-kubeconfig -l workloadidentity

# Cluster User Role — allows az aks get-credentials
az role assignment create \
  --assignee <service-principal-object-id> \
  --role "Azure Kubernetes Service Cluster User Role" \
  --scope /subscriptions/SUB/resourceGroups/RG/providers/Microsoft.ContainerService/managedClusters/CLUSTER

# Then bind to a Kubernetes Role/ClusterRole inside the cluster using the SP object ID or an AAD group

- name: Authenticate to GCP
  uses: google-github-actions/auth@6fc4af4b145ae7821d527454aa9bd537d1f2dc5f  # v2.1.7
  with:
    workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/github/providers/github
    service_account: deployer@my-project.iam.gserviceaccount.com

- name: Get GKE credentials
  uses: google-github-actions/get-gke-credentials@20b2b9f6b9a6a5cc0b7a435e26fdb9cf6de2e1fa  # v2.3.1
  with:
    cluster_name: my-cluster
    location: us-central1
    project_id: my-project

resource "google_iam_workload_identity_pool" "github" {
  workload_identity_pool_id = "github-actions"
}

resource "google_iam_workload_identity_pool_provider" "github" {
  workload_identity_pool_id          = google_iam_workload_identity_pool.github.workload_identity_pool_id
  workload_identity_pool_provider_id = "github-provider"
  oidc { issuer_uri = "https://token.actions.githubusercontent.com" }
  attribute_mapping = {
    "google.subject"       = "assertion.sub"
    "attribute.repository" = "assertion.repository"
  }
  attribute_condition = "assertion.repository == 'org/repo'"
}

resource "google_service_account_iam_member" "wif_binding" {
  service_account_id = google_service_account.deployer.name
  role               = "roles/iam.workloadIdentityUser"
  member             = "principalSet://iam.googleapis.com/${google_iam_workload_identity_pool.github.name}/attribute.repository/org/repo"
}

inputs:
  # String (default)
  image_name:
    description: 'Container image name'
    required: true

  # Choice — validates at workflow parse time
  log_level:
    description: 'Logging verbosity'
    required: false
    default: 'info'
    type: choice
    options: [debug, info, warn, error]

  # Boolean — arrives as string; always compare with == 'true'
  push:
    description: 'Push the image after build'
    required: false
    default: 'true'
    type: boolean

# 1. Template expression — use in YAML values only, never directly in run: commands
${{ inputs.image_name }}

# 2. Environment variable — always use this inside shell scripts
# Name rule: INPUT_ prefix + uppercased name, hyphens → underscores
$INPUT_IMAGE_NAME

runs:
  using: 'composite'
  steps:
    - name: Compute short SHA tag
      id: tag
      shell: bash
      run: |
        SHORT="${GITHUB_SHA:0:7}"
        echo "value=$SHORT" >> "$GITHUB_OUTPUT"

outputs:
  image_tag:
    description: 'Short SHA used as the image tag'
    value: ${{ steps.tag.outputs.value }}    # must reference a step id

- name: Build image
  id: build
  shell: bash
  run: |
    DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' myapp:latest)
    echo "digest=$DIGEST" >> "$GITHUB_OUTPUT"

- name: Sign image
  shell: bash
  env:
    IMAGE_DIGEST: ${{ steps.build.outputs.digest }}
  run: |
    cosign sign "$IMAGE_DIGEST"

# ❌ Tag — mutable, can be rewritten to point to malicious code
- uses: actions/checkout@v4

# ✅ SHA — immutable, tied to the exact code reviewed; add version as comment
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

# ❌
- run: echo "hello"

# ✅
- shell: bash
  run: echo "hello"

# ✅ action.yml
inputs:
  github_token:
    description: 'GitHub token — pass ${{ secrets.GITHUB_TOKEN }}'
    required: true

# ✅ caller workflow
- uses: org/repo/actions/deploy@abc123
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}

# ❌ Shell injection — inputs.environment is expanded before bash parses
- shell: bash
  run: deploy.sh --env ${{ inputs.environment }}

# ✅ Data, not code — bash sees the value as an env var, not a command
- shell: bash
  env:
    DEPLOY_ENV: ${{ inputs.environment }}
  run: |
    case "$DEPLOY_ENV" in
      dev|staging|production) ;;
      *) echo "::error::Invalid environment: $DEPLOY_ENV" && exit 1 ;;
    esac
    deploy.sh --env "$DEPLOY_ENV"

- name: Retrieve ephemeral token
  id: token
  shell: bash
  run: |
    TOKEN=$(curl -s https://auth.example.com/token | jq -r '.access_token')
    echo "::add-mask::$TOKEN"
    echo "value=$TOKEN" >> "$GITHUB_OUTPUT"

# ❌ Breaks when the caller's CWD differs from the action's directory
- shell: bash
  run: ./scripts/validate.sh

# ✅ Always resolves to the action's own directory
- shell: bash
  run: |
    chmod +x "${{ github.action_path }}/scripts/validate.sh"
    "${{ github.action_path }}/scripts/validate.sh"

# Minimum permissions required by this action
permissions:
  contents: read
  packages: write    # push to GHCR
  id-token: write    # OIDC

- name: Write job summary
  if: always()
  shell: bash
  run: |
    {
      echo "## Build Result"
      echo ""
      echo "| Field | Value |"
      echo "|---|---|"
      echo "| Image | \`${{ inputs.registry }}/${{ inputs.image_name }}\` |"
      echo "| Tag | \`${{ steps.tag.outputs.value }}\` |"
      echo "| Digest | \`${{ steps.push.outputs.digest }}\` |"
      echo "| Status | $([[ '${{ job.status }}' == 'success' ]] && echo '✅ Success' || echo '❌ Failed') |"
    } >> "$GITHUB_STEP_SUMMARY"

- name: Install and validate
  shell: bash
  run: |
    echo "::group::Install dependencies"
    npm ci
    echo "::endgroup::"

    echo "::group::Run lint"
    npm run lint
    echo "::endgroup::"

# Error — fails the check (shown as ❌ in PR)
echo "::error file=src/app.ts,line=42,col=5::Null pointer dereference"

# Warning — advisory, does not fail (shown as ⚠️)
echo "::warning file=terraform/main.tf,line=10::Deprecated resource type"

# Notice — informational (shown as ℹ️)
echo "::notice::Image built successfully: $IMAGE_TAG"

- name: Compute cache key
  shell: bash
  run: |
    KEY="${{ runner.os }}-node-${{ inputs.version }}-${{ hashFiles('**/package-lock.json') }}"
    echo "::debug::Cache key: $KEY"
    echo "cache_key=$KEY" >> "$GITHUB_OUTPUT"

- name: Run deployment
  shell: bash
  run: |
    if [[ "${RUNNER_DEBUG:-0}" == "1" ]]; then
      set -x       # echo every command
      kubectl get all -n "$NAMESPACE"
    fi
    kubectl apply -f manifest.yml
  env:
    NAMESPACE: ${{ inputs.namespace }}

- name: Validate inputs
  shell: bash
  env:
    IMAGE_NAME: ${{ inputs.image_name }}
    ENVIRONMENT: ${{ inputs.environment }}
    SEVERITY: ${{ inputs.severity }}
  run: |
    ERRORS=()

    # Required inputs
    [[ -z "$IMAGE_NAME" ]] && ERRORS+=("image_name is required")

    # Enum validation
    case "$ENVIRONMENT" in
      dev|staging|production) ;;
      *) ERRORS+=("environment must be one of: dev, staging, production (got: $ENVIRONMENT)") ;;
    esac

    # Pattern validation
    if [[ -n "$SEVERITY" ]] && ! echo "$SEVERITY" | grep -qE '^(UNKNOWN|LOW|MEDIUM|HIGH|CRITICAL)(,(UNKNOWN|LOW|MEDIUM|HIGH|CRITICAL))*$'; then
      ERRORS+=("severity must be comma-separated severity levels (e.g. HIGH,CRITICAL)")
    fi

    # Report all errors at once
    if [[ ${#ERRORS[@]} -gt 0 ]]; then
      for err in "${ERRORS[@]}"; do
        echo "::error::$err"
      done
      exit 1
    fi

- name: Build image
  id: build           # referenced as steps.build.outputs.digest below
  uses: docker/build-push-action@...
  with:
    push: true

# Run only when input flag is set
- name: Push image
  if: inputs.push == 'true'
  shell: bash
  run: docker push "$IMAGE_URI"

# Run on failure — e.g., cleanup or notification
- name: Notify on failure
  if: failure()
  shell: bash
  env:
    WEBHOOK: ${{ inputs.slack_webhook_url }}
  run: |
    curl -s -X POST "$WEBHOOK" \
      -H 'Content-Type: application/json' \
      -d "{\"text\":\"Build failed in ${{ github.repository }}@${{ github.sha }}\"}"

# Always run — e.g., upload logs, write summary
- name: Upload logs
  if: always()
  uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1029d08800d6f4dc  # v4.5.0
  with:
    name: build-logs-${{ github.run_id }}
    path: '*.log'

# ✅ continue-on-error: true — optional step, failure is ignored for job outcome
- name: Optional security scan
  id: scan
  continue-on-error: true
  uses: aquasecurity/trivy-action@...
  with:
    exit-code: '1'

- name: Report scan result
  shell: bash
  run: |
    # steps.scan.conclusion == 'success' even if scan found CVEs and exited 1
    # Use steps.scan.outcome (not conclusion) to check the real result
    echo "Scan outcome: ${{ steps.scan.outcome }}"

# ✅ if: always() — cleanup must run regardless of what failed above
- name: Delete temp kubeconfig
  if: always()
  shell: bash
  run: rm -f "$KUBECONFIG_TMPFILE"

# ❌ Wrong — cleanup is SKIPPED if the deploy step fails
- name: Deploy
  run: kubectl apply -f manifest.yml
- name: Cleanup
  continue-on-error: true   # this only affects THIS step's failure, not whether it runs
  run: rm -f /tmp/kubeconfig

# ✅ Correct — cleanup always runs
- name: Deploy
  run: kubectl apply -f manifest.yml
- name: Cleanup
  if: always()
  run: rm -f /tmp/kubeconfig

- name: Optional lint
  id: lint
  shell: bash
  continue-on-error: true
  run: npm run lint

- name: Report lint result
  shell: bash
  run: |
    # Use .outcome (actual result), not .conclusion (always success with continue-on-error)
    if [[ "${{ steps.lint.outcome }}" == "failure" ]]; then
      echo "::warning::Lint failed — see output above"
    fi

actions/
└── k8s-deploy/
    ├── action.yml
    └── scripts/
        └── deploy.sh

- name: Deploy to Kubernetes
  shell: bash
  run: |
    chmod +x "${{ github.action_path }}/scripts/deploy.sh"
    "${{ github.action_path }}/scripts/deploy.sh"
  env:
    KUBECONFIG_CONTENT: ${{ inputs.kubeconfig }}
    NAMESPACE: ${{ inputs.namespace }}

- name: Add action scripts to PATH
  shell: bash
  run: echo "${{ github.action_path }}/scripts" >> "$GITHUB_PATH"

- name: Deploy
  shell: bash
  run: deploy.sh    # found via PATH

- name: Set platform-specific paths
  shell: bash
  run: |
    if [[ "${{ runner.os }}" == "Windows" ]]; then
      echo "TOOL_PATH=C:\\tools\\bin" >> "$GITHUB_ENV"
      echo "EXT=.exe" >> "$GITHUB_ENV"
    else
      echo "TOOL_PATH=/usr/local/bin" >> "$GITHUB_ENV"
      echo "EXT=" >> "$GITHUB_ENV"
    fi

- name: Install tool
  shell: bash
  run: |
    if [[ "${{ runner.os }}" == "macOS" ]]; then
      brew install mytool
    elif [[ "${{ runner.os }}" == "Linux" ]]; then
      sudo apt-get install -y mytool
    else
      choco install mytool
    fi

# Windows steps use pwsh, not bash
- name: Windows-only step
  if: runner.os == 'Windows'
  shell: pwsh
  run: Write-Host "Running on Windows"

- name: Construct path
  shell: bash
  env:
    BASE_DIR: ${{ inputs.base_dir }}
  run: |
    # Use forward slashes even on Windows in bash shell
    FULL_PATH="$BASE_DIR/config/app.yml"
    echo "config_path=$FULL_PATH" >> "$GITHUB_OUTPUT"

# Pattern 1 — Skip if already done
- name: Check if image tag exists
  id: check
  shell: bash
  run: |
    if docker manifest inspect "${{ inputs.registry }}/${{ inputs.image_name }}:${{ inputs.image_tag }}" > /dev/null 2>&1; then
      echo "exists=true" >> "$GITHUB_OUTPUT"
      echo "::notice::Image already exists — skipping build"
    else
      echo "exists=false" >> "$GITHUB_OUTPUT"
    fi

- name: Build and push
  if: steps.check.outputs.exists == 'false'
  uses: docker/build-push-action@...

# Pattern 2 — Upsert (create or update)
- name: Create or update Kubernetes deployment
  shell: bash
  run: |
    kubectl apply -f manifest.yml   # apply is idempotent by design

# Pattern 3 — Check before delete
- name: Delete old tag if exists
  shell: bash
  run: |
    if git tag -l "${{ inputs.version }}" | grep -q .; then
      git tag -d "${{ inputs.version }}"
    fi
    git tag "${{ inputs.version }}"

- name: Wait for deployment to stabilise
  shell: bash
  timeout-minutes: 10    # fail this step if it runs longer than 10 minutes
  run: |
    kubectl rollout status deployment/"$DEPLOYMENT" -n "$NAMESPACE" --timeout=600s
  env:
    DEPLOYMENT: ${{ inputs.deployment_name }}
    NAMESPACE: ${{ inputs.namespace }}

- name: Call external API
  shell: bash
  timeout-minutes: 2
  run: curl --max-time 90 -s "$API_URL"
  env:
    API_URL: ${{ inputs.api_url }}

# Recommended in the caller workflow when using deploy or release actions
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false   # false for deploy/release; true for validation/build

name: Test composite action

on:
  push:
    paths:
      - 'actions/**'
      - '.github/workflows/test-action.yml'
  pull_request:
    paths:
      - 'actions/**'

jobs:
  test-defaults:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

      - name: Run action with default inputs
        id: result
        uses: ./actions/setup-env

      - name: Verify outputs
        shell: bash
        run: |
          echo "node_version: ${{ steps.result.outputs.node_version }}"
          node --version | grep -q "^v20\." || { echo "::error::Wrong Node version"; exit 1; }

  test-matrix:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node_version: ['18.x', '20.x', '22.x']
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
      - uses: ./actions/setup-env
        with:
          node_version: ${{ matrix.node_version }}

brew install act

# Run with a full Ubuntu image
act -P ubuntu-latest=catthehacker/ubuntu:act-22.04 \
    -W .github/workflows/test-action.yml

# With secrets
act -W .github/workflows/test-action.yml \
    --secret SLACK_WEBHOOK_URL=https://hooks.slack.com/...

# Install actionlint
brew install actionlint

# Validate
actionlint actions/setup-env/action.yml

# Check all external actions are SHA-pinned
grep -rn 'uses:' actions/ \
  | grep -vE '(@[0-9a-f]{40}|\./)' \
  | grep -v '#'

# Check every run: step has shell:
grep -B1 'run:' actions/*/action.yml | grep -v 'shell:' | grep 'run:'

# Step 1 — Add a deprecation warning on the old input (minor version)
- name: Check for deprecated inputs
  shell: bash
  run: |
    if [[ -n "$OLD_INPUT" ]]; then
      echo "::warning::Input 'aws_role' is deprecated. Use 'aws_role_arn' instead. This will be removed in v3."
    fi
  env:
    OLD_INPUT: ${{ inputs.aws_role }}

# Step 2 — Support both old and new inputs in the same minor version
- name: Resolve role ARN
  id: role
  shell: bash
  run: |
    ARN="${ROLE_ARN:-$OLD_ROLE}"
    [[ -z "$ARN" ]] && echo "::error::Provide aws_role_arn" && exit 1
    echo "arn=$ARN" >> "$GITHUB_OUTPUT"
  env:
    ROLE_ARN: ${{ inputs.aws_role_arn }}
    OLD_ROLE: ${{ inputs.aws_role }}

# Step 3 — Remove old input in next major version

## [v2.0.0] - 2026-05-23
### Breaking changes
- `aws_role` input renamed to `aws_role_arn` — update your `with:` block
### Migration
Replace `aws_role: arn:...` with `aws_role_arn: arn:...`

v1.0.0  — initial release
v1.0.1  — patch: fix shell quoting bug
v1.1.0  — minor: add enable_cache input
v2.0.0  — major: rename aws_role → aws_role_arn (breaking)
v1      — floating tag, always points to latest v1.x.x

name: Release action

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

      - name: Validate with actionlint
        shell: bash
        run: |
          curl -sL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash | bash
          ./actionlint

      - name: Update floating major version tag
        shell: bash
        run: |
          MAJOR=$(echo "${{ github.ref_name }}" | cut -d. -f1)
          git tag -f "$MAJOR"
          git push origin "$MAJOR" --force

      - name: Create GitHub release
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea  # v7.0.1
        with:
          script: |
            const tag = context.ref.replace('refs/tags/', '');
            await github.rest.repos.createRelease({
              owner: context.repo.owner,
              repo: context.repo.repo,
              tag_name: tag,
              name: tag,
              generate_release_notes: true,
            });

# .github/dependabot.yml
version: 2
updates:
  # Keep GitHub Actions up to date
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "09:00"
      timezone: "UTC"
    commit-message:
      prefix: "chore(deps)"
    labels:
      - "dependencies"
      - "github-actions"
    groups:
      github-actions:
        patterns:
          - "*"
    # Also update actions within composite action steps
  - package-ecosystem: "github-actions"
    directory: "/actions"
    schedule:
      interval: "weekly"

# In main step — save state
echo "KUBECONFIG_PATH=/tmp/kube-abc123" >> "$GITHUB_STATE"

# In post: step — read state
echo "Cleaning up ${STATE_KUBECONFIG_PATH}"
rm -f "${STATE_KUBECONFIG_PATH}"

steps:
  - name: Write kubeconfig
    id: write-kube
    shell: bash
    run: |
      TMPFILE=$(mktemp /tmp/kubeconfig-XXXXXX)
      echo "$KUBECONFIG_B64" | base64 -d > "$TMPFILE"
      chmod 600 "$TMPFILE"
      echo "path=$TMPFILE" >> "$GITHUB_OUTPUT"
      echo "KUBECONFIG_TMPFILE=$TMPFILE" >> "$GITHUB_ENV"
    env:
      KUBECONFIG_B64: ${{ inputs.kubeconfig }}

  # ... main steps ...

  - name: Cleanup kubeconfig
    if: always()      # runs even if earlier steps fail
    shell: bash
    run: |
      rm -f "$KUBECONFIG_TMPFILE"
      echo "::notice::Temporary kubeconfig deleted"

# inner-action/action.yml
name: 'Setup credentials'
runs:
  using: 'composite'
  steps:
    - name: Configure AWS
      uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502  # v4.0.2
      with:
        role-to-assume: ${{ inputs.role_arn }}
        aws-region: ${{ inputs.aws_region }}

# outer-action/action.yml — calls the inner action
name: 'Deploy to ECS'
runs:
  using: 'composite'
  steps:
    - name: Setup credentials
      uses: org/repo/inner-action@v1    # calls the inner composite action
      with:
        role_arn: ${{ inputs.role_arn }}
        aws_region: ${{ inputs.aws_region }}

    - name: Deploy
      shell: bash
      run: aws ecs update-service ...

## Runner requirements

This action works on both GitHub-hosted and self-hosted runners. Self-hosted runners must have:
- `bash` >= 4.0
- `curl`
- `docker` (for image scan target only)
- Internet access to `trivy.dev` for database updates (or set `trivy_version` to a pre-cached binary)

# Runner group: require ephemeral
gh api \
  --method PATCH \
  /orgs/{org}/actions/runner-groups/{group_id} \
  -f runs_on_self_hosted_runners_only=true \
  -f runners_type="ephemeral"

## Security note — ephemeral runners recommended

This action handles a `kubeconfig` secret. Run it on **ephemeral** (single-use) runners so the
temporary kubeconfig file cannot be accessed by subsequent jobs on the same machine.

GitHub-hosted runners (`ubuntu-latest`) are ephemeral by default.
For self-hosted runners, configure the runner group to use `--ephemeral` mode.

Error: required property is missing: shell

# action.yml
inputs:
  my_token:
    description: 'Pass ${{ secrets.MY_SECRET }}'
    required: true

# caller workflow
- uses: org/repo/my-action@v1
  with:
    my_token: ${{ secrets.MY_SECRET }}

Error: Can't find 'action.yml', 'action.yaml', or 'Dockerfile'

steps:
  - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
  - uses: ./.github/actions/my-action   # matches the directory where action.yml lives

# SC2086: quote variable
echo $FOO          # ❌
echo "$FOO"        # ✅

# SC2181: use direct exit code check
cmd; if [ $? -ne 0 ]; then    # ❌
if ! cmd; then                 # ✅

# SC2155: declare and assign separately
export FOO=$(bar)              # ❌
FOO=$(bar); export FOO         # ✅

# Suppress a specific check (last resort)
# shellcheck disable=SC2046
eval $(some_command)

# Install
brew install actionlint     # macOS
# or:
curl -sL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash \
  | bash -s -- latest /usr/local/bin

# Lint a single action
actionlint action.yml

# Lint all workflows in a repo
actionlint .github/workflows/*.yml

# With shellcheck integration
actionlint -shellcheck shellcheck action.yml

- name: Set tag
  shell: bash    # missing id:
  run: echo "tag=v1.2.3" >> "$GITHUB_OUTPUT"

# ❌ — colon instead of equals
echo "tag:v1.2.3" >> "$GITHUB_OUTPUT"

# ✅
echo "tag=v1.2.3" >> "$GITHUB_OUTPUT"

# ❌ — newlines in value break the key=value format
echo "body=$(cat NOTES.md)" >> "$GITHUB_OUTPUT"

# ✅ — EOF delimiter
{
  echo "body<<EOF"
  cat NOTES.md
  echo "EOF"
} >> "$GITHUB_OUTPUT"

gh run list --workflow release.yml --limit 5
gh api repos/{owner}/{repo}/git/refs/tags/v1 | jq .object.sha
gh api repos/{owner}/{repo}/git/refs/tags/v1.2.0 | jq .object.sha
# Both should return the same SHA after a successful release

git fetch --tags
git tag -f v1 v1.2.0
git push origin v1 --force

if [[ "$INPUT_ENABLE_CACHE" == "true" ]]; then

if: inputs.enable_cache == 'true'