GitHub Actions Primer

What are GitHub Actions?

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate build, test, and deployment pipelines. In the v4-monorepo, GitHub Actions are used to validate code changes, run tests, build Docker images, and deploy services to cloud environments.

Key Concepts

Workflows

Workflows are automated procedures that run one or more jobs. They are defined in YAML files in the .github/workflows directory.

Jobs

Jobs are a set of steps that execute on the same runner. Jobs can run in parallel or depend on other jobs.

Steps

Steps are individual tasks that run commands in a job. Steps can run actions, shell commands, or both.

Actions

Actions are reusable units of code that can be used in workflows. They can be defined in the same repository, from other repositories, or from the GitHub Marketplace.

Runners

Runners are servers that run workflows when they're triggered. GitHub provides cloud-hosted runners, or you can host your own.

How GitHub Actions are Used in This Repository

Workflow Structure

The v4-monorepo uses a structured approach to GitHub Actions:

Branch-Based Workflows:
next.ci.yaml: CI for the "next" branch
dev.on-push.merge-into-dev.yaml: CI for the "dev" branch
prod.ci.yaml: CI for the "master" branch
Reusable Workflow Components:
Shared job definitions
Custom action definitions in .github/actions/
Workflow configurations in .github/workflows/configs/
Security Workflows:
Dependency scanning
Secret detection
Code quality analysis

Custom Actions

The repository includes several custom actions:

cache-restore: Restore cache for dependencies
setup-kyan: Set up the environment for Kyan services
setup-rpc: Configure RPC endpoints
google-cloudrun-docker: Deploy to Google Cloud Run

Workflow Examples

Basic CI Workflow

A typical CI workflow for testing and validating changes:

name: Next CI

on:
  push:
    branches:
      - next

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup environment
        uses: ./.github/actions/setup-kyan

      - name: Get affected projects
        id: affected
        run: yarn nx show projects --affected --type=app --json > affected.json

      - name: Run tests
        run: yarn nx affected -t test

      - name: Run lint
        run: yarn nx affected -t lint

      - name: Build affected apps
        run: yarn nx affected -t build

Deployment Workflow

A workflow for deploying to Google Cloud Run:

name: Deploy to Production

on:
  push:
    branches:
      - master

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Google Cloud
        uses: google-github-actions/auth@v2
        with:
          credentials_json: ${{ secrets.GCP_SA_KEY }}

      - name: Build and push Docker image
        uses: ./.github/actions/docker-build
        with:
          image_name: orderbook
          dockerfile: apps/orderbook/Dockerfile

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Cloud Run
        uses: ./.github/actions/google-cloudrun-docker
        with:
          service: orderbook
          image: orderbook:latest
          region: us-central1

NX and GitHub Actions Integration

The repository leverages NX's capabilities with GitHub Actions:

Affected Commands: Only build and test projects affected by changes
Nx Cloud: Share computation cache between workflow runs
Parallelization: Run tasks concurrently for faster workflows

Example of NX integration:

- name: Cache Nx
  uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57
  with:
    path: node_modules/.cache/nx
    key: nx-${{ runner.os }}-${{ hashFiles('yarn.lock') }}

- name: Build affected
  run: yarn nx affected -t build --parallel=3

Custom GitHub Actions

Setup Kyan Action

.github/actions/setup-kyan/action.yaml:

name: 'Setup Kyan Environment'
description: 'Sets up the environment for Kyan services'

runs:
  using: 'composite'
  steps:
    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '22'
        cache: 'yarn'

    - name: Install dependencies
      shell: bash
      run: yarn install --immutable

    - name: Set up Python
      uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55
      with:
        python-version: '3.10'
        cache: 'pip'

    - name: Install Poetry
      shell: bash
      run: pip install poetry

    - name: Set Git credentials
      shell: bash
      run: |
        git config --global user.name "GitHub Actions"
        git config --global user.email "[email protected]"

Environment Variables and Secrets

The workflows use several types of secrets and environment variables:

Repository Secrets:
GCP_SA_KEY: Google Cloud service account key
DOCKER_USERNAME and DOCKER_PASSWORD: Docker registry credentials
NPM_TOKEN: NPM registry token
Environment Variables:
NX_CLOUD_ACCESS_TOKEN: Token for NX Cloud
NODE_OPTIONS: Node.js runtime options

Workflow Optimization

The repository includes several optimizations for GitHub Actions:

Conditional Execution:
Skip jobs when no relevant changes are detected
Use output from previous jobs to determine next steps
Caching:
Cache dependencies between runs
Cache build artifacts for reuse
Matrix Builds:
Run jobs across multiple environments
Parallelize tests across various configurations

Troubleshooting GitHub Actions

Common Issues

Issue	Solution
"Workflow failed"	Check job logs for specific errors
"Missing secret"	Verify secrets are set in repository settings
"NX cache miss"	Ensure NX cache is properly configured
"Docker build failed"	Check Dockerfile and build context
"Timeout error"	Optimize workflow or increase timeout limit

Debugging Workflows

Enable debug logging:
Set secret ACTIONS_RUNNER_DEBUG to true
Set secret ACTIONS_STEP_DEBUG to true
Use GitHub CLI:
List recent workflow runs: gh run list
View logs: gh run view <run-id> --log
Local testing:
Use act to run workflows locally
Test individual actions in isolation