Blog

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.

I am a huge fan of dogfooding. If I build developer tooling, I want to use it in my own day-to-day workflows, deployments, and release checks in production.

Deployments are one of the biggest ways I use ActivitySmith: push to main, a GitHub Actions workflow runs in the background, and I get step-by-step progress updates on my iPhone lock screen using iOS Live Activities.

The Problem I Kept Running Into

My deployments are automated with GitHub Actions and are fairly simple, but they still have multiple steps and usually take at least a minute. In larger projects and teams, deployment runs often take much longer.

Before ActivitySmith, that meant opening GitHub, finding the repo, going to Actions, opening the current run, and watching it progress until it finished so I knew when I could try it out.

That workflow was annoying. With ActivitySmith, the progress streams directly to my iPhone lock screen in real time, and I know exactly when a release is finished and ready to try.

ActivitySmith deployment Live Activity on iPhone showing a completed API deployment

What ActivitySmith Does in My Deployments

For every production deployment, ActivitySmith:

Starts a Live Activity at the beginning of the workflow.
Updates each phase of deployment progress in real time.
Ends the activity when production is fully switched.

This is not limited to one backend service. I use the same pattern across various backend services, frontend apps, landing pages, and other projects.

My GitHub Actions Workflow

Here is the workflow I use in production:

1
name: Deploy API to Production
2
3
on:
4
  push:
5
    branches: [main]
6
7
jobs:
8
  deploy:
9
    runs-on: ubuntu-latest
10
    steps:
11
      - uses: actions/checkout@v3
12
      - uses: actions/setup-node@v4
13
        with:
14
          node-version:node-version:node-version: 24
15
          cache: npm
16
17
      - name: Start live activity
18
        id: start_activity
19
        continue-on-error: true
20
        uses: ActivitySmithHQ/activitysmith-github-action@v1
21
        with:
22
          action: start_live_activity
23
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
24
          payload: |
25
            content_state:
26
              title: "API Deployment"
27
              subtitle: "ci: install & build"
28
              number_of_steps: 4
29
              current_step: 1
30
              type: "segmented_progress"
31
              color: "yellow"
32
33
      - name: Build
34
        run: |
35
          npm ci
36
          npm run build
37
38
      - name: Update live activity
39
        if: ${{ steps.start_activity.outputs.live_activity_id != '' }}
40
        continue-on-error: true
41
        uses: ActivitySmithHQ/activitysmith-github-action@v1
42
        with:
43
          action: update_live_activity
44
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
45
          live-activity-id: ${{ steps.start_activity.outputs.live_activity_id }}
46
          payload: |
47
            content_state:
48
              title: "ActivitySmith API Deployment"
49
              subtitle: "prepare release & upload"
50
              current_step: 2
51
52
      - name: Set release id
53
        run: |
54
          echo "RELEASE_ID=$(date +%Y%m%d%H%M%S)" >> $GITHUB_ENV
55
56
      - name: Prepare release dir on remote server
57
        run: |
58
          ssh -o StrictHostKeyChecking=no [email protected] "RELEASE_ID=${RELEASE_ID} bash -s" << 'EOF'
59
            set -euo pipefail
60
            BASE="/srv/apps/activitysmith-api"
61
            NEW="$BASE/releases/$RELEASE_ID"
62
            mkdir -p "$BASE/releases"
63
            rm -rf "$NEW"
64
            mkdir -p "$NEW"
65
          EOF
66
67
      - name: Upload built artifacts to remote server
68
        run: |
69
          # rsync release artifacts to the new server release directory
70
71
      - name: Update live activity
72
        if: ${{ steps.start_activity.outputs.live_activity_id != '' }}
73
        continue-on-error: true
74
        uses: ActivitySmithHQ/activitysmith-github-action@v1
75
        with:
76
          action: update_live_activity
77
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
78
          live-activity-id: ${{ steps.start_activity.outputs.live_activity_id }}
79
          payload: |
80
            content_state:
81
              title: "ActivitySmith API Deployment"
82
              subtitle: "prod install & reload"
83
              current_step: 3
84
85
      - name: Install prod deps, switch release, and reload
86
        run: |
87
          # Remote deployment script:
88
          # - Install production dependencies in the new release directory
89
          # - Atomically switch current symlink to the new release
90
          # - Gracefully reload PM2 cluster behind nginx
91
          # - Prune old releases while keeping rollback-safe history
92
93
      - name: End live activity
94
        if: ${{ steps.start_activity.outputs.live_activity_id != '' }}
95
        continue-on-error: true
96
        uses: ActivitySmithHQ/activitysmith-github-action@v1
97
        with:
98
          action: end_live_activity
99
          api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
100
          live-activity-id: ${{ steps.start_activity.outputs.live_activity_id }}
101
          payload: |
102
            content_state:
103
              title: "ActivitySmith API Deployment"
104
              subtitle: "done"
105
              current_step: 4

Push Notification

ActivitySmith push notification on iPhone showing deployment status

You can also use ActivitySmith to send push notifications to your iOS devices.

1
- name: Send deployment complete push notification
2
  uses: ActivitySmithHQ/activitysmith-github-action@v1
3
  with:
4
    action: send_push_notification
5
    api-key: ${{ secrets.ACTIVITYSMITH_API_KEY }}
6
    payload: |
7
      title: "Build Failed 🚨"
8
      message: "CI pipeline failed on main branch"

Why Zero Downtime Is Non-Negotiable

ActivitySmith is API infrastructure. Users expect near-constant availability.

Before I implemented zero-downtime deployments, the Live Activity lifecycle would break during release restarts because the API went down mid-deploy, so updates could not be delivered.

Deployments now run behind nginx with PM2 in cluster mode using zero-downtime reloads (worker A, then worker B), so traffic stays up and Live Activity updates continue reliably.

More Than One Project

This pattern now powers every deployment workflow I care about, not just ActivitySmith core services. Once wired in, every release gives real-time confidence without babysitting logs.

And outside GitHub Actions, the same approach works from scripts, cron jobs, workers, agents and more. Basically any backend. Zapier and n8n integrations are complete and currently pending marketplace approval.

Try It on Your Next Deployment

Read Documentation: activitysmith.com/docs
SDKs: activitysmith.com/docs/sdks/overview
GitHub Action: ActivitySmith GitHub Marketplace Action

GitHub Actions YAML Workflow Basics: A Practical Guide

What a Workflow File Looks Like

Core YAML Blocks You Should Know

Expressions, Secrets, and Step Outputs

What You Can Automate in One Workflow

Control Execution With `needs` and `if`

Practical End-to-End Example

Common Mistakes to Avoid

Final Notes

How I Use ActivitySmith While Deploying ActivitySmith

The Problem I Kept Running Into

What ActivitySmith Does in My Deployments

My GitHub Actions Workflow

Push Notification

Why Zero Downtime Is Non-Negotiable

More Than One Project

Try It on Your Next Deployment

Blog

GitHub Actions YAML Workflow Basics: A Practical Guide

What a Workflow File Looks Like

Core YAML Blocks You Should Know

Expressions, Secrets, and Step Outputs

What You Can Automate in One Workflow

Control Execution With needs and if

Practical End-to-End Example

Common Mistakes to Avoid

Final Notes

How I Use ActivitySmith While Deploying ActivitySmith

The Problem I Kept Running Into

What ActivitySmith Does in My Deployments

My GitHub Actions Workflow

Push Notification

Why Zero Downtime Is Non-Negotiable

More Than One Project

Try It on Your Next Deployment

Control Execution With `needs` and `if`