Skip to content

Team Automation with GitHub Actions

Why I run selected, recurring checks as workflows – and how you can tell whether the automation actually takes load off the team.

≈ 10 min readSoftwareArchitecture

Team Automation with GitHub Actions

A file under .github/workflows is not a build script and not a better Makefile. It is a rule with teeth: something that applies on every push and every pull request without anyone having to remind people. The difference sounds academic, but it decides what such a file can actually do in a team’s everyday work.

It becomes visible in the questions that end up there. Is code merged before the tests are green? Is the code formatted? Does the change have a changelog entry? Who may trigger a release? As long as the answers live in the head of an experienced person, in a wiki or in a PR comment you have already written three times, they hold – but only as long as everyone is awake and present. They break on the day someone new joins, someone is on vacation or it is simply late.

In the repository, on the other hand, the rule sits next to the code, in the same history, and is applied instead of negotiated. That is exactly where its value lies, and exactly where the interesting architecture questions begin.

Automation as an executable agreement#

The first mistake is to sell automation as a time saver. It does save time, but that is the smaller effect. The bigger one is that a decision stops being negotiable. If “we only merge with green tests” is a convention, it holds until the pressure rises. If the same rule is a required check on the branch, it holds even when nobody is looking. The rule moves from the social space to the technical space, and there it is robust against fatigue and hierarchy.

This shifts my design question. I do not ask “which steps can I automate” but “which decision do I want to make reliable.” That is an architecture decision, not a scripting exercise. A good workflow encodes an intent: this class of errors should never reach the main branch. Nobody should do this follow-up work by hand anymore. This step should be traceable, even in half a year.

Where the line runs#

Before I write a line of YAML, I draw a line that many pipelines do not draw cleanly: the one between checking and changing. A gate only reads. It says yes or no and touches nothing – lint, tests, typecheck, format check. A changing step intervenes: it publishes an artifact, tags a release, deploys, comments, labels. These two classes have completely different requirements for permissions, repeatability and failure behavior, and if you mix them in the same job, the harmless test step suddenly inherits the permissions of the dangerous deploy step.

Check steps therefore run on every pull request, including those from forks, and get no secrets. Changing steps run only on trusted triggers – a merge to the main branch, a tag, a deliberately triggered run. This separation carries the security architecture of the entire repository. GitHub takes care of part of it: for a pull request from a fork, the GITHUB_TOKEN is read-only and secrets are not visible. That is the answer to a real attack scenario, and I build my workflows so that they respect this boundary instead of working around it.

A concrete gate#

This is what a pull request gate looks like that I set up in this form again and again. It checks and changes nothing:

name: pr-gate

on:
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node-version: [12.x, 14.x]
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm test -- --ci

A few decisions in it are deliberate and carry more meaning than they appear to. npm ci instead of npm install, because I want reproducible installs from the lockfile and no creeping drift of dependencies. The matrix over two Node versions, because “works on my machine” is the most common lie in teams and I would rather move compatibility from the laptop into the pipeline. fail-fast: false, because on a red run I want to see both versions, not just the first one that aborts – an aborted report costs a whole round of feedback.

But the real lever is not the YAML. It is the branch protection rule that makes this check mandatory. Only that turns a friendly recommendation into a boundary that the main branch defends. The workflow provides the signal; the protection rule gives it teeth.

The expensive mistake is the happy path#

The happy path is quickly built: everything green, artifact built, release out. It gets interesting exactly where things do not go well, and that is where it is decided whether the automation is a tool or a new source of errors.

The first stumbling block is idempotency. A changing step must be built so that a second run does no harm. Runs get repeated – after a network error, via the re-run button, because someone sets the same tag again. If my publish step creates a duplicate artifact the second time or aborts with a hard error, I have not abolished the manual follow-up work, only moved it. That is why I build such steps so that they check whether the version already exists and then cleanly do nothing.

The second stumbling block is the fork. A pull request from outside should be checked, but not rewarded with trust. There is pull_request_target, which runs with the permissions of the target repository and has access to secrets – intended for harmless tasks such as labeling or commenting on a PR. If you use it to check out and run foreign code from the fork, you open the door to exactly the secrets you wanted to protect. That is why, in my setups, pull_request_target only runs code from the target branch and never the content of the PR. This puts the separation of checking and trust exactly where it really hurts.

