GitHub Actions Fundamentals

Events, workflows, jobs, steps, actions — understand the core building blocks.

🧒 Simple Explanation (ELI5)

Imagine a giant domino chain. Someone pushes the first domino — that's an event (like pushing code to GitHub). The entire domino path laid out on the table is the workflow. Along the path, dominoes are grouped into sections separated by little bridges — those sections are jobs. Within each section, every single domino that falls is a step — they fall one after another in order.

Now here's the cool part: some of those dominoes aren't just plain tiles. They're fancy pre-built domino gadgets — little machines that spin, launch a ball, or ring a bell before tipping the next domino. Those gadgets are actions. Someone else built them, and you just plug them into your chain. You didn't have to engineer the spinning gadget yourself — you found it in the marketplace (a store full of pre-built gadgets) and dropped it into your path.

The full picture: You push the first domino (event). The chain (workflow) starts falling. Section 1 (Job 1) runs its dominoes one by one (steps). Some are plain tiles (shell commands), some are fancy gadgets (actions). Meanwhile, Section 2 (Job 2) on a separate table starts falling at the same time — jobs run in parallel by default. When all sections finish, the chain is complete and you get your result.

If any domino in a section fails to fall (a step errors out), the rest of that section stops. But the other sections on their separate tables keep going — unless you told them to wait.

🔧 Technical Explanation

Core Concepts Overview

GitHub Actions has six fundamental building blocks. Every workflow you write is composed of these elements:

Events Deep Dive

Events are what trigger your workflow to start. GitHub supports dozens of event types. Here are the most important ones:

push — Fires when commits are pushed to a branch. The most common trigger for CI pipelines.

on:
  push:
    branches: [main, develop]       # Only trigger on these branches
    paths: ['src/**', 'tests/**']   # Only trigger when these files change

pull_request — Fires when a PR is opened, updated (pushed to), or synchronized. Essential for running checks before merge.

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

schedule — Cron-based trigger for running workflows on a schedule. Perfect for nightly builds, weekly reports, or periodic cleanup.

on:
  schedule:
    - cron: '0 2 * * *'   # Every day at 2:00 AM UTC

workflow_dispatch — Adds a "Run workflow" button in the GitHub Actions UI. Allows manual triggering with optional custom inputs.

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'staging'
        type: choice
        options: [staging, production]

repository_dispatch — Triggered by an external system via the GitHub API. Used for integrating third-party tools or cross-repo orchestration.

on:
  repository_dispatch:
    types: [deploy-request]   # Custom event type you define

release — Fires when a release is published, created, or edited. Common trigger for publishing packages or deploying production.

on:
  release:
    types: [published]

Workflows

A workflow is a YAML file stored in the .github/workflows/ directory of your repository. Each file defines one complete automation pipeline. Key rules:

• The filename can be anything ending in .yml or .yaml (e.g., ci.yml, deploy.yml)
• A repository can have multiple workflows — they run independently
• Workflows must have at least one trigger (on:) and at least one job
• Workflows are version-controlled — changes are reviewed in PRs like any other code
• The name: field is optional but strongly recommended — it appears in the Actions UI

Jobs — Parallel by Default

Jobs define what to run and where to run it. Each job gets its own fresh runner (virtual machine). Critical behavior:

• Parallel by default: If you define build and test jobs, they start at the same time on separate runners
• Dependencies with needs: Use the needs keyword to create sequential execution. deploy with needs: [build, test] waits for both to complete
• Isolated environments: Each job starts fresh — no files, no environment variables, no state from other jobs. Use artifacts to share data between jobs.
• Conditionals with if: Jobs can be skipped based on expressions, e.g., if: github.ref == 'refs/heads/main'

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

  test:
    runs-on: ubuntu-latest
    needs: build               # Waits for build to finish first
    steps:
      - uses: actions/checkout@v4
      - run: npm test

  deploy:
    runs-on: ubuntu-latest
    needs: [build, test]       # Waits for BOTH build and test
    if: github.ref == 'refs/heads/main'
    steps:
      - run: echo "Deploying to production..."

Steps — Sequential Within a Job

Steps are the individual tasks within a job. They execute sequentially — step 2 waits for step 1 to finish. Each step is either:

• run: — Execute a shell command directly. This is your own custom code.
• uses: — Execute a pre-built action from the GitHub Marketplace or your own repository.

Steps share the same runner filesystem, so files created in step 1 are available in step 2. They also share environment variables set with $GITHUB_ENV.

