GitHub Actions Workflow

A workflow is a collection of automated instructions that GitHub Actions executes when specified events occur.

Event
  ↓
Workflow
  ↓
Job
  ↓
Steps
  ↓
Result

GitHub Actions workflow files are stored in:

.github/workflows/

For example:

.github/workflows/ci.yml

The file extension can be .yml or .yaml.

A repository can contain a workflow directory with one or more workflow files.

.github/
└── workflows/
    ├── ci.yml
    ├── deploy.yml
    └── tests.yml

Different workflows can be used for different automation tasks.

name: My Workflow

on:
  push:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - run: echo "Hello GitHub Actions"

This workflow runs when a push event occurs.

The name property gives the workflow a readable name.

name: Node.js CI

A clear workflow name makes it easier to identify the workflow in GitHub Actions.

The on section defines the event or events that trigger the workflow.

on:
  push:

This means the workflow can run when a push event occurs.

The push event can trigger a workflow when changes are pushed to the repository.

on:
  push:

This is commonly used for continuous integration.

The pull_request event can trigger a workflow when a pull request is opened, updated, or otherwise matches the configured event.

on:
  pull_request:

The workflow_dispatch event allows a workflow to be started manually.

on:
  workflow_dispatch:

Manual execution can be useful when a developer wants to run a workflow on demand.

A workflow can be configured to respond to multiple events.

on:
  push:
  pull_request:
  workflow_dispatch:

This workflow can respond to pushes, pull requests, and manual execution.

The jobs section contains the jobs that the workflow should execute.

jobs:
  test:
    ...
  build:
    ...

A workflow can contain one or multiple jobs.

Every job has an identifier that is used to reference the job inside the workflow.

jobs:
  test:

Here, test is the job identifier.

The runs-on property specifies the runner environment used by the job.

jobs:
  test:
    runs-on: ubuntu-latest

The runner provides the environment where the job's steps execute.

The steps section contains the individual operations performed by a job.

steps:
  - run: echo "Step 1"
  - run: echo "Step 2"

Steps normally execute in the order they are defined.

The run keyword executes a shell command.

steps:
  - run: echo "Hello"
  - run: npm test

The command depends on the technology and requirements of the project.

The uses keyword allows a workflow to use a reusable action.

steps:
  - uses: actions/checkout@v4

Actions can provide reusable functionality for common automation tasks.

The checkout action is commonly used to make the repository's files available to later workflow steps.

- uses: actions/checkout@v4

After checkout, commands can work with the repository files.

A workflow can install the dependencies required by a project.

steps:
  - uses: actions/checkout@v4

  - run: npm install

The installation command depends on the programming language and package manager.

Testing can be automated as part of a workflow.

steps:
  - uses: actions/checkout@v4
  - run: npm install
  - run: npm test

If the test command fails, the corresponding workflow execution can be reported as unsuccessful.

Workflows can build applications after installing dependencies and running checks.

steps:
  - uses: actions/checkout@v4
  - run: npm install
  - run: npm test
  - run: npm run build

The build command depends on the project.

A workflow can contain multiple jobs.

jobs:

  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm run build

Jobs can be organized according to the workflow requirements.

The needs keyword can make one job depend on another.

jobs:

  test:
    runs-on: ubuntu-latest
    steps:
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - run: npm run build

Here, the build job depends on the test job.

Environment variables can provide configuration values to workflow steps.

env:
  APP_ENV: production

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "$APP_ENV"

Environment variables can be defined at different levels depending on the workflow requirements.

Sensitive information should not be written directly into workflow files. GitHub provides repository and organization secrets for sensitive values.

steps:
  - run: echo "Deploying..."
    env:
      API_KEY: ${{ secrets.API_KEY }}

Secrets should be handled carefully and only exposed to steps that need them.

A workflow or job can use conditions to control when particular work should execute.

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest

    steps:
      - run: echo "Deploy"

Conditions are useful when different actions are required for different situations.

name: Node.js CI

on:
  push:
  pull_request:

jobs:

  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - run: npm install

      - run: npm test

This workflow checks the project for configured push and pull request events.

name: Build Project

on:
  push:
  pull_request:

jobs:

  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm test

  build:
    needs: test
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm run build

Developer Pushes Code
        ↓
GitHub Event
        ↓
Workflow Starts
        ↓
Runner Created
        ↓
Job Starts
        ↓
Steps Execute
        ↓
Tests / Build
        ↓
Workflow Result

The workflow result can help developers determine whether the automated process succeeded or failed.

• Use clear workflow names.
• Keep workflows focused.
• Use appropriate triggers.
• Keep jobs easy to understand.
• Use reusable actions when appropriate.
• Run automated tests.
• Protect sensitive information.
• Use secrets for credentials.
• Keep action versions maintained.
• Review failed workflow runs.

A GitHub Actions workflow defines an automated process using YAML. It specifies the events that trigger automation, the jobs that run, the runner environment, and the steps or actions used to perform the work.

Workflow
   ↓
Trigger
   ↓
Jobs
   ↓
Runner
   ↓
Steps
   ↓
Commands / Actions
   ↓
Tests / Build / Deploy
   ↓
Result

Understanding workflows is important for automating testing, continuous integration, builds, deployment, and other development tasks with GitHub Actions.