Understanding GitHub Actions Workflow Files (YAML Explained in Detail)

Amaresh Pelleti
Understanding GitHub Actions Workflow Files (YAML Explained in Detail)

This will help readers deeply understand the structure of workflows (.yml files), which is critical for customizing pipelines.

This article is part of our complete Git and GitHub Actions workflow guide.

Understanding GitHub Actions Workflow Files (YAML Explained in Detail)

When working with GitHub Actions, everything revolves around the workflow file. These files define what gets automated — from running tests to deploying apps.

Workflow files are written in YAML and stored inside:

.github/workflows/

This guide explains the structure of workflow files, key sections, and common examples to help you write and customize your own GitHub Actions pipelines.

🔹 Workflow File Structure

A typical workflow looks like this:

name: CI Pipeline

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

🔹 Key Sections in a Workflow File

1. name – Workflow Name

Defines the display name in GitHub Actions.

name: My First Workflow

2. on – Events (Triggers)

Specifies when the workflow should run.

Examples:

on: push                # runs on every push
on: pull_request         # runs on PRs
on:
  schedule:
    - cron: '0 0 * * *' # runs daily at midnight

3. jobs – Group of Tasks

Each workflow has one or more jobs, and jobs contain steps.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "Running build job"

4. runs-on – Runners

Defines the environment (machine) where jobs run.

Options:

  • ubuntu-latest
  • windows-latest
  • macos-latest

You can also use self-hosted runners.

5. steps – Individual Tasks

Steps run in sequence within a job. They can:

  • Run commands (run)
  • Use prebuilt actions (uses)

Example:

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

6. Using Actions (uses)

GitHub Actions has a marketplace of reusable actions.

Example: setting up Node.js:

- name: Set up Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18'

7. Using Environment Variables

Pass custom variables to workflows.

env:
  NODE_ENV: test

Access in steps:

- run: echo "Environment: $NODE_ENV"

8. Using Secrets

Secrets are used for sensitive data (API keys, tokens).

Example:

- name: Deploy
  run: deploy.sh
  env:
    API_KEY: ${{ secrets.API_KEY }}

🔹 Example: Full Workflow

name: Node.js CI

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install
      - run: npm run lint
      - run: npm test

🔹 Best Practices

✅ Use descriptive workflow and job names.
✅ Keep workflows small and modular.
✅ Store credentials in GitHub Secrets, not YAML.
✅ Reuse marketplace actions where possible.
✅ Use caching to speed up builds.

✅ Key Takeaways

  • Workflow files define automation in GitHub Actions.
  • They live in .github/workflows/ and use YAML syntax.
  • Key sections: name, on, jobs, steps.
  • You can run commands, use prebuilt actions, and manage secrets.

Mastering workflow files is the foundation for building complex CI/CD pipelines with GitHub Actions.

Frequently Asked Questions

Where do GitHub Actions workflow files go?

In the .github/workflows directory at the root of your repository, as .yml or .yaml files.

What triggers a GitHub Actions workflow?

The on key: events such as push, pull_request, schedule (cron), workflow_dispatch (manual) or workflow_call (reusable).

What is the difference between a job and a step?

A job runs on its own runner and its steps share that machine; separate jobs run in parallel by default and use needs to depend on each other.

How do I pass data between jobs in GitHub Actions?

Use job outputs combined with needs, or upload and download artifacts for files.

You Might Also Like