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@v7
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@v7
8
      - uses: actions/setup-node@v7
9
        with:
10
          node-version: 24
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

Use GitHub expressions to give each workflow run and rerun its own stream key. Reuse that key at each milestone instead of passing an activity ID between steps.

1
- name: Start live activity
2
  uses: ActivitySmithHQ/activitysmith-github-action@v1
3
  with:
4
    action: stream_live_activity
5
    api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
6
    stream-key: workflow-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}
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: stream_live_activity
20
    api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
21
    stream-key: workflow-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}
22
    payload: |
23
      content_state:
24
        title: "Release Pipeline"
25
        subtitle: "deploy"
26
        current_step: 2
27
        type: "segmented_progress"
28
        number_of_steps: 3

Three rules:

Store credentials in secrets, not plain YAML.
Reuse the same stream key throughout the job.
Send complete content state at each milestone.

ActivitySmith operations are informative by default. API or payload errors report ok: false and let the workflow continue. Set errors: true only when an ActivitySmith failure should fail the step.

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
concurrency:
11
  group: production-deploy
12
  cancel-in-progress: false
13
14
jobs:
15
  test:
16
    runs-on: ubuntu-latest
17
    strategy:
18
      matrix:
19
        node: [22, 24]
20
    steps:
21
      - uses: actions/checkout@v7
22
      - uses: actions/setup-node@v7
23
        with:
24
          node-version: ${{ matrix.node }}
25
          cache: npm
26
      - run: npm ci
27
      - run: npm test
28
29
  deploy:
30
    runs-on: ubuntu-latest
31
    needs: test
32
    if: ${{ github.ref == 'refs/heads/main' }}
33
    steps:
34
      - uses: actions/checkout@v7
35
      - uses: actions/setup-node@v7
36
        with:
37
          node-version: 24
38
          cache: npm
39
40
      - name: Start live activity
41
        continue-on-error: true
42
        uses: ActivitySmithHQ/activitysmith-github-action@v1
43
        with:
44
          action: stream_live_activity
45
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
46
          stream-key: workflow-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}
47
          payload: |
48
            content_state:
49
              title: "API Deploy"
50
              subtitle: "build"
51
              number_of_steps: 3
52
              current_step: 1
53
              type: "segmented_progress"
54
              color: "yellow"
55
56
      - name: Build
57
        run: |
58
          npm ci
59
          npm run build
60
61
      - name: Update live activity
62
        continue-on-error: true
63
        uses: ActivitySmithHQ/activitysmith-github-action@v1
64
        with:
65
          action: stream_live_activity
66
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
67
          stream-key: workflow-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}
68
          payload: |
69
            content_state:
70
              title: "API Deploy"
71
              subtitle: "release switch and reload"
72
              current_step: 2
73
              type: "segmented_progress"
74
              number_of_steps: 3
75
76
      - name: Deploy
77
        run: |
78
          # release directory prep
79
          # artifact upload
80
          # dependency install
81
          # symlink switch
82
          # process reload
83
84
      - name: End live activity
85
        if: ${{ always() }}
86
        continue-on-error: true
87
        uses: ActivitySmithHQ/activitysmith-github-action@v1
88
        with:
89
          action: end_live_activity_stream
90
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
91
          stream-key: workflow-${{ github.repository_id }}-${{ github.run_id }}-${{ github.run_attempt }}
92
          payload: |
93
            content_state:
94
              title: "${{ job.status == 'success' && 'API Deploy' || 'API Deploy Failed' }}"
95
              subtitle: "${{ job.status == 'success' && 'done' || 'check the workflow run' }}"
96
              current_step: 3
97
              auto_dismiss_seconds: 10
98
              color: "${{ job.status == 'success' && 'green' || 'red' }}"
99
100
      - name: Send failed deployment push notification
101
        if: ${{ failure() }}
102
        uses: ActivitySmithHQ/activitysmith-github-action@v1
103
        with:
104
          action: send_push_notification
105
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
106
          payload: |
107
            title: "Deploy Failed"
108
            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.
Letting production deploy runs overlap instead of using a concurrency group with cancel-in-progress: false.
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 and an always() cleanup step so breakages are visible without leaving stale Live Activities.

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