GitHub Actions Tutorial — First Workflow

2 minute read

Your First Workflow

Let’s create a GitHub Actions workflow from scratch. In under 5 minutes, you’ll have an automated pipeline that runs every time you push code.

Prerequisites

  • A GitHub account (free tier is fine)
  • A GitHub repository (new or existing)
  • Git installed on your local machine

Step 1 — Create the Workflow File

GitHub Actions looks for workflow files in a specific directory: .github/workflows/. Create this directory structure in your repository:

mkdir -p .github/workflows

Create a file called hello.yml:

touch .github/workflows/hello.yml

Step 2 — Write the Workflow

Open .github/workflows/hello.yml and add this content:


name: Hello World

on:
  push:
    branches: [main]

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Say Hello
        run: echo "Hello from GitHub Actions!"

      - name: Show Date
        run: date

      - name: Show Runner Info
        run: |
          echo "Runner OS: $RUNNER_OS"
          echo "Runner Arch: $RUNNER_ARCH"
          echo "GitHub Repo: $GITHUB_REPOSITORY"

Let’s break down what each line does:

Line Purpose
name: Hello World Display name in the Actions tab
on: push: branches: [main] Trigger when code is pushed to main
jobs: Container for all jobs
greet: Job ID (you choose the name)
runs-on: ubuntu-latest Use a GitHub-hosted Ubuntu runner
steps: List of sequential tasks
- name: Say Hello Human-readable step name
run: echo "..." Shell command to execute
run: \| Multi-line shell command

Step 3 — Push and Trigger

Commit and push:

git add .github/workflows/hello.yml
git commit -m "Add first GitHub Actions workflow"
git push origin main

Step 4 — View the Results

  1. Go to your repository on GitHub
  2. Click the Actions tab
  3. You’ll see “Hello World” workflow
  4. Click on the latest run to see the details
  5. Click on the “greet” job to see step-by-step output

Expected output for “Say Hello” step:

Hello from GitHub Actions!

Expected output for “Show Runner Info” step:

Runner OS: Linux
Runner Arch: X64
GitHub Repo: your-username/your-repo

What Just Happened?

┌──────────────────────────────────────────┐
│          You pushed to main              │
│                  │                        │
│                  ▼                        │
│     GitHub detected .github/workflows/   │
│          hello.yml                        │
│                  │                        │
│                  ▼                        │
│   GitHub spun up an Ubuntu VM (runner)   │
│                  │                        │
│                  ▼                        │
│      Executed 3 steps sequentially       │
│      1. echo "Hello..."                 │
│      2. date                             │
│      3. echo runner info                 │
│                  │                        │
│                  ▼                        │
│      Results displayed in Actions tab    │
└──────────────────────────────────────────┘

Common Mistakes

Mistake Fix
Workflow doesn’t trigger Check that the file is in .github/workflows/ (not github/workflows/ or .github/workflow/)
YAML syntax error Validate with a YAML linter; indentation must use spaces, not tabs
Wrong branch name Ensure branches: [main] matches your default branch (might be master)
File not committed The workflow file must be committed and pushed to the branch it targets

Quick Reference

Concept Value
Workflow directory .github/workflows/
File extension .yml or .yaml
Minimum workflow name + on + jobs + runs-on + steps
View results Repository → Actions tab
Default runner ubuntu-latest

← Back to: Chapter 2: Getting Started

Next: Workflow Structure →

Updated:

You may also enjoy