Okay, this is going to sound dumb, but last month I fixed the same bug in eleven repositories. Not eleven bugs. One bug, eleven times. A Node version pin in a CI workflow that I’d copy-pasted across every client project I set up in 2024, and every one of them started failing the week a dependency dropped support for Node 18.<\/p>\n
Eleven pull requests. Eleven “bump node to 22” commits. Eleven times waiting for the green tick. Somewhere around repo seven I stopped and asked myself why I was doing this by hand when GitHub Actions has had reusable workflows since 2021 and I had, apparently, never bothered to learn them properly.<\/p>\n
So this is the post I should have read three years ago. It covers what reusable workflows are, how they differ from composite actions (the two get confused constantly, including by me), the before and after of my own setup, and the handful of gotchas that cost me an afternoon. If you maintain more than three repos with CI, you probably have this problem too, you just haven’t hit the eleven-PR morning yet.<\/p>\n
Here’s roughly what lived in Nothing wrong with it on day one. The rot sets in slowly. One repo gets a fix for flaky caching. Another gets a matrix added because a client needed Node 20 support. A third gets a security tweak after I read something about pinning action versions to SHAs. None of those improvements travel. Six months later I have eleven workflows that are 80% identical and 20% mysteriously different, and I couldn’t tell you which one is the “good” one.<\/p>\n The Node pin was just the symptom that finally hurt enough to notice.<\/p>\n This is where I got stuck the first time, so let me be blunt about the distinction before showing code.<\/p>\n A reusable workflow is an entire workflow, with its own jobs and runners, that another workflow can call as if it were a job. You trigger it with A composite action is a bundle of steps. It runs inside a job that already exists. You can’t define a runner or a matrix in a composite action, because it doesn’t own the job. It’s closer to a function you call from within a step list. The composite action docs<\/a> cover the mechanics.<\/p>\n The rule I use now: if the thing I want to share is “a job” (test this, build this, deploy this), it’s a reusable workflow. If it’s “a few steps that always go together” (set up Node with our cache config, or log in to our registry), it’s a composite action. I ended up needing both, and they nest fine: a reusable workflow can call composite actions.<\/p>\n I got this wrong for two weeks by trying to make one composite action do everything, then wondering why I couldn’t give it a matrix.<\/p>\n I made a repo called And in each of the eleven repos, Eight lines. The next time a Node version dies, I change one file, tag Notice the matrix lives in the shared workflow but the versions come from the caller. That’s the bit composite actions can’t do, and it’s the reason I picked reusable workflows for this layer. The Two things bit me here.<\/p>\n First, secrets don’t flow automatically. The called workflow only sees what you explicitly pass in the Second, On the topic of security, pin the shared workflow reference to something you control. Once the job-level workflow was shared, I noticed the same four setup steps kept appearing in my other workflows too: the deploy workflow, the release workflow, a nightly one. Node setup, cache, Called with One genuine limitation: composite actions can’t use I assumed moving to a shared workflow would make caching “just work” everywhere. It mostly did, with one wrinkle: cache keys are scoped to the repo that runs the workflow, not the repo that defines it. That’s the right behaviour, and it means each of the eleven repos has its own If you’re also shrinking Docker images in CI, the same “measure before you assume” attitude applies. I wrote about that in my post on multi-stage builds and the 1.2 GB image I stopped shipping<\/a>, and about half of that post’s advice is really about what your CI cache is silently doing.<\/p>\n Don’t extract too early. I wrote the copy-paste version of that workflow in maybe fifteen minutes back in 2024 and it served me fine for a year. The shared version took most of a day, including the two weeks of low-level confusion about composite actions that I’m compressing here. Three repos with slightly different CI is fine. Eight is where it starts to hurt. Eleven is where you write a blog post about it.<\/p>\n Also, version the shared repo like a library. Moving I’m still not sure whether I should have just used a monorepo for the client projects and skipped all of this. Probably not; the clients own their repos and want them separate. But I wrote about that tradeoff at length in the Turborepo vs Nx post<\/a>, and the honest answer is that shared CI workflows are the “we have multiple repos and that’s not changing” solution.<\/p>\n Open your most-copied workflow file. Grep your org for its job name. If it appears in more than three repos, make a .github\/workflows\/ci.yml<\/code> in every one of those repos. You’ve written this file. Everyone has.<\/p>\n# Before: the same file, pasted into every repo\nname: CI\non:\n push:\n branches: [main]\n pull_request:\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions\/checkout@v4\n - uses: actions\/setup-node@v4\n with:\n node-version: 18\n cache: npm\n - run: npm ci\n - run: npm run lint\n - run: npm test -- --coverage\n - uses: actions\/upload-artifact@v4\n with:\n name: coverage\n path: coverage\/\n<\/code><\/pre>\nReusable workflows vs composite actions<\/h2>\n
workflow_call<\/code>, and the caller uses uses:<\/code> at the job level. The GitHub docs on reusing workflows<\/a> are decent here, but they bury the important part: the called workflow runs in the context of the caller’s repository, on the caller’s runners, with the caller’s secrets if you pass them.<\/p>\nThe after: one workflow, one line per repo<\/h2>\n
qasim\/workflows<\/code> (public, because reusable workflows in private repos need extra access config and I didn’t want to think about it yet). The shared workflow lives at .github\/workflows\/node-ci.yml<\/code>:<\/p>\n# .github\/workflows\/node-ci.yml in the shared repo\nname: Node CI (reusable)\non:\n workflow_call:\n inputs:\n node-versions:\n description: JSON array of Node versions to test\n type: string\n default: '["22"]'\n run-lint:\n type: boolean\n default: true\n coverage:\n type: boolean\n default: false\n secrets:\n NPM_TOKEN:\n required: false\n\njobs:\n test:\n runs-on: ubuntu-latest\n strategy:\n fail-fast: false\n matrix:\n node: ${{ fromJSON(inputs.node-versions) }}\n steps:\n - uses: actions\/checkout@v4\n - uses: actions\/setup-node@v4\n with:\n node-version: ${{ matrix.node }}\n cache: npm\n - run: npm ci\n env:\n NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}\n - if: ${{ inputs.run-lint }}\n run: npm run lint\n - run: npm test ${{ inputs.coverage && '-- --coverage' || '' }}\n - if: ${{ inputs.coverage }}\n uses: actions\/upload-artifact@v4\n with:\n name: coverage-node${{ matrix.node }}\n path: coverage\/\n<\/code><\/pre>\nci.yml<\/code> became this:<\/p>\n# After: the caller, in every project repo\nname: CI\non:\n push:\n branches: [main]\n pull_request:\n\njobs:\n ci:\n uses: qasim\/workflows\/.github\/workflows\/node-ci.yml@v1\n with:\n node-versions: '["20", "22"]'\n coverage: true\n secrets:\n NPM_TOKEN: ${{ secrets.NPM_TOKEN }}\n<\/code><\/pre>\nv1.1<\/code>, and move the v1<\/code> tag. Every repo picks it up on its next run.<\/p>\nfromJSON<\/code> trick is ugly but it’s the documented way to pass an array through a string input; matrix inputs can’t be typed as arrays directly. Yes, I find that annoying too.<\/p>\nSecrets, permissions, and the
inherit<\/code> shortcut<\/h2>\nsecrets:<\/code> block, unless you write secrets: inherit<\/code>, which hands over everything the caller has access to. I used inherit<\/code> for a day, then changed my mind. It’s convenient, but it means the shared workflow can read every secret in every repo that calls it, and if I ever add a step that echoes environment for debugging (I have, more than once), that’s a bad afternoon. Passing secrets by name costs one extra line per secret and lets me see exactly what crosses the boundary.<\/p>\npermissions<\/code>. If your shared workflow needs to write to the repo (pushing a tag, commenting on a PR), the caller has to grant that. The called workflow can only narrow permissions, never widen them beyond what the caller allowed. GitHub’s secure use guide for Actions<\/a> covers the reasoning, and the short version is: put permissions: contents: read<\/code> at the top of your caller and only open things up per job when you have to.<\/p>\n@v1<\/code> is a moving tag I own, so I’m fine with it. If you’re calling someone else’s reusable workflow, pin to a full commit SHA. Same rule as third-party actions.<\/p>\nComposite actions for the boring steps<\/h2>\n
npm ci<\/code>, registry auth. That’s a composite action.<\/p>\n# action.yml in qasim\/workflows\/setup-node-project\/\nname: Setup Node project\ninputs:\n node-version:\n default: '22'\n npm-token:\n default: ''\nruns:\n using: composite\n steps:\n - uses: actions\/setup-node@v4\n with:\n node-version: ${{ inputs.node-version }}\n cache: npm\n - run: npm ci\n shell: bash\n env:\n NODE_AUTH_TOKEN: ${{ inputs.npm-token }}\n<\/code><\/pre>\nuses: qasim\/workflows\/setup-node-project@v1<\/code>. The shell: bash<\/code> line is required on every run<\/code> step in a composite action, and forgetting it produces an error message that does not mention the word “shell”. You’ve been warned.<\/p>\nsecrets.*<\/code> directly. You pass the secret in as an input from the caller, which is what the npm-token<\/code> input is doing above. It feels slightly wrong to pass a secret as an input, but it’s how the model works, and the value is still masked in logs.<\/p>\nCaching still needs care<\/h2>\n
node_modules<\/code> cache, which is what you want. But the 10 GB per-repo cache limit that GitHub documents in its dependency caching reference<\/a> applies per caller, so a shared workflow that caches aggressively can fill a small repo’s quota faster than you’d expect. I trimmed the coverage artifacts to seven days of retention and stopped caching Playwright browsers in the shared job. Not a big deal, just not free.<\/p>\nWhat I’d tell someone starting today<\/h2>\n
v1<\/code> is fine for backward-compatible fixes. Anything that changes an input name gets v2<\/code>, and the old tag stays around. I learned this the cheap way, by breaking one repo instead of all of them, because one repo happened to still pin @main<\/code>. Don’t pin @main<\/code>.<\/p>\nSomething to do this week<\/h2>\n
workflows<\/code> repo, move that job into a workflow_call<\/code> file with two or three inputs, and replace the copies with an eight-line caller. Tag it v1<\/code>. You’ll spend an hour, and the next time a runtime version dies you’ll fix it once.<\/p>\n