YAML and GitHub Actions

YAML Fundamentals and GitHub Actions Workflows

Understanding Configuration as Code and Workflow Automation

By Presica Peter Pinto  ·  Cloud Team

1. What Is YAML?

YAML (YAML Ain't Markup Language) is a human-readable format used to represent structured data, most often for configuration. Unlike XML or verbose JSON payloads, YAML keeps syntax light and relies on indentation to show hierarchy. That makes it easier for engineers to read quickly, review in pull requests, and maintain over time.

Files typically use the .yml or .yaml extension. In cloud and DevOps workflows, these files act as executable specifications that are stored in Git and interpreted by automation platforms.

Five characteristics that make YAML the standard language of cloud automation.

2. YAML Syntax Fundamentals

Most production YAML files are built from three patterns: key-value pairs, lists, and nested objects. Once these patterns are clear, engineers can work confidently across CI/CD pipelines, container tooling, and platform configuration files.

Key-Value Pairs

name:    AzureApp
version: 1.0
env:     production

Lists

services:
  - frontend
  - backend
  - database

Nested Objects

server:
  host: localhost
  port: 8080

Data Types

name:    "Sam"          # string
age:     52             # number
active:  true           # boolean
manager: null           # null
notes: |
  Multi-line string
  value supported

Rules in Action

# This is a comment
app:
  name: myapp        # spaces only, never tabs
  version: 1.0       # indentation = hierarchy
  services:
    - api            # hyphen = list item
    - web

YAML vs JSON: Choosing the Right Tool

Verdict: YAML for human-written configs  |  JSON for machine-to-machine APIs.

3. YAML in Modern Cloud Engineering

YAML is valuable not only because it is readable, but because the skill transfers across platforms. The same syntax appears in Kubernetes manifests, Docker Compose files, GitHub Actions workflows, and Azure Pipelines definitions. This gives teams a practical learn-once, apply-everywhere advantage.

4. Introduction to GitHub Actions

GitHub Actions is GitHub's built-in automation platform for CI/CD and repository-level operations. It reacts to events such as pushes, pull requests, schedules, and manual triggers, then runs workflows on managed runners.

Workflows are stored in .github/workflows/ as YAML files, which keeps delivery logic version-controlled and visible in the same place as application code. This tight integration improves traceability and simplifies team collaboration.

5. Anatomy of a GitHub Actions Workflow

A workflow combines triggers, jobs, steps, and runners into one automated sequence. A simple factory analogy helps: on is the entry sensor, jobs are departments, steps are tasks on each station, and runners are temporary workers assigned for one shift.

.github/workflows/build.yml

name: CI/CD Pipeline          # display name in Actions UI

on:                           # WHEN to run
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  workflow_dispatch:          # manual trigger button

jobs:
  build:
    runs-on: ubuntu-latest    # ephemeral Ubuntu VM
    steps:
      - uses: actions/checkout@v4    # reusable action
      - name: Build Application
        run: npm run build           # shell command

Each stage acts as a quality gate. If one stage fails, downstream execution stops.

6. Hands-On Demo: Production CI/CD Pipeline Walkthrough

The live demonstration used a production-style pipeline for GoCart, a Next.js e-commerce application. Its structure reflects practical enterprise needs: controlled triggers, fail-fast quality checks, security visibility, containerization, and auditable releases.

Seven sequential quality gates. Each job declares needs on the previous one.

Triggers and Concurrency Control

The workflow listens to push and pull_request events on main/master, and includes workflow_dispatch for manual runs. Concurrency settings prevent duplicate branch runs by canceling outdated executions. On protected branches, teams often keep in-progress runs intact to avoid partial deployment states.

Typical use of workflow_dispatch: hotfix redeployments, reruns for a specific commit, and operator-controlled release execution.

Global Environment Variables

env:
  NODE_VERSION: '20'                 # defined once and reused by all jobs
  DOCKER_IMAGE_NAME: gocart          # consistent image naming across stages
  NEXT_PUBLIC_CURRENCY_SYMBOL: '$'   # region-configurable app-level setting

Centralized variables reduce repetition and lower the risk of drift. For example, changing the Node runtime in one place updates every job that depends on it.

Build Stage: Reproducibility and Artifact Handoff

- uses: actions/checkout@v4
- uses: actions/setup-node@v4
  with:
    node-version: ${{ env.NODE_VERSION }}
    cache: npm                         # avoids re-downloading unchanged packages
- run: npm ci                          # exact lock-file install for reproducibility
- run: npm run build                   # compile Next.js and generate .next output
- uses: actions/upload-artifact@v4
  with:
    name: build-output
    path: .next/
    retention-days: 1                  # short-lived handoff between jobs

npm ci installs exactly what the lock file defines, which keeps builds deterministic across environments. Since jobs run on fresh runners, artifacts are used to hand off build output to later stages.

Lint and Test Stages: Quality Gates with Diagnostics

The lint stage enforces coding standards and catches static issues early. The test stage runs the automated suite with verbose reporting. Both stages publish logs using if: always(), so failure data is retained for troubleshooting and audit trails.

Security Stage: Visibility-First Governance

The security stage usually combines dependency auditing and secret-pattern detection. Dependency checks identify known CVEs; secret scanning looks for leaked credentials such as API keys and passwords. Together, these checks improve release confidence without relying on manual inspection.

In many enterprise teams, findings are reported and retained for compliance review, while remediation is prioritized based on severity and business impact.

Docker Build and Conditional Push: Governance in YAML

# Docker Build validates the image, but does not push on pull requests
- uses: docker/build-push-action@v6
  with:
    push: false                       # build-only on PR branches
    tags: gocart:test
    cache-from: type=gha              # layer caching shortens repeated builds
    cache-to: type=gha,mode=max

# Docker Push runs only for approved execution paths
if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'

This condition enforces a critical policy: pull requests validate code, but do not publish release images. Credentials are injected through encrypted repository secrets and are never stored in plain text in workflow files.

Release Stage: Automated Versioning and Traceability

For successful main-branch runs, release automation can generate semantic tags and publish GitHub Releases with generated notes. This gives teams clean version history, commit-level traceability, and faster rollback capability.

7. Benefits, Best Practices, and Conclusion

Real-World Benefits

DevOps high performers deploy significantly more often and recover faster. Workflow automation is a major reason this performance gap exists.

Best Practices