Actions — Reusable Building Blocks

Actions are pre-built, reusable units that perform specific tasks. Instead of writing 50 lines of shell commands, you reference an action with one line. The most commonly used actions:

Actions are version-pinned using tags (e.g., @v4) or commit SHAs for maximum security (e.g., @a5ac7e51b41094c92402da3b24376905380afc29).

GitHub Context Objects

GitHub provides context objects accessible in workflow expressions using the ${{ }} syntax. These give you metadata about the event, repository, and runner:

📊 GitHub Actions Architecture

💻 Code Example — Complete Workflow Explained

Here's a complete CI workflow with every single line annotated:

# name: Human-readable name for this workflow.
#   Appears in the Actions tab of your repository.
name: CI Pipeline

# on: Defines which events trigger this workflow.
#   This workflow runs on two events: push and pull_request.
on:
  # push: Triggered when commits are pushed to the repository.
  push:
    # branches: Only trigger on pushes to the 'main' branch.
    #   Pushes to feature branches are ignored.
    branches: [main]

  # pull_request: Triggered when a PR is opened or updated.
  pull_request:
    # branches: Only trigger for PRs targeting the 'main' branch.
    #   PRs targeting other branches are ignored.
    branches: [main]

# jobs: Defines all the jobs in this workflow.
#   Each job runs on its own virtual machine (runner).
jobs:

  # 'build' is the job ID — used by other jobs to reference this one.
  #   You can name it anything: build, ci, lint, etc.
  build:

    # runs-on: Specifies the runner (virtual machine) for this job.
    #   'ubuntu-latest' gives you a fresh Ubuntu VM with common tools
    #   pre-installed (git, node, python, docker, etc.).
    runs-on: ubuntu-latest

    # steps: The sequential list of tasks this job performs.
    #   Each step runs in order. If one fails, the rest are skipped.
    steps:

      # uses: Run a pre-built action from the GitHub Marketplace.
      #   actions/checkout@v4 clones your repository code onto the runner.
      #   Without this, the runner has no access to your code.
      - uses: actions/checkout@v4

      # name: Human-readable label for this step (appears in logs).
      # uses: actions/setup-node@v4 installs Node.js on the runner.
      - name: Setup Node.js
        uses: actions/setup-node@v4
        # with: Passes input parameters to the action.
        #   node-version: '20' installs Node.js version 20.x.
        with:
          node-version: '20'

      # run: Executes a shell command directly on the runner.
      #   'npm ci' installs dependencies from package-lock.json.
      #   It's faster and stricter than 'npm install' — preferred in CI
      #   because it ensures exact versions from the lockfile.
      - run: npm ci

      # run: Another shell command — runs the project's test suite.
      #   If any test fails, this step fails, the job fails,
      #   and the workflow reports failure on the PR.
      - run: npm test

📋 Event Types Reference

Here are the most commonly used GitHub Actions events, when they fire, and when to use each:

⌨️ Hands-on: Build a Multi-Event Workflow

Let's create a workflow that triggers on both push and pull_request, uses the actions/checkout action, and runs a custom step.

Step 1: Create the Workflow File

In your repository, create .github/workflows/fundamentals-lab.yml:

name: Fundamentals Lab

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  explore:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Show GitHub context
        run: |
          echo "Event:      ${{ github.event_name }}"
          echo "Branch:     ${{ github.ref }}"
          echo "Commit SHA: ${{ github.sha }}"
          echo "Actor:      ${{ github.actor }}"
          echo "Repository: ${{ github.repository }}"
          echo "Run ID:     ${{ github.run_id }}"

      - name: List repository files
        run: |
          echo "--- Repository root ---"
          ls -la
          echo ""
          echo "--- Git log (last 3 commits) ---"
          git log --oneline -3

      - name: Custom build step
        run: |
          echo "Building the project..."
          echo "In a real workflow, this would be: npm ci && npm run build"
          echo "Build complete! ✅"

Step 2: Commit and Push

mkdir -p .github/workflows
# paste the YAML above into .github/workflows/fundamentals-lab.yml

git add .github/workflows/fundamentals-lab.yml
git commit -m "ci: add fundamentals lab workflow"
git push origin main

Step 3: View the Workflow Run

Go to your repository on GitHub and click the Actions tab. You'll see "Fundamentals Lab" in the list. Click into the run to see:

• The event that triggered it — "push" in this case
• The job name — "explore"
• Each step's output — expand "Show GitHub context" to see all the context variables printed
• Timing — how long each step took

