Lesson 112 gave you a GitHub Actions workflow in one repo. This lesson is about writing the deploy once and using it everywhere. A reusable workflow is a workflow other workflows call. A composite action is a bundle of steps other jobs use. By the end you have built both, and eight repos can call the same deploy without copying it.
Difficulty: Advanced · Know this first: Lesson 112 — GitHub Actions
Every hop charges rent in milliseconds. The bar below is a worked example for this lesson's scenario — not a measurement from a live system — but the shape is honest: on a cache hit the trip is almost free, on a miss the kitchen eats the budget. Step through the lesson or switch the scenario and watch the bar change.
Extra diagram · from scratch to master
Start with one copied deploy. Add one box at a time until eight repos call one workflow and the steps live in one composite action.
The budget bar above shows three fixed stories. This simulator lets you write your own. Move a slider and watch the call, the composite steps, and the runs change in the budget bar, in the hop timings, and in the total. The numbers are a teaching example, not live measurements. The shape is the lesson: sharing multiplies the value of one fix, and it multiplies the blast radius of one mistake.
How many repos call the same reusable workflow. Every repo adds its own run. The workflow is written once. The runs are paid once per repo.
How many steps the composite action holds. Each step costs about a minute, in every repo that runs it.
How many inputs each caller passes. More inputs means more ways for a caller to pass the wrong value, and more the composite action must check.
Try this: (1) Set repos to 12, steps to 10, inputs to 5. The call is about 12 min, the composite about 15 min, the runs about 24 min, and the total is about 57 min. (2) Set all three to the worst end: 20 repos, 20 steps, 10 inputs. The call is 20 min, the composite is 30 min, the runs are 40 min, and the total is about 96 min. Same workflow. Only the inputs changed.
Three questions. No score is saved anywhere — this is just you against the material.
Here is a caller workflow that calls a reusable workflow. Change it, then run the check. The check looks for the three things a working caller needs: a uses line that calls the shared workflow, a with block that passes inputs, and a secrets block that passes the token.
Try breaking it on purpose: delete the secrets block, or move the token into the with block. Run the check and watch it fail. Then press Reset and try a change that keeps it passing, like adding a second input.
Expected output when it passes: The caller uses the shared workflow, passes inputs with a with block, passes the token with a secrets block, and pins the version. This workflow would run the shared deploy.
I take the same deploy four times here. First I learn the call. Then I learn inputs and secrets. Then I learn versions. Last I run it for the world.
Definition: A reusable workflow is a workflow file with on workflow_call. Another workflow calls it with a uses line that names the repo, the file, and the version. The caller passes inputs with a with block and secrets with a secrets block. The called workflow runs in the caller's context.
Types:
Uses: I use this when two repos have the same deploy job and I am tired of fixing the same bug twice. I move the jobs into the shared repo, call them from both repos, and fix them once. Try it now: write a caller for the reusable workflow in the Try it box, and run the check.
Dimensions: At low traffic everything is nearly free. What breaks first is the unpinned version: a workflow change lands in your repo on the next push, and you did not ask for it. It costs one version tag to pin it. It costs a broken deploy when you skip it.
Definition: A composite action is a file called action.yml that holds a list of steps. A job uses it with one uses line. Inputs are declared with types and defaults, and the action reads them as inputs dot name. Outputs let one step pass a value to the next step. A composite action can call other actions, including the standard checkout action.
Types:
Uses: I use a composite action when several jobs share the same steps, like setting up a tool and running a linter. I use a reusable workflow when several repos share the same jobs. I use outputs when a step computes a value the next step needs. Try it now: add a second step to the composite action in your head, and name what it would do.
Dimensions: As the steps grow, the action grows, and the failure gets harder to find. What breaks is the composite step that fails without saying which line failed. It costs a name on every step and a log line at the start of each one.
Definition: A shared workflow is a library, so it gets versions. Tags mark releases. A major version bump warns every caller that the change can break them. Starter workflows give every new repo a caller file on day one. Policies limit which actions a repo may use, so a repo cannot call an action the org has not approved.
Types:
Uses: I use tags so no repo is forced onto a breaking change. I use starter workflows so a new repo gets the shared deploy without copying it. I use policies so a repo cannot call an action nobody reviewed. Lesson 137 builds the policies and the scale on top of this.
Dimensions: At ten times the callers, the version is the lesson. What breaks is the workflow change that eight repos did not expect. It costs a test workflow and a changelog. The trade is that sharing is powerful and unforgiving in the same breath.
The input that was never validated. A reusable workflow takes inputs from its callers, and a caller can pass anything. An environment name with a typo deploys to a place that does not exist, or worse, to a place that does. I validate inputs at the top of the reusable workflow, and I fail fast when they are wrong.
Do this: call a reusable workflow with an environment name that does not exist, and read the failure. Expected: the failure is late, in the deploy step, and it names the cloud, not the input. Add a validation job that checks the input against the allowed list, call it again, and expect the failure to name the input.
jobs:
validate:
runs-on: ubuntu-latest
steps:
- name: Check the environment input
run: |
case "${{ inputs.environment }}" in
staging|production) ;;
*) echo "Unknown environment: ${{ inputs.environment }}" && exit 1 ;;
esac
What the snippet means: the validation job runs first and checks the input against the two allowed values. A bad input fails in seconds, in the workflow, instead of minutes later in the cloud.
Secrets do not flow downhill by default. A caller cannot pass a secret to a reusable workflow by accident, and a reusable workflow cannot read the caller's secrets unless the caller hands them over. That is the design. The mistake is working around it by putting the secret in an input, where it shows up in the log.
Do this: try to pass a secret as a workflow input and run the workflow. Expected: the workflow fails or the value is empty, because inputs are not secrets. Pass it properly with the secrets block from the snippet, run again, and expect the deploy to succeed with the secret masked in the log.
jobs:
call-deploy:
uses: my-org/shared-workflows/.github/workflows/deploy.yml@v1.2.0
with:
environment: production
secrets:
deploy-token: ${{ secrets.DEPLOY_TOKEN }}
What the snippet means: secrets travel in the secrets block, never in inputs. The caller owns the secret, the reusable workflow borrows it, and the log masks it.
Definition: At this level the shared workflows repo is a platform with owners, versions, tests, and a deprecation policy. Old versions get a sunset date. Breaking changes ship with a migration guide. A dashboard shows which repos pin which version, so a bad version can be found in one look. And I rehearse the worst day: the shared repo is down, and no caller can fetch it.
Types:
Uses: I use this when more than one team ships through the same workflows, or when a bad workflow can take down services other teams depend on. It is also how I review a setup I did not build: I ask where the shared workflows live, who can change them, and what happens when they are gone. Try it now: pick one shared workflow you own and write its sunset date. If it has none, it has no owner.
Dimensions: At a hundred times the callers, the shared repo is not the bottleneck, the blast radius is. What breaks is the single workflow that everything depends on, or the version nobody can find. It costs real operational work: owners, tests, dashboards, and drills.
The shared repo is down. Every caller fetches the reusable workflow from the shared repo. When that repo is down, no caller can fetch it, and no deploy runs. I rehearse that day with a test caller pointed at a mirror, so the first outage is not the first test.
Do this: point a test caller at a workflow path that does not exist and run it. Expected: the run fails before any job starts, with an error that names the missing workflow. That is the blast radius. The fallback is a mirror of the shared repo, and the drill is changing the uses line to the mirror and watching the run pass.
uses: my-org/shared-workflows-mirror/.github/workflows/deploy.yml@v1.2.0
What the snippet means: the uses line is the only thing that changes in the fallback. A mirror that nobody has called from is not a fallback, it is a hope.
The breaking change, and the callers it breaks. A major version of a reusable workflow breaks its callers on purpose. The question is which callers, and the answer is a search, not a meeting. I search every repo for the uses line and list the pinned versions before I ship the major version.
Do this: search your repos for the shared workflow path with the command in the snippet. Expected: a list of callers and the version each one pins. The callers on the old major version are the migration list, and the dashboard is that list, kept current.
grep -r "shared-workflows/.github/workflows" --include="*.yml" .github/ | sort
What the snippet means: the grep is the version dashboard. Every uses line names the version its caller loads, and the list shows which callers a breaking change reaches.
Read the flags: grep -r --include and sort
A shared workflow is found by searching for the repos that call it. The search is the list of callers, and the list is the blast radius of any change to the shared file.
grep -r: The -r flag searches files under a directory. Without it, grep would stop at the directory and search nothing."shared-workflows/.github/workflows": This is the text to find. Every caller workflow has this path in its uses line, and the path names the shared workflow it calls.--include="*.yml": This limits the search to .yml files. Without it, grep would search every file, and the list would include docs that only mention the path..github/ (the directory): This is where the search starts. It is the folder that holds the caller workflows. A search from the repo root would also find the shared workflow itself, which is not a caller.| sort: The pipe hands the matches to sort. Sort orders them, so the same caller groups together and I can count the callers.grep -n (added): The lesson did not show this one yet. It prints the line number with each match. I use it when I need to open the caller file at the uses line and read the inputs it passes.Try it: search the .github folder for the shared-workflows path. Expect one line per caller. Change one input in the shared workflow and expect every caller on the list to be affected.
Start with the reusable workflow, then the caller. The reusable workflow below takes an environment input and a deploy token secret, and runs three jobs. Do this: save it as .github/workflows/deploy.yml in a repo called shared-workflows, and run python3 -c "import yaml; yaml.safe_load(open('.github/workflows/deploy.yml'))". Expected output: the parse check prints nothing, and the file triggers on workflow_call only.
Read the flags: python3 -c and yaml.safe_load
A workflow file that does not parse fails the whole run. This one-liner parses it before I push, so the failure happens on my machine, not in the pipeline.
python3 -c: The -c flag runs the code string that follows it. Without it, python3 would expect a file name, and the check would need a script file for one line of code.import yaml: This loads the YAML library. The library knows how to read YAML. Without the import, the next call has no name to call.yaml.safe_load(open('.github/workflows/deploy.yml')): Safe_load reads the file and turns it into Python data. Safe means it never runs code from the file, which matters because a workflow file can hold anything. If the YAML is broken, safe_load raises an error and the check fails.json.dumps (added): The lesson did not show this one yet. Wrapping the result in json.dumps prints the parsed file as JSON. I use it when safe_load passes but I want to see the structure it read.Try it: run the python3 -c check on the deploy workflow. Expect silence, which means it parsed. Break one line of indentation and run it again. Expect an error that names the line.
name: deploy
on:
workflow_call:
inputs:
environment:
required: true
type: string
secrets:
deploy-token:
required: true
jobs:
deploy:
runs-on: ubuntu-latest
environment: ${{ inputs.environment }}
steps:
- uses: actions/checkout@v4
- run: make build
shell: bash
- run: make deploy
shell: bash
env:
DEPLOY_TOKEN: ${{ secrets.deploy-token }}
What the snippet means: the workflow only runs when called, it requires an environment input and a deploy token secret, and it runs the build and the deploy with the token as an environment variable, never printed in the log.
The caller is short on purpose. Do this: save the file below as .github/workflows/call-deploy.yml in a scratch repo, validate it the same way, and push it. Expected output: the Actions tab shows a run, and the run shows the deploy job from the shared workflow.
name: call-deploy
on:
push:
branches: [main]
jobs:
call-deploy:
uses: my-org/shared-workflows/.github/workflows/deploy.yml@v1.2.0
with:
environment: production
secrets:
deploy-token: ${{ secrets.DEPLOY_TOKEN }}
What the snippet means: the caller triggers on push to main, calls the shared workflow at version v1.2.0, passes production as the environment, and passes its own deploy token as the secret. Eleven lines, and the repo owns none of the deploy logic.
The composite action is the third file. Do this: save an action.yml with a runs block that uses composite and two steps, build and test, then use it from a job with a uses line pointing at the folder. Expected output: the job log shows both steps running with their names. If the steps do not appear, the path in the uses line is wrong.
At 10x the callers, the shape holds and the numbers grow. At 100x, the design changes: the shared repo gets owners, tests, a version dashboard, and a deprecation policy. The workflow never stops being shared code. It just gets more callers, and more ways to break them. The next lesson in this track does the same job at org scale.
A reusable workflow is a whole workflow. A composite action is smaller: a few steps, packaged, that run inside any job. I use composite actions for the steps every job repeats, like setting up a tool or checking a version, and reusable workflows for the whole deploy.
Do this: save the action file from the snippet, use it from a job with a uses line pointing at the folder, and run the workflow. Expected: the job log shows both steps running with their names. If the steps do not appear, the path in the uses line is wrong, and the error names the path.
name: Setup and test
runs:
using: composite
steps:
- name: Set up the tool
run: make setup
shell: bash
- name: Run the tests
run: make test
shell: bash
What the snippet means: the composite action is a folder with an action file, and the job calls it by path. The steps run inside the caller job, on the caller runner, with the caller's secrets.
A shared workflow change I shipped broke eight repos at once. The callers pinned a branch name, not a tag, so every repo pulled the newest workflow on its next push. I renamed an input in the workflow, and eight callers failed with an input-not-found error within the hour. The workflow did exactly what it was told. Nobody had told it to stay still.
Three things. First, every uses line pins a tag or a commit hash, and a pin to a branch name is treated as broken in review. Second, the shared repo gets a tag and a changelog for every release. Third, a workflow change runs a test caller before it ships. Try it now: open any uses line you own and read what follows the @ sign. If it is a branch name, pin it before the next push.
Build a reusable workflow, a composite action, and a caller that uses both. The reusable workflow must trigger on workflow_call, take an environment input, and deploy. The composite action must hold the build and test steps. The caller must pin the version and pass the secret. It passes when the caller run turns green and the app serves the new code.
Success looks like this: all three files parse with no output from the check. The caller run shows the deploy job from the shared workflow, and the app serves the new code. When you rename the input, the caller fails with an input error, and the version pin is what stops the other callers from breaking.
If the run fails at once with a not-found error, the repo path or the version in the uses line is wrong. If the token appears in the log, it was passed as an input, not as a secret. If the workflow runs on push, its trigger is not workflow_call. If the composite steps do not appear, the action path in the uses line is wrong.