GitHub Actions YAML Syntax

# CHAPTER 3

GitHub Actions YAML Syntax #

1. Introduction #

2. Learning Objectives #

• Understand the strict indentation rules of YAML.

• Differentiate between YAML dictionaries (key-value pairs) and lists (arrays).

• Utilize the core GitHub Actions keywords: name, on, jobs, steps, uses, and run.

• Identify common syntax errors that cause workflows to fail.

3. Beginner-Friendly Explanation #

• Main Heading: (No spaces)

• Sub-heading: (Indent 2 spaces)

• Bullet point: (Indent 4 spaces, use a dash)

YAML is exactly like a strict essay outline. It uses spaces to show relationships. If you put a sub-heading directly under a main heading without indenting it, the computer gets confused and assumes they are completely unrelated.

4. The Golden Rules of YAML #

1. 1. NO TABS: Never use the Tab key to indent. You must use the Spacebar. (Most code editors automatically convert tabs to spaces for you).

1. 2. Indentation is everything: Two spaces define a child element.

1. 3. Key-Value Pairs (Dictionaries): Separated by a colon and a space. key: value

1. 4. Lists (Arrays): Indicated by a dash and a space. - item

5. Deconstructing the Workflow YAML #

name: The title of your workflow. This is what appears in the GitHub Actions UI.

name: Production Deployment

on: The event that triggers the workflow. This can be a single event, a list, or an event with filters.

# Trigger on push to ANY branch
on: push

# Trigger on push OR pull_request
on: [push, pull_request]

# Trigger ONLY when code is pushed to the 'main' branch
on:
  push:
    branches:
      - main

jobs: The container for all your jobs. Every workflow must have at least one job.

jobs:
  build-my-app: # This is an ID you create. No spaces allowed.
    runs-on: ubuntu-latest # Mandatory: Defines the server OS

steps: The sequence of tasks inside a job. Steps use lists (the dash -).

    steps:
      - name: Print a message # 'name' is optional but highly recommended
        run: echo "Executing step 1"

run: vs uses: This is the most critical distinction in GitHub Actions!

• run: Tells the runner to execute a standard Linux terminal command.

• uses: Tells the runner to download a pre-built script from the GitHub Marketplace and run it.

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4 # Downloads your code from Git
        
      - name: Install dependencies
        run: npm install # Runs a terminal command

6. Mini Project: Build a Simple Workflow Using YAML #

Step-by-Step Walkthrough:

1. 1. Open your repository and create .github/workflows/syntax-demo.yml.

1. 2. Type the following code carefully, paying strict attention to the spacing.

name: YAML Syntax Demo

# Trigger on push to main, or manually via button
on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  demonstrate-syntax:
    runs-on: ubuntu-latest
    steps:
      # Step 1: Uses a marketplace action to pull the code
      - name: Get the Code
        uses: actions/checkout@v4
      
      # Step 2: Runs a single shell command
      - name: Check server OS
        run: cat /etc/os-release
      
      # Step 3: Runs MULTIPLE shell commands using the pipe '|' character
      - name: Run Multiple Commands
        run: |
          echo "Line 1"
          echo "Line 2"
          ls -la

1. 3. Commit the file. Go to the Actions tab and watch it execute!

7. Real-World Scenarios #

8. Best Practices #

• Multi-line Strings: When you need to run several shell commands in a single step, do not write multiple run: keywords. Instead, use the pipe character |. This tells YAML: "Everything indented below this line is one big block of text."

9. Security Recommendations #

• Pinning Action Versions: In the example, we used actions/checkout@v4. The @v4 is crucial. It tells GitHub to use version 4. If you use @master or @main, the creator of that action could push a malicious update tomorrow, and your pipeline would automatically download and run the hacked code. Always pin your actions to a specific version tag.

10. Troubleshooting Tips #

• YAML Validators: If your workflow won't run, 90% of the time it is an indentation error. Use a free online tool like yamllint.com to paste your code. It will instantly highlight missing spaces or invalid formatting.

11. Exercises #

1. 1. What is the functional difference between the run: keyword and the uses: keyword?

1. 2. Why is the pipe character | used after the run: keyword in complex steps?

12. FAQs #

13. Interview Questions #

• Q: Explain the purpose of the actions/checkout step in a GitHub Actions workflow. Why is this step explicitly required before you can run npm install or composer install?

• Q: A pipeline fails with a YAML parsing error on a step attempting to execute a multi-line Bash script. What YAML syntax character is likely missing from the run: declaration?

14. Summary #

15. Next Chapter Recommendation #