GitHub Actions YAML Workflow Basics: A Practical Guide

Learn the core structure of GitHub Actions YAML workflows, from triggers and jobs to reusable steps, conditions, and deployment-safe patterns for CI/CD teams.

If you have ever opened a workflow file and felt like it looked simple but still hard to reason about, this is the practical baseline.

I will walk through what each part of a workflow does, how to structure jobs safely, and how to wire real runtime updates into the same file.

What a Workflow File Looks Like

Workflow files live in .github/workflows/ and use .yml or .yaml.

1
name: Backend CI
2
3
on:
4
  push:
5
    branches: [main]
6
7
jobs:
8
  test:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v4
12
      - run: npm ci && npm test

The structure is always the same:

name: human-readable workflow name in the GitHub Actions UI.
on: trigger rules.
jobs: units of work that run on isolated runners.
steps: ordered commands/actions inside each job.

Core YAML Blocks You Should Know

1
jobs:
2
  deploy:
3
    runs-on: ubuntu-latest
4
    env:
5
      NODE_ENV: production
6
    steps:
7
      - uses: actions/checkout@v4
8
      - uses: actions/setup-node@v4
9
        with:
10
          node-version:node-version:node-version: 22
11
          cache: npm
12
      - name: Build
13
        run: |
14
          npm ci
15
          npm run build

What each field gives you:

runs-on: the runner image.
uses: a reusable action from GitHub Marketplace or your repo.
run: shell commands.
with: action inputs.
env: shared environment variables for a job or step.

Expressions, Secrets, and Step Outputs

You can stitch steps together with expressions and outputs.

1
- name: Start live activity
2
  id: start_activity
3
  uses: ActivitySmithHQ/activitysmith-github-action@v1
4
  with:
5
    action: start_live_activity
6
    api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
7
    payload: |
8
      content_state:
9
        title: "Release Pipeline"
10
        subtitle: "build"
11
        number_of_steps: 3
12
        current_step: 1
13
        type: "segmented_progress"
14
        color: "yellow"
15
16
- name: Update live activity
17
  uses: ActivitySmithHQ/activitysmith-github-action@v1
18
  with:
19
    action: update_live_activity
20
    api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
21
    live-activity-id: ${{ steps.start_activity.outputs.live_activity_id }}
22
    payload: |
23
      content_state:
24
        title: "Release Pipeline"
25
        subtitle: "deploy"
26
        current_step: 2

Three rules:

Store credentials in secrets, not plain YAML.
Give important steps an id when you need outputs later.
Use steps.<id>.outputs.<name> for wiring state across steps.

What You Can Automate in One Workflow

1
on:
2
  push:
3
    branches: [main]
4
  pull_request:
5
    branches: [main]
6
  workflow_dispatch:
7
    inputs:
8
      environment:
9
        description: "Where to deploy"
10
        required: true
11
        default: "staging"
12
  schedule:
13
    - cron: "0 * * * *"

With this, one file can cover:

CI checks for pull requests.
Production deploys from main.
Manual run buttons for recovery/release tasks.
Hourly jobs (health checks, report generation, cleanup).

Control Execution With `needs` and `if`

Before looking at the full workflow, these two controls are the ones most teams miss:

needs sets job order, so deploy waits for test.
if gates a job or step behind explicit conditions.
success() and failure() let you split success/failure paths clearly.

1
jobs:
2
  test:
3
    runs-on: ubuntu-latest
4
    steps:
5
      - run: npm test
6
7
  deploy:
8
    runs-on: ubuntu-latest
9
    needs: test
10
    if: ${{ github.ref == 'refs/heads/main' && success() }}
11
    steps:
12
      - run: ./deploy.sh
13
14
      - name: Notify on failure
15
        if: ${{ failure() }}
16
        run: ./notify-failure.sh

Practical End-to-End Example

This example runs tests, deploys on main, streams progress updates, and sends a failure push.

1
name: API CI and Deploy
2
3
on:
4
  push:
5
    branches: [main]
6
  pull_request:
7
    branches: [main]
8
  workflow_dispatch:
9
10
jobs:
11
  test:
12
    runs-on: ubuntu-latest
13
    strategy:
14
      matrix:
15
        node: [20, 22]
16
    steps:
17
      - uses: actions/checkout@v4
18
      - uses: actions/setup-node@v4
19
        with:
20
          node-version:node-version:node-version: ${{ matrix.node }}
21
          cache: npm
22
      - run: npm ci
23
      - run: npm test
24
25
  deploy:
26
    runs-on: ubuntu-latest
27
    needs: test
28
    if: ${{ github.ref == 'refs/heads/main' }}
29
    steps:
30
      - uses: actions/checkout@v4
31
      - uses: actions/setup-node@v4
32
        with:
33
          node-version:node-version:node-version: 22
34
          cache: npm
35
36
      - name: Start live activity
37
        id: start_activity
38
        continue-on-error: true
39
        uses: ActivitySmithHQ/activitysmith-github-action@v1
40
        with:
41
          action: start_live_activity
42
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
43
          payload: |
44
            content_state:
45
              title: "API Deploy"
46
              subtitle: "build"
47
              number_of_steps: 3
48
              current_step: 1
49
              type: "segmented_progress"
50
              color: "yellow"
51
52
      - name: Build
53
        run: |
54
          npm ci
55
          npm run build
56
57
      - name: Update live activity
58
        if: ${{ steps.start_activity.outputs.live_activity_id != '' }}
59
        continue-on-error: true
60
        uses: ActivitySmithHQ/activitysmith-github-action@v1
61
        with:
62
          action: update_live_activity
63
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
64
          live-activity-id: ${{ steps.start_activity.outputs.live_activity_id }}
65
          payload: |
66
            content_state:
67
              title: "API Deploy"
68
              subtitle: "release switch and reload"
69
              current_step: 2
70
71
      - name: Deploy
72
        run: |
73
          # release directory prep
74
          # artifact upload
75
          # dependency install
76
          # symlink switch
77
          # process reload
78
79
      - name: End live activity
80
        if: ${{ steps.start_activity.outputs.live_activity_id != '' }}
81
        continue-on-error: true
82
        uses: ActivitySmithHQ/activitysmith-github-action@v1
83
        with:
84
          action: end_live_activity
85
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
86
          live-activity-id: ${{ steps.start_activity.outputs.live_activity_id }}
87
          payload: |
88
            content_state:
89
              title: "API Deploy"
90
              subtitle: "done"
91
              current_step: 3
92
93
      - name: Send failed deployment push notification
94
        if: ${{ failure() }}
95
        uses: ActivitySmithHQ/activitysmith-github-action@v1
96
        with:
97
          action: send_push_notification
98
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
99
          payload: |
100
            title: "Deploy Failed"
101
            message: "Main branch deploy failed. Open GitHub Actions run for details."

Common Mistakes to Avoid

Missing id on a step that needs outputs later.
Forgetting needs and running deploy in parallel with tests.
Hardcoding environment values that should come from secrets or inputs.
Skipping if: ${{ failure() }} branches and losing fast failure visibility.

Final Notes

If you remember only few things, make it these:

Keep workflow files small and explicit so intent is obvious during incidents.
Treat secrets and step outputs as first-class building blocks.
Add failure paths (if: ${{ failure() }}) so breakages are visible immediately.

Start with a single CI workflow, then expand to deploy and scheduled jobs once the basics are stable.