No history yet

Workflow Architecture

The Anatomy of a Workflow

At the heart of GitHub Actions is the workflow file. This is a simple text file written in a format called YAML that you place in a special directory within your repository: .github/workflows/. GitHub automatically detects any YAML files in this location and treats them as instructions for automation.

Think of a workflow file as a recipe. It lists all the ingredients (tools and code) and the step-by-step instructions (commands) needed to produce a final dish, like a tested application or a deployed website.

The structure of this recipe follows a clear hierarchy. At the top level is the workflow. A workflow is the entire automated process, from start to finish. Each workflow is made up of one or more jobs. A job is a set of steps that execute on the same virtual machine, or s. By default, jobs run in parallel, but you can configure them to run sequentially if one job depends on another.

Finally, each job contains a sequence of steps. A step is the smallest unit of work. It can be a shell command (like npm install) or a reusable package of code called an action (like actions/checkout@v4).

Making Workflows Run

A workflow file doesn't do anything until an event triggers it. You define these triggers using the on key in your YAML file. The most common events are push (when someone pushes commits to a branch) and pull_request (when a pull request is opened or updated).

name: Simple CI

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository code
        uses: actions/checkout@v4

      - name: Run a one-line script
        run: echo Hello, world!

In this example, the workflow runs whenever there's a push or a pull request to the main branch. You can get very specific with event filters, triggering workflows based on tags, file paths, or even on a schedule.

Dynamic and Smart

Workflows aren't just static scripts. You can make them dynamic using [{] and expressions. Contexts are collections of variables that provide information about the workflow run. For example, the github context contains details about the event that triggered the workflow, like the repository name or the commit SHA.

You can use this information in expressions to control the flow of your jobs and steps. A common use case is adding a conditional if statement to a step. This allows the step to run only when a certain condition is met.

steps:
  - name: Run only for the main branch
    if: github.ref == 'refs/heads/main'
    run: echo "This step ran on the main branch."

This if conditional checks the github.ref context variable. The step will only execute if the code is on the main branch. By combining triggers, jobs, steps, and expressions, you can build powerful and flexible automation tailored precisely to your project's needs.

Quiz Questions 1/6

In a GitHub repository, where must you place your workflow files for GitHub Actions to automatically detect them?

Quiz Questions 2/6

What is the correct hierarchy of components in a GitHub Actions workflow file, from largest to smallest?