GitHub Actions First Workflow

A first workflow turns theory into a working result. In about ten minutes, you can watch GitHub start a machine, run your commands, and show the output. The steps below need only a GitHub account and an empty repository.

What You Will Build

The workflow prints a greeting, shows the current date, and lists the files in your repository. The task is small, and it teaches the full path from file to result.

+-----------+     +------------------+     +--------------+     +-----------+
| You push  | --> | GitHub reads the | --> | A runner     | --> | Logs show |
| a commit  |     | workflow file    |     | executes it  |     | the result|
+-----------+     +------------------+     +--------------+     +-----------+

Create the Folder and File

GitHub looks for workflow files in one exact location. The folder path must match the spelling shown here.

your-repository/
  .github/
    workflows/
      hello.yml

Open your repository on GitHub, choose Add file, then Create new file. Type .github/workflows/hello.yml in the name box. GitHub creates each folder as you type the slashes.

Paste the Workflow

name: Hello Workflow

on:
  push:
    branches: [ main ]
  workflow_dispatch:

jobs:
  greet:
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Say hello
        run: echo "Hello from GitHub Actions"

      - name: Show date
        run: date

      - name: List files
        run: ls -la

Line-by-Line Meaning

The Name

The name line sets the title that appears in the Actions tab.

The Trigger

The on block starts the workflow on every push to the main branch. The workflow_dispatch line adds a manual Run workflow button.

The Job

The job named greet runs on a fresh Ubuntu machine that GitHub provides and deletes after the job ends.

The Steps

The checkout step copies your repository onto the machine. Without it, the machine has no files. The three run steps execute ordinary shell commands in the order written.

Commit and Watch It Run

Commit the file directly to the main branch. The commit itself fires the push trigger. Open the Actions tab and look for the run called Hello Workflow. A yellow circle means running, a green check means success, and a red cross means failure.

Click the run, click the job named greet, and expand each step. The log under Say hello shows your greeting exactly as typed.

Run It by Hand

Select Hello Workflow in the left sidebar of the Actions tab. The Run workflow button appears on the right because of the workflow_dispatch line. Manual runs help when you want to test without making a new commit.

Break It on Purpose

Change one command to exit 1 and commit again. The step fails, the job turns red, and GitHub skips every step after it. Reading a failed log builds confidence faster than reading a successful one.

Step 1  Check out code   [pass]
Step 2  Say hello        [pass]
Step 3  Fail on purpose  [FAIL]
Step 4  List files       [skipped]

Common Problems

Symptom	Likely Cause
Workflow missing in the Actions tab	File sits outside .github/workflows
Error banner on the file	Indentation or spelling mistake in YAML
No run after a push	Push went to a branch not listed under branches
Run button missing	Workflow file lacks workflow_dispatch or sits on a non-default branch

Why This Small Workflow Matters

Every larger pipeline repeats this same shape: a trigger, a job, and a list of steps. Build, test, and deploy workflows only add more steps and smarter triggers. A reliable first run proves that your repository, permissions, and file location all work.