How to Create a GitHub Action (and Why It Matters)

Why this guide matters

A lot of designers and solo builders hear “GitHub Actions” and assume it is an advanced developer topic.

But in practice, GitHub Actions are one of the simplest ways to automate repetitive work around design systems, token publishing, docs generation, testing, deployments, and AI-assisted workflows.

If you already use GitHub, Actions give you a way to say:

When this happens, automatically do this

That is the real value. Instead of manually running the same commands every time, GitHub runs them for you.

---

What a GitHub Action actually is

A GitHub Action is an automation that runs inside your repository.

It can trigger when:

• code is pushed
• a pull request is opened
• a file changes
• a schedule runs
• you click a button manually

And it can do things like:

• run tests
• build your site
• export tokens
• deploy your app
• generate docs
• post comments on PRs

Think of it as a repeatable workflow attached to your repo.

---

Why designers should care

GitHub Actions become useful the moment you want to reduce repeated setup or human error.

Examples:

• run a design token build every time tokens change
• check if generated code passes linting before a developer reviews it
• deploy your docs site automatically when you update content
• generate component documentation when files are modified
• run visual tests on pull requests

This matters because the best automation is not flashy. It quietly removes friction.

---

The basic idea

Every GitHub Action is defined in a file inside:

.github/workflows/

For example:

.github/workflows/build-docs.yml

That file tells GitHub when to run, what machine to use, and what steps to execute.

---

The anatomy of a workflow

Here is a minimal workflow:

name: Build Site

on:
  push:
    branches: [main]

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

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm install

      - name: Build site
        run: npm run build

What each part means

name: The label you see in the GitHub Actions tab.

on: The trigger. Common values: push, pull_request, schedule, workflow_dispatch.

jobs: The main tasks that run. A workflow can have multiple jobs running in parallel.

runs-on: The machine and environment GitHub should use. ubuntu-latest is the default and usually all you need.

steps: The sequence of actions and commands. Usually: check out the code, set up Node, install dependencies, run your command.

---

Example 1: Run tests on every pull request

This is one of the best first actions because it prevents broken code from being merged quietly.

name: Run Tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm test

Why this matters:

• catches issues earlier
• gives you confidence before merging
• reduces review friction

---

Example 2: Build design tokens automatically

Especially useful for design system work. If your tokens live in GitHub and you build them with Style Dictionary, you can automate that build.

name: Build Tokens

on:
  push:
    paths:
      - 'tokens/**'
      - 'style-dictionary.config.js'
      - 'package.json'
      - 'package-lock.json'

jobs:
  build-tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build:tokens

Why this matters:

• tokens are always built consistently
• no one has to remember the command manually
• easier to connect design changes to code outputs

---

Example 3: Deploy a site automatically

If you maintain a docs site, guide site, or design system site, this is a great workflow.

name: Deploy Site

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - name: Deploy
        run: echo "Add your deploy command here"

In real use, the final step often calls a hosting provider command or official deploy action (Vercel, Netlify, Cloudflare Pages).

Why this matters:

• publish updates faster
• reduce manual deployment mistakes
• make content publishing more repeatable

---

Example 4: Manual workflow for one-off tasks

Not every workflow should run automatically. Sometimes you want a button in GitHub that says “generate docs” or “export tokens”.

Use workflow_dispatch for that.

name: Generate Docs

on:
  workflow_dispatch:

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run docs:generate

Why this matters:

• keeps useful scripts available to non-technical teammates
• avoids needing terminal access for every recurring task
• great for content and documentation workflows

---

Step by step: how to create your first one

Step 1: Choose one small automation

Best beginner choices: run tests, build your site, build tokens, run linting.

Step 2: Create the folder and file

.github/workflows/your-workflow-name.yml

Step 3: Start with a simple template

Copy one of the examples above. Change the name and the build command.

Step 4: Push it to GitHub

Commit the YAML file and push to your branch.

Step 5: Open the Actions tab in GitHub

That is where you will see whether it ran, whether it failed, which step failed, and the logs.

---

How to debug when it fails

Most first-time failures come from:

• the wrong Node version
• the wrong command
• missing dependencies
• environment variables not being available
• a script that works locally but assumes something GitHub does not have

The best way to debug:

1. Copy the exact command from the workflow.
2. Run it locally first.
3. Compare local assumptions with the GitHub logs.

---

Common things people forget

actions/checkout

If you do not check out the repo, the workflow cannot see your files. Every workflow that touches your code needs this as its first step.

Using npm ci instead of npm install

For CI workflows, npm ci is usually better because it is more predictable. It installs exactly what is in the lockfile and fails fast if something is off.

Triggers that are too broad

If your workflow runs on every tiny change, it becomes noisy and expensive. Use paths filters when relevant.

Secrets

If you need API keys or deploy tokens, store them in GitHub Settings → Secrets. Do not hardcode them in the workflow file.

---

Good first use cases for designers

These are especially useful for designers or design system teams:

• run a design token build when token files change
• publish a docs site when guides are updated
• run visual tests on pull requests
• generate docs or changelogs
• validate JSON, YAML, or token files
• run accessibility or linting checks before merge

---

A practical designer example

If you run a guide site and want every main push to rebuild it, a GitHub Action can automate the build check.

If you maintain tokens and transform them into CSS, a GitHub Action can automate the token pipeline.

If you use AI to help generate docs or component specs, a manual action lets you rerun generation without setting up the environment from scratch every time.

---

A useful mindset

Do not start with an advanced pipeline.

Start with:

What is the one thing I keep doing manually that GitHub could do for me?

That question usually gives you the right first action.

---

Checklist: you are done when

---

What Actions are really good for

GitHub Actions are best when:

• the task is repeated often
• the steps are clear
• humans keep forgetting to do it
• consistency matters

They are not magical. They are just reliable automation. That is what makes them valuable.

Exercise

Create and run your first GitHub Action end to end

40 min

1. Pick one repeated command and wrap it in a workflow file

   Choose the simplest command you already run: npm test, npm run build, or a token build. In any GitHub repo you own, create .github/workflows/first-action.yml. Paste the minimal workflow template from this guide. Replace the build command in the final step with your real one. Keep the trigger as pull_request on main.

   • The file is saved at the correct path: .github/workflows/first-action.yml
   • The command in the last step is one you already run manually
   • The YAML has name, on, and jobs blocks and is valid YAML

2. Open a PR and read the Actions logs

   Commit the workflow on a branch, push it, and open a pull request. Open the Actions tab in GitHub. Watch the run. If it fails, click into the failing step, read the log, and fix the cause locally. Push again. Iterate until it turns green.

   • The Action runs on the PR, not silently skipped
   • You can point at the exact log line where each step started
   • A passing run shows a green check next to every step, and you know which command each line mapped to