GitHub Actions: Advanced Patterns & Reuse

A reusable workflow is a full workflow file that can be called as a job from another workflow. It runs in its own runner environment, with its own job context — but it shares the same repository secrets (if the caller passes them) and can return outputs back to the caller.

This is the right tool for sharing complete, multi-step job sequences across repos — like a standard deploy pipeline, a security scan, or a release process.

The reusable workflow (callee)

The caller

A composite action packages a sequence of steps (not jobs) into a reusable unit that runs inside the caller's job. Use composite actions to DRY up repeated step sequences across workflows in the same repo — or publish them as public actions for wider use.

The key difference from reusable workflows: composite actions run in the caller's job on the caller's runner. They share the same workspace, env vars, and job context. Reusable workflows get their own isolated runner.

Creating a composite action

Using the composite action

JavaScript actions run directly on the runner (no container startup cost) and have full access to the GitHub API via @actions/github. Use them when your logic is too complex for shell, or when you need to interact with GitHub's API as part of the action itself.

Project structure

Bundling with ncc (recommended)

Bundling with ncc produces a single dist/index.js with all dependencies inlined. Consumers don't need to run npm install — and you don't commit node_modules/ (which can be hundreds of MB).

Key @actions/core methods

Docker actions run inside a container you define. Use them when your action needs a specific runtime environment, system-level dependencies, or a language other than JavaScript/TypeScript.

JS action vs Docker action — when to use each

A matrix spawns multiple job instances from a single job definition. Each combination of matrix values gets its own runner, running in parallel by default.

include — add extra variables to specific combinations

exclude — remove specific combinations from the grid

Using matrix values in if: for conditional steps

Sometimes the matrix isn't known until runtime — which services changed, which test suites exist, which versions to test. Generate the matrix in a prior job and pass it to the test job via fromJSON.

The output of compute-matrix is a JSON string like {"service":["payments","auth"]}. fromJSON() parses it back into an object that the matrix: key can use.

Dynamic matrix from a JSON file in the repo

Concurrency groups prevent redundant runs — when a new run starts, any in-progress run in the same group is cancelled or queued depending on configuration.

Workflow-level concurrency (most common)

Per-PR concurrency (cancel previous run for the same PR)

Job-level concurrency (more granular)

The GITHUB_TOKEN is an automatically-generated short-lived token scoped to the current repository. Its default permissions depend on your org/repo settings — and the principle of least privilege says you should always declare exactly what you need.

Setting permissions

Permission scopes reference

The traditional approach to cloud auth in Actions is storing a long-lived cloud credential (AWS access key, GCP service account JSON) as a GitHub secret. This creates a credential that lives forever, can be exfiltrated, and needs manual rotation.

OIDC (OpenID Connect) eliminates stored credentials entirely. GitHub issues a short-lived JWT for each workflow run; your cloud provider is configured to trust GitHub as an identity provider and exchange the JWT for a temporary cloud credential. No secrets to store, no rotation needed.

Setup: AWS (OIDC + IAM Role)

Step 1 — create the OIDC identity provider in AWS:

Step 2 — create an IAM role with a trust policy:

Step 3 — use it in your workflow:

GCP (Workload Identity Federation)

Azure (Federated Credentials)

Persistent self-hosted runners accumulate state between jobs (environment variables, tool installs, left-over files from previous builds) which causes subtle, hard-to-reproduce failures. The solution is ephemeral runners — each job gets a fresh runner that is destroyed after completion.

Actions Runner Controller (ARC)

ARC is a Kubernetes operator that manages ephemeral self-hosted runners. It watches the GitHub Actions queue and scales runner pods up and down dynamically — zero runners when idle, one per queued job when busy.

Quick ARC setup (Helm)

Security model for self-hosted runners

Parallelism checklist

• Split independent jobs. Unit tests and lint don't need each other — run them as separate parallel jobs, not sequential steps in one job.
• Use a matrix for parallel test sharding. Split a large test suite across N runners: matrix: shard: [1,2,3,4] with --shard=${{ matrix.shard }}/4 in your test runner command.
• Cache aggressively. Dependency install should be a cache restore, not a network download, on 95%+ of runs.
• Use actions/setup-* built-in caches. They handle lock-file hashing correctly by default (Phase 5.10).

Skipping redundant jobs

Reducing checkout overhead in monorepos

Typical CI time budget

When you write uses: actions/checkout@v4, GitHub fetches that action at the v4 tag at run time. If the action maintainer moves the v4 tag to a new commit (maliciously or accidentally), your workflow silently runs different code. SHA pinning eliminates this risk.

Finding the SHA for a tag

Keeping SHA-pinned actions updated with Dependabot

Dependabot opens PRs that update the SHA to the latest release. You review the diff (or auto-merge patches), merge, and your workflow uses the new SHA. You get the security of pinning with the convenience of automated updates.