GitHub Actions Basics: How to Write Workflow YAML Files

A beginner's guide to GitHub Actions workflow YAML structure, covering triggers, jobs, steps, and runners with practical examples.

3 min read

What is GitHub Actions?

GitHub Actions is a CI/CD (Continuous Integration/Continuous Delivery) platform that allows you to automate software development workflows directly within your GitHub repository. It automates tasks such as building, testing, and deploying code to streamline the development process.

Workflows are defined by placing YAML files in the following directory structure at the root of your repository:

.github/workflows/{filename}.yml

YAML File Structure

A GitHub Actions workflow YAML file consists of the following main elements:

name: {workflow name} # Workflow name displayed in the GitHub UI

on:
  # Specify trigger events for the workflow
  # Example 1: push event (on push to specified branches)
  push:
    branches:
      - main # or master
      - develop # Multiple branches can be specified

  # Example 2: pull_request event (on PR to specified branches)
  pull_request:
    branches:
      - main
      - develop

  # Example 3: schedule event (specify time in CRON format)
  # Specified in UTC; for JST, subtract 9 hours
  schedule:
    - cron: '45 10 * * *'

  # Other trigger events: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows

jobs:
  # Define jobs to execute
  build: # Job ID (arbitrary name)
    name: Build and Test # Job display name
    runs-on: ubuntu-latest # Specify the runner environment
                            # ubuntu-latest, windows-latest, macos-latest, etc.
                            # Or a specific version (ubuntu-20.04)

    steps:
      # Sequence of steps executed within the job
      - uses: actions/checkout@v4 # Action to checkout repository code
                                  # Use GitHub-provided or community actions

      - name: Install dependencies # Step name
        run: |
          npm install # Example: Install Node.js dependencies
          pip install -r requirements.txt # Example: Install Python dependencies

      - name: Build code # Step name
        run: |
          npm run build # Example: Build the project
          make # Example: Run make command

      - name: Run tests # Step name
        run: |
          npm test # Example: Run tests
          pytest # Example: Run Python tests

Key Elements Explained

  • name: The name of the entire workflow. Displayed in GitHub’s Actions tab.
  • on: Defines when the workflow is triggered. Various events such as push, pull_request, schedule, etc. can be specified.
  • jobs: Defines a series of jobs to be executed within the workflow. Each job can run independently or sequentially with dependencies.
    • runs-on: Specifies the virtual environment (runner) for the job. You can choose the latest versions or specific versions of Ubuntu, Windows, and macOS.
    • steps: A sequence of individual tasks executed within a job.
      • uses: Uses an existing action (a reusable unit of work). actions/checkout@v4 is an official action that checks out repository code to the runner.
      • name: The display name of the step.
      • run: Executes shell commands. Multiple commands can be written using |.

GitHub Actions is highly flexible and can integrate with various tools and services to build complex workflows.

関連記事