# .github/actions/security-scan/action.yml
name: 'Container security scan'
description: 'Trivy scan with PR comment and severity gate'
inputs:
  image:
    description: 'Container image to scan'
    required: true
  severity-fail:
    description: 'Severities that fail the build'
    default: 'CRITICAL,HIGH'
outputs:
  critical-count:
    description: 'Number of CRITICAL vulnerabilities'
    value: ${{ steps.parse.outputs.critical }}
runs:
  using: composite
  steps:
    - shell: bash
      run: |
        trivy image --format json --output trivy.json ${{ inputs.image }}
    - id: parse
      shell: bash
      run: |
        CRITICAL=$(jq '[.Results[].Vulnerabilities[]? | select(.Severity=="CRITICAL")] | length' trivy.json)
        echo "critical=$CRITICAL" >> $GITHUB_OUTPUT
    - shell: bash
      run: |
        trivy image --severity ${{ inputs.severity-fail }} --exit-code 1 ${{ inputs.image }}

Reusable Workflow: A Real Example

Reusable workflows shine for "an entire job we want every repo to run." Here is a reusable workflow we deploy as the standard release job:

# .github/workflows/release.yml in opsio/.github (org-default repo)
name: standard-release
on:
  workflow_call:
    inputs:
      service-name:
        type: string
        required: true
      registry:
        type: string
        default: ghcr.io
    secrets:
      DEPLOY_TOKEN:
        required: true
    outputs:
      image-tag:
        value: ${{ jobs.build.outputs.tag }}

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write
    outputs:
      tag: ${{ steps.tag.outputs.value }}
    steps:
      - uses: actions/checkout@v4
      - id: tag
        run: echo "value=v$(date +%Y.%m.%d)-${GITHUB_SHA::7}" >> $GITHUB_OUTPUT
      - uses: docker/login-action@v3
        with:
          registry: ${{ inputs.registry }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - run: docker build -t ${{ inputs.registry }}/${{ inputs.service-name }}:${{ steps.tag.outputs.value }} .
      - run: docker push ${{ inputs.registry }}/${{ inputs.service-name }}:${{ steps.tag.outputs.value }}

Calling repos invoke this workflow with a one-line job:

jobs:
  release:
    uses: opsio/.github/.github/workflows/release.yml@v1
    with:
      service-name: api
    secrets:
      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

The reusable workflow runs as a separate job on a separate runner. Its permissions are scoped explicitly. Secrets are passed in by name (not secrets: inherit, which is the convenience option that defeats the security boundary). Outputs flow back to the calling workflow, which can chain them into downstream jobs.

Versioning: SHA Pinning, Tags, or Branches?

Three options exist for versioning a reusable workflow or composite action. They have meaningfully different stability and supply-chain trade-offs:

• Branch reference (e.g., @main) — every call gets the latest main. Easy to roll out changes; impossible to roll back individual repos; supply-chain risk if the producing repo's main is compromised
• Tag reference (e.g., @v1) — calls get the latest commit pointed at by the v1 tag. Tags are mutable on GitHub; a compromised producer can repoint a tag to a malicious commit
• SHA reference (e.g., @a81bbbf6...) — pins to an immutable commit. Strongest supply-chain stance; harder to keep up to date without Dependabot

The right answer for cross-org reuse is SHA pinning with Dependabot configured for github-actions. The right answer for in-org reuse where you control the producing repo is a major-version tag (@v1) with a strict release process: any change to v1 goes through PR review on the producing repo. Branch references should be used only for in-development workflows.

The Org-Default Pattern: opsio/.github Repository

GitHub respects a special repository per organisation called .github. Workflow files placed at OWNER/.github/.github/workflows/ are addressable from any repo in the org. This is the canonical home for org-wide reusable workflows. We typically structure it as:

opsio/.github/
├── .github/
│   ├── workflows/
│   │   ├── release.yml         # standard release pipeline
│   │   ├── security-gate.yml   # standard SAST/SCA/container scan
│   │   ├── go-ci.yml           # standard Go CI
│   │   └── node-ci.yml         # standard Node CI
│   └── actions/
│       ├── security-scan/      # composite action
│       └── notify-slack/       # composite action
└── README.md

This shape gives 100-line product workflows in every repo that are mostly uses: calls into the org-default repo. Standards changes happen once, reviewed once, and propagate by version-tag bump in calling repos (or by Dependabot PR if you are SHA-pinning).

The Failure Modes We See in Customer Audits

Three failure patterns surface in customer audits of mature reusable-workflow estates:

1. Reusable workflow used as composite action — a 5-step "lint and test" sequence implemented as a reusable workflow. Each call spins up a fresh runner, re-clones the repo, re-installs dependencies. Pipeline minutes inflate by 3-5x
2. secrets: inherit everywhere — every reusable workflow inherits all caller secrets. The blast radius of a compromised reusable workflow is the union of every caller's secrets. Pass secrets explicitly
3. Branch references in production — workflows pinned to @main on a producing repo where any contributor can merge. A compromised commit on main propagates to every caller within minutes

How Opsio Helps

Opsio's managed github actions typically include reusable-workflow library design as a core deliverable. Engagements run 8-12 weeks for organisations with 100-500 repositories: discovery and standard-extraction, library design, security-and-versioning policy, rollout to a pilot cohort, and migration of the long tail. Customers running broader DevOps platforms pair this work with our devops consulting delivery, and customers consolidating CI estates from multiple tools onto GitHub Actions use our pipeline services delivery service for the cross-tool migration.