The Kingdom's Actions

GitHub Actions, YAML workflows and automation

What is a GitHub Action?

A GitHub Action is an automated workflow that runs directly on GitHub's servers. You don't need to install anything, configure anything on your machine - GitHub takes care of everything.

The principle is simple: you describe in a file what you want to happen and when you want it to happen. GitHub executes these instructions automatically.

For example:

• On every push, run the tests
• On every pull request, check the code style
• Every night at midnight, generate a report
• When a version is tagged, deploy the application

Key concepts

Before writing your first Action, you need to understand the vocabulary. GitHub Actions uses five fundamental concepts:

Workflow - the instruction scroll

A workflow is a YAML file describing a complete automated process. It is the scroll you write for the Forge. A repository can contain multiple workflows.

Job - the task

A job is a set of steps that run on the same machine. A workflow can contain multiple jobs. By default, jobs run in parallel (at the same time).

Step - the individual action

A step is an individual action inside a job. Each step is either a shell command (run:) or a reusable action (uses:).

Action - the reusable component

An action (with a lowercase "a") is a prefabricated component you can use in your steps. Thousands exist on the GitHub marketplace. The most common is actions/checkout@v4 which retrieves your code.

Runner - the execution machine

A runner is the virtual machine on which your job runs. GitHub offers free runners on Ubuntu, Windows and macOS.

Where to place workflows?

GitHub looks for workflows in a very specific folder:

your-repo/
  .github/
    workflows/
      my-workflow.yml
      another-workflow.yml

The path is always .github/workflows/. If you place your file elsewhere, GitHub will ignore it.

Files must have the .yml or .yaml extension.

YAML basics

GitHub Actions workflows are written in YAML (YAML Ain't Markup Language). It's a data format readable by humans. Here are the essential rules:

Indentation is crucial

In YAML, indentation defines the structure. We use spaces (never tabs!). Each nesting level adds 2 spaces.

# Correct
parent:
  child:
    grandchild: value

# INCORRECT - mixed indentation
parent:
  child:
      grandchild: value   # 6 spaces instead of 4!

Key-value pairs

name: Tests
version: 1.0
active: true

Lists

List items start with a dash followed by a space:

fruits:
  - apple
  - banana
  - cherry

Multi-line text

The | character allows writing text on multiple lines:

script: |
  echo "First line"
  echo "Second line"
  echo "Third line"

Your first workflow

Here is the simplest possible workflow. It runs on every push and displays a message:

name: Tests
on: push
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Tests pass!"

Let's break down each line:

Triggers

The on: keyword defines when the workflow starts. Here are the most common triggers:

On every push

on: push

On every pull request

on: pull_request

On multiple events

on: [push, pull_request]

On specific branches

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

This workflow only triggers for pushes to main or develop, and for pull requests targeting main.

On a schedule (cron)

on:
  schedule:
    - cron: '0 0 * * *'   # Every day at midnight UTC

Manually

on: workflow_dispatch

This trigger adds a "Run workflow" button in the GitHub interface. Very handy for manual deployments.

A more complete workflow

Here is a realistic workflow for a project with tests:

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

      - name: Check style
        run: npm run lint

Multiple jobs and dependencies

By default, jobs run in parallel. To create dependencies between jobs, use the needs: keyword.

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

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm run build

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Deploying..."

In this example:

• test runs first
• build waits for test to finish successfully
• deploy waits for build to finish successfully

If test fails, neither build nor deploy will run. That's exactly the desired behavior - no deployment if tests fail!

A job can also depend on multiple jobs:

  deploy:
    needs: [test, build, lint]

The marketplace - Tools from other Masters

GitHub has a marketplace with thousands of prefabricated actions. Instead of writing everything yourself, you can reuse the work of others.

Some popular actions:

Example with Node.js:

steps:
  - uses: actions/checkout@v4

  - uses: actions/setup-node@v4
    with:
      node-version: '20'

  - run: npm install
  - run: npm test

The with: keyword passes parameters to an action. Here, we request Node.js version 20.

Secrets and environment variables

Some information must never appear in your code: passwords, API keys, access tokens. GitHub lets you store them as secrets.

Using a secret in a workflow

steps:
  - name: Deploy
    run: ./deploy.sh
    env:
      API_KEY: ${{ secrets.API_KEY }}
      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

Secrets are configured in the repository's Settings on GitHub, under "Secrets and variables" > "Actions".

Simple environment variables

For non-sensitive values, you can define environment variables directly:

env:
  NODE_ENV: production
  APP_NAME: my-application

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Application: $APP_NAME"

Variables defined at root level are available in all jobs. You can also define them at the job or step level.

Checking results

When a workflow runs, you can follow its progress in the Actions tab of your GitHub repository.

Logs

Each step produces logs you can view by clicking on it. This is where you'll see error messages if something fails.

Statuses

Each run has a status:

• Green (success): all jobs passed
• Red (failure): at least one job failed
• Yellow (in progress): the workflow is currently running
• Grey (cancelled): the workflow was cancelled

Status badges

You can add a badge to your README that displays the status of the latest workflow:

![CI](https://github.com/USERNAME/REPO/actions/workflows/FILENAME.yml/badge.svg)

This badge updates automatically. Green if tests pass, red otherwise. It's a trust signal for everyone who visits your repository.

Hands-on exercise - Write your first Action

Step 1 - Create the repository

mkdir forge-actions
cd forge-actions
git init -b main

Step 2 - Create the workflow structure

mkdir -p .github/workflows

This is the magic folder that GitHub watches. Any .yml file placed here will be treated as a workflow.

Step 3 - Create a test script

Before writing the workflow, create a small script the workflow can execute:

cat > test.sh << 'EOF'
#!/bin/bash
echo "=== Chronicle verification ==="
echo "Test 1: The README file exists..."
if [ -f "README.md" ]; then
    echo "  SUCCESS"
else
    echo "  FAILURE"
    exit 1
fi
echo "Test 2: The README is not empty..."
if [ -s "README.md" ]; then
    echo "  SUCCESS"
else
    echo "  FAILURE"
    exit 1
fi
echo "=== All tests pass ==="
EOF

chmod +x test.sh

Step 4 - Create the README

cat > README.md << 'EOF'
# Forge Actions

My first repository with GitHub Actions.

![Tests](https://github.com/USERNAME/REPO/actions/workflows/verification.yml/badge.svg)
EOF

Step 5 - Write the workflow

This is the crucial moment. Create the file .github/workflows/verification.yml:

name: Chronicle verification
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - name: Retrieve the code
        uses: actions/checkout@v4

      - name: Make the script executable
        run: chmod +x test.sh

      - name: Run the tests
        run: ./test.sh

Verify the file is correct:

cat .github/workflows/verification.yml

Step 6 - Commit everything

git add .
git commit -m "Add the chronicle verification workflow"

Step 7 - Run the verification

bash verifier.sh

.\verifier.ps1

Concept summary