The third stumbling block is the flaky test. A check that turns red at random is worse than no check, because it teaches the team to ignore the red cross. The moment “just run it again” becomes a habit, the value of the gate is gone. For me, an unstable test is not a side issue but a defect in the boundary itself – it should be fixed or isolated, not tolerated.

The path from checking to changing#

The picture behind it is simple, and I deliberately draw it as a flow, because the direction carries the whole message:

flowchart LR
  PR[Pull Request] --> Gate{Gate<br/>lint, test, types}
  Gate -- red --> Stop[Merge blocked]
  Gate -- green --> Merge[Merge to main]
  Merge --> Trusted[Trusted run]
  Release --> Audit[Traceable in the history]
  Trusted --> Release[Tag, Publish, Deploy]

On the left, things are only read; on the right, changes happen only after the merge. Between the two lies the trust boundary. Almost all of the security and operations questions that come up in real projects can be traced back to whether a step sits on the right side of this line.

The deliberate trigger#

Not every changing step should fire automatically. For a release, I often want a human involved, but without someone typing commands locally that nobody else sees. That is exactly what I use workflow_dispatch for – a trigger that you deliberately press a button for, with a small input form:

name: release

on:
  workflow_dispatch:
    inputs:
      level:
        description: "semver bump level"
        required: true
        default: patch

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: 14.x
      - run: npm ci
      - run: npm run build
      - run: node ./scripts/release.js --level "${{ github.event.inputs.level }}"
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

This is the manual decision as a form instead of a verbal agreement. The actual logic deliberately lives in release.js, a tested script that the workflow merely calls – the secret is limited to this one trusted path and never shows up in the check gate. The gain lies in traceability: every release appears with its trigger, time and person in the same history as the code. A process that used to vanish into a terminal becomes an entry you can still read half a year later.

What it measurably delivers#

I do not like automation that only feels good. The benefit should show in three places; otherwise I have traded effort for a gut feeling.

The first is the lead time of a pull request. If the gate already answers the usual review questions – is it formatted, do the tests pass, is the typecheck clean – before a human looks at it, the time from “PR open” to “merged” shrinks noticeably. The review can focus on what a machine cannot see: whether the solution is the right one.

The second is the friction in the review itself. Discussions about formatting and style are expensive, not because they take long, but because they poison the tone. A machine that decides formatting questions takes them out of the interpersonal level. Nobody argues with a linter anymore.

The third is the time until a new person’s first meaningful contribution. If the team’s rules are in the repository and become visible with the first PR, nobody has to pass them on verbally. Onboarding turns from an obligation of experienced colleagues into a property of the project. For me, this is the most underrated effect: automation is also a form of documentation that never goes stale, because it is executed.

When I deliberately do not do it#

A tool is not an architecture, and GitHub Actions is no exception. There are cases where I advise against it. If an automation would be real orchestration across many systems with state, restart points and long run times, a workflow runner is the wrong home – that belongs in a proper job runner or a platform built for it, not in a CI file. And if a rule is still in flux because the team itself does not know whether it is right, I do not cement it in a required check. Automation is good at enforcing settled decisions and bad at replacing unsettled ones.

The most expensive mistake is letting the runner grow into a secret deployment platform until critical processes live in a YAML file nobody understands anymore. A workflow that fills a page is a win. A workflow that fills three screens and catches special cases with if conditions is usually a program in the wrong place – then the logic belongs in a tested script or a small CLI that the workflow merely calls.

How I get started#

In practice, I do not turn this into a big initiative. I start with exactly one gate that removes a real, recurring friction – usually tests plus a format check on every PR – and make it mandatory via branch protection. Then I wait two weeks and see whether it takes load off the team or just annoys it. Only when it holds does the next step come along, and the first changing step deliberately comes later than the first checking one.

The yardstick stays the same as for any architecture: a decision is only good once I can describe its failure path. What happens on a re-run? What if the PR comes from a fork? What if a test becomes flaky? Who notices when the gate fails silently? When I can answer these questions, convenience has turned into a piece of reliable team infrastructure. That a machine takes work off your hands along the way is the pleasant Side Effect. The point is the decision that finally holds.

Revised and translated from German with the help of AI.