Step 4: Test the Pull Request Trigger

Create a branch, make a change, and open a PR targeting main. The same workflow will trigger again — but this time github.event_name will show pull_request instead of push. This is how the same workflow adapts to different events.

🐛 Debugging Common Issues

Scenario: "Workflow Never Triggers"

You pushed code but nothing shows up in the Actions tab. Here's the systematic checklist:

• Check the file path: The workflow YAML must be in .github/workflows/ — exactly. Not .github/workflow/ (no "s"), not github/workflows/ (missing dot), not at the repo root. The directory name is case-sensitive on Linux runners.
• Check the branch filter: If your workflow says on: push: branches: [main] but you pushed to feature/my-branch, it won't trigger. Remove the branch filter temporarily to verify: on: [push].
• Check YAML syntax: A single indentation error can silently break the file. Use a YAML linter or the GitHub workflow editor (which has built-in validation). Common mistake: using tabs instead of spaces.
• Check file extension: The file must end in .yml or .yaml. A .txt or no extension won't work.
• Check Actions permissions: Go to Settings → Actions → General. Ensure "Allow all actions and reusable workflows" is selected (or at least "Allow actions created by GitHub").
• Check the branch where the YAML exists: For push events, the workflow file must exist on the branch you're pushing to. If you added the file on main but pushed to develop, and the file doesn't exist on develop, it won't trigger.

Scenario: "Job Shows 'Skipped'"

The workflow triggered but one or more jobs show "Skipped" with a grey icon:

• Check the if: conditional: The job has an if: expression that evaluated to false. For example, if: github.ref == 'refs/heads/main' skips the job on any other branch. Click the skipped job to see the condition that was evaluated.
• Check needs: dependencies: If a job uses needs: build and the build job failed, dependent jobs are skipped by default. To run a job even when dependencies fail, add if: always().
• Check event type: A pull_request event won't have github.ref == 'refs/heads/main' — it has the PR's head ref. Conditions written for push events may not work on pull_request events.
• Check path filters: If your workflow uses on: push: paths: ['src/**'] and you only changed README.md, the workflow may trigger but with all jobs skipped because no relevant files changed.

🎯 Interview Questions

🌍 Real-World Use Case

A platform engineering team at a fintech company uses workflow_dispatch and schedule events to power two critical workflows:

Manual Deployments with workflow_dispatch

Their production deployment workflow uses workflow_dispatch with inputs for the target environment and the image tag. When a release manager is ready to deploy, they go to the Actions tab, select the deploy workflow, choose "production" from the environment dropdown, and paste the Docker image tag. The workflow then:

• Validates the image tag exists in the container registry
• Runs a preflight check against the target cluster (health, capacity)
• Deploys via Helm with the specified image tag
• Runs post-deploy smoke tests
• Sends a Slack notification with the deployment summary

This gives them full control over when deployments happen (no accidental deploys on merge) while keeping the process fully automated and auditable. Every deployment is logged in the Actions tab with who triggered it, what inputs were provided, and the full execution log.

Nightly Builds with schedule

Their scheduled workflow runs every night at 2 AM UTC. It:

• Builds all 8 microservices from the latest main branch
• Runs the full end-to-end test suite (too slow for PR-time CI)
• Scans all dependencies for known vulnerabilities (CVEs)
• Generates a coverage report and publishes it to an internal dashboard
• If any vulnerability is found, opens a GitHub Issue automatically and tags the security team

This combination — manual deploys for safety, nightly builds for thoroughness — gives them confidence that production is stable and that the codebase is continuously validated even when no one is actively committing.

📝 Summary

• Events trigger workflows — push, pull_request, schedule, workflow_dispatch, release, and 30+ more
• Workflows are YAML files in .github/workflows/ that define your automation pipeline
• Jobs run in parallel by default on separate runners — use needs: for sequential execution
• Steps run sequentially within a job — either run: (shell commands) or uses: (pre-built actions)
• Actions are reusable building blocks from the GitHub Marketplace — always pin versions for safety
• Runners are the VMs that execute jobs — GitHub-hosted (ubuntu, windows, macos) or self-hosted
• GitHub Context provides metadata like github.sha, github.ref, github.actor for conditional logic and dynamic values
• If a workflow doesn't trigger, check the file path, branch filter, YAML syntax, and Actions permissions
• If a job is skipped, check the if: conditional and needs: dependencies