GitHub Actions Guide: Concepts, Workflow Configuration, Jobs, Steps, Actions, and Advanced Features

GitHub Actions enables creating custom workflows directly in a GitHub repository to automate CI and CD processes such as building, testing, packaging, and deployment.

Basic concepts

workflow

: a complete process containing a set of jobs. job: a collection of steps. step: an individual command or action. action: a reusable unit of functionality.

Configuring a workflow

A workflow file must be stored in .github/workflows/ with a .yml or .yaml extension.

name: Greet Everyone
on: [push]
jobs:
  my_job:
    runs-on: ubuntu-latest
    steps:
      - name: Hello world
        uses: actions/hello-world-javascript-action@v1
        with:
          who-to-greet: 'Mona the Octocat'
      - name: Echo the greeting
        run: echo 'The time was ${{ steps.hello.outputs.time }}.'

Triggering events (on)

The on key defines when a workflow runs. It can be GitHub events, a schedule, or external repository dispatch events.

on:
  push:
    branches: [master]
  pull_request:
    branches: [master]
  schedule:
    - cron: '0 0 * * *'

Jobs and dependencies

Multiple jobs can run in parallel or depend on each other using the needs keyword.

jobs:
  job1:
    runs-on: ubuntu-latest
  job2:
    needs: job1
    runs-on: ubuntu-latest
  job3:
    needs: [job1, job2]
    runs-on: ubuntu-latest

Matrix strategy

Matrix builds allow testing across multiple OSes and runtime versions.

strategy:
  matrix:
    os: [ubuntu-16.04, ubuntu-18.04]
    node: [6, 8, 10]

Steps syntax

Each step can specify name, uses, run, with, env, and error handling options.

- name: Install dependencies
  run: npm ci
- name: Run tests
  if: success()
  run: npm test

Actions

Actions can be referenced from public repositories, the same repository, or Docker images.

# Public action
- uses: actions/checkout@v1
# Local action
- uses: ./github/actions/hello-world-action
# Docker action
- uses: docker://alpine:3.8

Environment variables

Variables can be set at the workflow, job, or step level; the most specific definition wins.

env:
  NODE_ENV: dev
jobs:
  build:
    env:
      NODE_ENV: test
    steps:
      - name: Deploy
        env:
          NODE_ENV: prod
        run: echo Deploying

Conditional execution (if) and contexts

Jobs and steps can use if expressions with built‑in functions like success(), failure(), and always(). Contexts such as github.event_name, secrets, and steps.<em>id</em>.outputs provide runtime information.

if: github.event_name == 'pull_request' && github.event.action == 'opened'
run: echo 'New PR opened'

Conclusion

The example at the end demonstrates a complete CI workflow that builds with multiple Node versions, installs dependencies, runs tests, and reports coverage, illustrating how GitHub Actions can be combined to create powerful, reusable automation pipelines.