Reusable Workflows & Composite Actions
DRY your CI — define a workflow once and call it from any repository or multiple workflows
Skills taught: cicd.workflow-call, cicd.reusable-workflow, cicd.composite-actions, cicd.shared-ci
The problem: copy-pasted workflows
When you have 5 repositories that all deploy Node.js APIs, you end up with the same 80-line workflow file copy-pasted 5 times. When you need to update the Node.js version or add a new security step, you have to update all 5 files. Reusable workflows solve this: define the workflow once in a shared repository, call it from every other repo. Update in one place, applied everywhere.
Defining a reusable workflow
name: Shared Deploy Workflow
# workflow_call makes this workflow callable by other workflows
on:
workflow_call:
# Inputs the caller provides
inputs:
environment:
required: true
type: string
description: 'Deployment target (staging | production)'
image_tag:
required: true
type: string
node_version:
required: false
type: string
default: '20'
# Secrets the caller must pass through
# They are never exposed — just forwarded
secrets:
DEPLOY_TOKEN:
required: true
DATABASE_URL:
required: false
# Outputs the caller can use
outputs:
deployment_url:
description: 'The deployed application URL'
value: ${{ jobs.deploy.outputs.url }}
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ inputs.environment }}
outputs:
url: ${{ steps.deploy.outputs.url }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node_version }}
cache: 'npm'
- run: npm ci
- run: npm test
- name: Deploy
id: deploy
env:
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
ENVIRONMENT: ${{ inputs.environment }}
IMAGE_TAG: ${{ inputs.image_tag }}
run: |
URL=$(./scripts/deploy.sh $ENVIRONMENT $IMAGE_TAG)
echo "url=$URL" >> $GITHUB_OUTPUT
Calling the reusable workflow
name: Deploy
он:
push:
branches: [main]
jobs:
deploy-staging:
uses: myorg/shared-workflows/.github/workflows/shared-deploy.yml@main
# ↑ org/repo/path@ref — can be a branch, tag, or SHA
with:
environment: staging
image_tag: ${{ github.sha }}
node_version: '22'
secrets:
DEPLOY_TOKEN: ${{ secrets.STAGING_DEPLOY_TOKEN }}
deploy-production:
needs: deploy-staging
uses: myorg/shared-workflows/.github/workflows/shared-deploy.yml@main
with:
environment: production
image_tag: ${{ github.sha }}
secrets:
DEPLOY_TOKEN: ${{ secrets.PROD_DEPLOY_TOKEN }}
DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}
notify:
needs: deploy-production
runs-on: ubuntu-latest
steps:
- run: |
echo "Deployed to: ${{ needs.deploy-production.outputs.deployment_url }}"
Composite actions — reusable steps
# A composite action bundles multiple steps into one reusable action
# Useful for the 'checkout + setup-node + npm ci' boilerplate
name: Setup Project
description: Checkout, setup Node.js, and install dependencies
inputs:
node-version:
description: 'Node.js version'
default: '20'
runs:
using: composite
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
cache: 'npm'
- name: Install dependencies
shell: bash
run: npm ci
---
# Using the composite action in any workflow:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: ./.github/actions/setup-project
with:
node-version: '22'
# Now directly run build/test — setup is handled
- run: npm run build
Tip: Reusable workflows run as separate jobs; composite actions run as steps within a job. Use reusable workflows when you want an independent, isolated execution with its own environment and permissions. Use composite actions when you want to group steps within a job — they share the runner environment, can access files created by previous steps, and don't add job overhead.
Frequently Asked Questions
Can a reusable workflow call another reusable workflow?
Yes — reusable workflows can be nested up to 4 levels deep. You can have a 'deploy' workflow that calls a 'build' workflow and a 'notify' workflow. However, each level adds job overhead. For simple step reuse, composite actions are lighter. Use nested workflow_call for genuinely independent, multi-job phases.