GitHub Actions fundamentals

A workflow file is YAML, and YAML has one rule that trips everyone: indentation is meaning. Two spaces in means "this belongs to the line above". Tabs are not allowed. A job is a list of work that runs on one fresh machine; a step is one command or action inside that job, run in order. Read this small file from the top: on a pull request, run one job called check, on Ubuntu, with two steps.

on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: echo "The robot read the repository"

Move runs-on two spaces to the left and it no longer belongs to check; the run fails before it starts. That is the first error most people meet, and now you will recognise it.

Infrastructure code is reviewable, but its checks only help if someone runs them. GitHub Actions lets a repository run defined jobs for events such as a pull request. Put a YAML file in .github/workflows/, give it a trigger, and GitHub starts the job when that event occurs. The run can still fail, wait for approval, or be skipped by repository settings; inspect the result before trusting it.

Workflow

An automated process defined in a YAML file in .github/workflows/, started by an event, made of one or more jobs, each a sequence of steps run on a fresh machine called a runner.

One small, real workflow contains every concept in this class. This is Campux's first — it validates the Bicep from Class Twenty on every pull request:

# .github/workflows/validate.yml
name: Validate infrastructure

on:
  pull_request:
    branches: [ main ]

jobs:
  validate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
      - name: Build Bicep (fails on errors)
        run: az bicep build --file infra/main.bicep

on — the trigger

The event that starts the workflow: a push, a pull_request, a schedule (cron), or workflow_dispatch — a button a human presses.

job

A named unit of work. Multiple jobs run in parallel by default, each on its own machine; needs: chains them in order.

runner

The machine a job runs on. ubuntu-latest is a fresh virtual machine GitHub provides, used once and destroyed.¹

step

One command (run:) or one reusable action (uses:). Steps in a job run in order and share the runner's filesystem.

action

A packaged, reusable step from the marketplace — actions/checkout@v7 clones your repository so later steps can see the code. You will use ten of these before you ever write one.

Read the flow top to bottom: an eligible pull request against main starts a job on a fresh runner; checkout supplies the code and Azure CLI compiles the Bicep. The sample only compiles. It does not run what-if, deploy, or contact an Azure subscription. If this exact job is configured as a required check on the protected branch, a failing result blocks merge. A first-time or forked contribution may need approval before its run starts.

Workflows need to know things about the run they are in — who opened the pull request, which branch, what secret to use. That information arrives through contexts, read with the ${{ … }} expression syntax. You need surprisingly few of them:

# the contexts you will actually use
steps:
  - name: Show the facts of the run
    run: |
      echo "Actor:  ${{ github.actor }}"
      echo "Branch: ${{ github.ref_name }}"
      echo "Event:  ${{ github.event_name }}"

  - name: Deploy — but only from main
    if: github.ref_name == 'main'
    run: ./deploy.sh
  # secrets.NAME and vars.NAME — covered next section

The github context identifies the event, actor, and ref. An if: can condition a step or job; it is not an authorization boundary for a deploy by itself. Pair it with appropriate token permissions, environment rules, and a trusted event. secrets and vars supply configuration, but availability depends on the event and repository settings. For debugging, print only the specific non-sensitive fields you need; dumping an entire context can disclose data.

The moment a workflow does anything real — deploys, publishes, talks to Azure — it needs configuration, and some of that configuration is sensitive. GitHub gives you three containers for it, and choosing the wrong one is a security decision made by accident.

An environment can scope a deployment job and its secrets. A production approval gate works only when required reviewers are configured and supported by the repository's plan and visibility; naming an environment does not create an approval gate. Check the current GitHub plan rules before relying on one. A forked pull request normally receives no repository secrets, while a privileged trigger needs special care with untrusted code. For the validation workflow in this class, use no Azure credentials at all.

Secret masking is a backstop, not permission to print credentials. GitHub says redaction is best effort; a transformed, split, or derived value may escape it.² Pass a secret only to the step that needs it, preferably through an environment variable or standard input. Never print it or interpolate it directly into a shell command.

Workflows accumulate duplication fast: the same steps against three environments, the same validation in four repositories. Actions has two answers. A matrix runs one job definition many times with different inputs, in parallel:

# one job definition, two independent Bicep builds
jobs:
  validate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    strategy:
      matrix:
        template: [ infra/network.bicep, infra/storage.bicep ]
    steps:
      - uses: actions/checkout@v7
      - name: Compile ${{ matrix.template }}
        run: az bicep build --file "${{ matrix.template }}"

This illustrative matrix assumes those two files exist in the repository. Each copy of the job compiles one file without Azure credentials. A reusable workflow uses workflow_call so other workflows can invoke reviewed steps with declared inputs and secrets. Reuse helps when several repositories need the same process; it also makes the shared workflow a dependency whose changes deserve review.

Here is the fact that separates teams that take CI seriously from teams that have incidents about it: the workflow file can read your secrets and deploy to your production. That sentence has an implication — whatever reviews production changes must review this file with the same care. A one-line edit to a workflow can widen a trigger, print a credential, skip a validation step, or point a deploy at the wrong subscription, and it will look like harmless YAML in a diff full of real code.

The pipeline is production code.

Review a workflow diff with four questions. Trigger: did on: change — does anything new start this workflow, and could an outsider's pull request start it? Permissions: what can the job now reach — new secrets, a new environment, a wider token? Steps: is anything echoed, uploaded, or sent somewhere that was not before? Gates: did a needs:, an if:, or an environment protection quietly disappear? Four questions, thirty seconds each — and they catch the class of bug that a thousand green runs never will, because the run only proves the workflow did what it says, not that it says the right thing.