GitHub Actions: Workflows from Scratch

What is GitHub Actions?

The workflow hierarchy

Workflow (.github/workflows/*.yml)
  └── Jobs (run in parallel by default)
       └── Steps (run sequentially)

Level	What It Represents	Key Property
Workflow	The entire automation definition	on: — which events trigger it
Job	A unit of work on one runner	runs-on: — which runner executes it
Step	A single action or command	uses: (action) or run: (script)

Key difference from Azure Pipelines: GitHub Actions has no “stage” level. Jobs ARE the top-level unit under a workflow. You create stage-like behaviour by grouping jobs with needs: dependencies.

Events — when workflows run

GitHub Actions supports 50+ event types. The exam focuses on the most common:

Code events

Event	Fires When	Common Use
push	Code is pushed to a branch	CI builds, deployments on merge to main
pull_request	PR is opened, updated (synchronize), reopened, or closed	PR validation, code review automation
pull_request_target	Same as pull_request but runs in the BASE branch context	Safe automation on PRs from forks (avoids secret leakage)

Scheduled events

on:
  schedule:
    - cron: '30 5 * * 1-5'

Runs on a UTC cron schedule. Note: GitHub Actions cron can be delayed during high-demand periods — don’t rely on precise timing for time-critical workflows.

Manual and API events

Event	Fires When	Use Case
workflow_dispatch	Manually triggered from the UI or REST API	Ad-hoc deployments, manual test runs
repository_dispatch	External system sends a webhook	Cross-repo triggers, external CI integration

Event filtering

Events support filtering by branch, path, tag, and activity type:

on:
  push:
    branches:
      - main
      - 'release/**'
    paths:
      - 'src/**'
    tags:
      - 'v*'
  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize

The types: filter is unique to GitHub Actions — you can react to specific PR activities (opened, closed, labeled, review_requested) rather than all PR events.

💡 Exam tip: pull_request vs pull_request_target

This is a high-value exam topic:

• pull_request runs the workflow from the HEAD branch (the PR’s source code). Secrets from the base repo are NOT available to PRs from forks — this prevents secret theft.
• pull_request_target runs the workflow from the BASE branch (the target branch). Secrets ARE available, but the code being tested is from the BASE, not the PR. Use this for safe label-based automation on fork PRs.

Security rule: Never use pull_request_target with actions/checkout pointing at the PR head AND passing secrets — this allows a fork PR to inject malicious code that runs with your secrets.

Jobs — parallel by default

Jobs within a workflow run in parallel unless you add needs: to create dependencies:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

  deploy:
    runs-on: ubuntu-latest
    needs: [build, test]
    steps:
      - run: echo "Deploying after build and test succeed"

In this example, build and test run in parallel. deploy waits for both to finish. This is “fan-out / fan-in” execution.

Matrix strategy

A matrix lets you run the same job across multiple configurations (OS, language version, Node version) in parallel:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci && npm test

This creates 9 parallel jobs (3 OS times 3 Node versions). Matrix is powerful for testing cross-platform compatibility.

Key matrix options:

• fail-fast: false — continue all matrix jobs even if one fails (default is true — cancel all on first failure)
• max-parallel: 2 — limit how many matrix jobs run simultaneously
• include: / exclude: — add or remove specific combinations

Steps: actions vs run

Steps execute sequentially within a job:

Actions (uses:)

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: '20'

Actions are reusable units from the GitHub Marketplace or your own repositories. The @v4 pins the major version.

Scripts (run:)

- run: npm ci && npm test
  env:
    NODE_ENV: test

Shell commands executed on the runner. Use shell: bash or shell: pwsh to specify the shell explicitly.

Key built-in actions

Action	Purpose
actions/checkout@v4	Check out repository code onto the runner
actions/setup-node@v4	Install a specific Node.js version
actions/setup-dotnet@v4	Install a specific .NET SDK version
actions/setup-java@v4	Install a specific JDK version
actions/setup-python@v5	Install a specific Python version
actions/cache@v4	Cache dependencies (node_modules, .nuget) between runs
actions/upload-artifact@v4	Upload build artefacts for later jobs or downloads
actions/download-artifact@v4	Download artefacts from previous jobs

Environments with protection rules

GitHub Actions environments provide deployment targets with governance:

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - run: echo "Deploy to staging"

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment: production
    steps:
      - run: echo "Deploy to production"

Environment protection rules:

• Required reviewers — pause the workflow until specified people approve
• Wait timer — delay deployment by N minutes (cool-down period)
• Deployment branches — restrict which branches can deploy (e.g., only main to production)
• Custom protection rules — call external APIs for approval decisions

Environments also store secrets and variables scoped to that environment — production secrets are only available to jobs targeting the production environment.

Azure Pipelines vs GitHub Actions — side by side

Both platforms support YAML CI/CD — Azure Pipelines has stages and richer templates; GitHub Actions has a larger marketplace and more event types

Concept	Azure Pipelines	GitHub Actions
Definition file	azure-pipelines.yml (root of repo)	.github/workflows/*.yml (multiple files supported)
Hierarchy	Pipeline > Stages > Jobs > Steps	Workflow > Jobs > Steps (no stage concept)
CI trigger	trigger: keyword with branch/path filters	on: push with branch/path/tag filters
PR trigger	pr: keyword (Azure Repos) or branch policies (GitHub)	on: pull_request with branch/type filters
Scheduled trigger	schedules: with cron and branch filters	on: schedule with cron expression
Manual trigger	Pipeline can always be queued manually, or use trigger: none	on: workflow_dispatch with optional input parameters
Job parallelism	Jobs within a stage run in parallel by default	Jobs within a workflow run in parallel by default
Dependencies	dependsOn: keyword at stage or job level	needs: keyword at job level
Matrix	strategy: matrix on jobs	strategy: matrix on jobs (similar syntax)
Reusable templates	YAML templates (extends, include) for stages, jobs, steps	Reusable workflows (workflow_call), composite actions
Environments	environment: keyword on deployment jobs, with checks and approvals	environment: keyword on jobs, with protection rules (reviewers, timers, branch restrictions)
Marketplace	Azure DevOps Marketplace (tasks and extensions)	GitHub Marketplace (20,000+ actions)

💡 Scenario: Kai builds the Launchpad Labs CI workflow

🚀 Kai Tanaka at Launchpad Labs sets up CI for their Next.js SaaS app. The team is GitHub-first, so Actions is the natural choice.

The workflow:

1. Trigger — on: push to main and on: pull_request to main
2. Matrix — test on Node 20 and 22, on Ubuntu and Windows (4 combinations)
3. Steps — checkout, setup-node with caching, npm ci, lint, test with coverage, build
4. Artefact upload — the build output is uploaded with actions/upload-artifact
5. Deploy job — needs: [test], targets the staging environment with required reviewer (Sam, CTO), deploys to Kubernetes

Riku (frontend) asks: “Why does the matrix run 4 jobs? We only deploy on Ubuntu.” Kai explains: “The matrix validates cross-platform compatibility. The deploy job runs once, after all matrix jobs pass — needs: creates the dependency.”

Zoe (QA) adds a comment: “Can I run E2E tests only on PRs to main?” Kai adds a separate job with if: github.event_name == 'pull_request' to conditionally run Playwright tests.

Question

What is the GitHub Actions YAML hierarchy?

Click or press Enter to reveal answer

Answer

Workflow contains Jobs. Jobs contain Steps. There is no 'stage' concept — jobs are the top-level unit. Jobs run in parallel by default; use 'needs:' for sequential dependencies. Steps within a job run sequentially. Workflows are stored in .github/workflows/ directory.

Click to flip back

Question

What is the difference between 'pull_request' and 'pull_request_target' events?

Click or press Enter to reveal answer

Answer

pull_request runs the workflow code from the PR's HEAD branch. Secrets are not available on fork PRs (security). pull_request_target runs the workflow code from the BASE branch (target). Secrets are available. Use pull_request_target for safe automation on fork PRs — but never checkout the PR head code when secrets are in scope.

Click to flip back

Question

What does 'fail-fast: false' do in a GitHub Actions matrix strategy?

Click or press Enter to reveal answer

Answer

By default (fail-fast: true), if any matrix job fails, all other running matrix jobs are cancelled. Setting fail-fast: false lets all matrix jobs complete even if one fails. Use this when you want to see the full picture of which platform/version combinations pass and which fail.

Click to flip back

Question

What are GitHub Actions environment protection rules?

Click or press Enter to reveal answer

Answer

Rules that govern deployments to an environment: 1) Required reviewers — human approval before deployment. 2) Wait timer — delay by N minutes. 3) Deployment branch rules — restrict which branches can deploy. 4) Custom protection rules — external API approval. Environments also scope secrets and variables.

Click to flip back

Question

How does workflow_dispatch differ from repository_dispatch in GitHub Actions?

Click or press Enter to reveal answer

Answer

workflow_dispatch allows manual triggering from the GitHub UI or REST API — you can define input parameters users fill in. repository_dispatch is triggered by external systems sending a webhook event to the GitHub API. Use workflow_dispatch for human-initiated runs; repository_dispatch for cross-repo or external system triggers.

Click to flip back

Knowledge check

Knowledge Check

Kai defines a workflow with three jobs: lint, test, and deploy. Lint and test have no 'needs:' keyword. Deploy has 'needs: [lint, test]'. What is the execution order?

Alint runs first, then test, then deploy — all sequentialBlint and test run in parallel; deploy runs after both succeedCAll three jobs run in parallelDdeploy runs first, then lint and test in parallel

Check Answer

Knowledge Check

A workflow uses on: pull_request to run CI checks. An external contributor forks the repo and opens a PR. The workflow needs a secret (API_KEY) to run integration tests. What happens?

AThe workflow runs and the secret is available — fork PRs have full accessBThe workflow runs but the secret is NOT available — fork PRs cannot access repo secretsCThe workflow does not run at all — fork PRs cannot trigger workflowsDThe workflow runs with the secret only if a maintainer approves first

Check Answer

Knowledge Check

Nadia wants to migrate a three-stage Azure Pipeline (Build > Test > Deploy) to GitHub Actions. Azure Pipelines has stages — GitHub Actions does not. How should she model the three stages?

ACreate three separate workflow files — one for build, one for test, one for deployBUse three jobs with 'needs:' dependencies — build job, test job (needs: build), deploy job (needs: test)CUse a single job with all steps in sequence — build steps, then test steps, then deploy stepsDGitHub Actions cannot model multi-stage pipelines — continue using Azure Pipelines

Check Answer

🎬 Video coming soon

Next up: Pipeline Agents — choose between hosted and self-hosted agents, design agent infrastructure, and handle hybrid and air-gapped environments.