Workflow files and triggers

Every GitHub Actions automation starts with a workflow file and an event that triggers it. The exam asks a lot about getting this syntax exactly right.

The workflow file

A workflow is a YAML file in .github/workflows/. It contains a name, one or more triggers under on, and one or more jobs. Each job has a runs-on value and a list of steps. A step either runs a shell command with run or calls an action with uses.

name: CI
on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]
    paths:
      - 'apps/**'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          npm ci
          npm run build

Use run: | for several commands. The shell key only picks the interpreter, for example shell: python, and never holds the commands themselves.

Events and filters

Need	Event
Code pushed	push
Pull request activity	pull_request
Run on a timer	schedule with cron
Run by hand	workflow_dispatch
Call from outside GitHub	repository_dispatch
Chain after another workflow	workflow_run
Called by another workflow	workflow_call

Many events have activity types. issues can be limited with types: [opened, edited]. For pull_request the default types are opened, synchronize and reopened. If you write a list of types, only those fire.

Filters combine with AND logic. A branches filter and a paths filter must both match. Use branches-ignore or paths-ignore to exclude, but do not mix branches and branches-ignore for the same event.

Manual and scheduled runs

workflow_dispatch adds a Run workflow button and can define inputs. schedule uses POSIX cron syntax, runs in UTC, and runs only from the default branch. The shortest interval is five minutes.

Conditions

Use if: on a job or step. Expressions can omit ${{ }} in an if. To run a deploy job only for one branch, use github.ref_name == 'feature-branch'. The names github.branch and github.ref.name do not exist.

Exam traps

• shell does not contain commands. Use run for commands and shell only to change the interpreter.
• schedule and workflow_dispatch use the default branch or the branch you pick, not whichever branch you edited last.
• pull_request_label is not an event. The label is an activity type of pull_request.
• branches and paths filters are combined with AND, not OR.
• A cron schedule is always UTC, not the time zone of the repository owner.

Practice questions

Choose an answer, then review the explanation to check your understanding.

1. Where must a workflow file be stored so that repository events can trigger it?

1. A.In the .github/workflows folder
2. B.In the .github/actions folder
3. C.In the root of the repository, with any name
4. D.In a .workflows folder

Show answer

Answer: A.Workflow files are YAML files in .github/workflows. Files stored anywhere else are ignored.

2. A deployment workflow must run when a pull request is labeled, but only for the releases branch and only when files under apps/ change. Which trigger fits?

1. A.on: pull_request_label with branches and paths
2. B.on: pull_request with types [labeled], branches [releases] and paths [apps/**]
3. C.on: pull_request_review with types [labeled]
4. D.on: push with paths [apps/**]

Show answer

Answer: B.The event is pull_request. The types filter selects the labeled activity, and branches and paths narrow it further.

3. Activity outside GitHub must start a workflow through the REST API. Which event do you use?

1. A.workflow_run
2. B.deployment
3. C.repository_dispatch
4. D.check_suite

Show answer

Answer: C.repository_dispatch is fired by an API call and lets you send a custom event type and payload.

4. A workflow must run on pushes and on pull requests. Which syntax is valid?

1. A.on: [push, commit]
2. B.on: [push, pull_request]
3. C.on: env: [push, pull_request]
4. D.on: push, pull_request

Show answer

Answer: B.Several events can be listed in an array, such as on: [push, pull_request]. There is no commit event.