GitHub Actions Configuration

This directory contains the CI/CD workflows and automation for the project. This document explains how to configure and use the GitHub Actions workflows.

Table of Contents

• Overview
• Quick Start
• Workflows
• Secrets Configuration
• Repository Variables
• External Service Setup
• Customization

Overview

The CI/CD system provides:

• Quality Gates: Linting, type checking, formatting, and testing
• Security Scanning: Vulnerability detection, secret scanning, license compliance
• Release Management: Automated versioning, changelogs, and GitHub releases
• Mobile Builds: Expo EAS builds for iOS and Android
• OTA Updates: Expo EAS Update deployments
• Performance Testing: Lighthouse CI for web, k6 load testing
• AI Integration: Claude Code for automated code review and assistance

Quick Start

Minimum Configuration

To get started with basic CI, add these secrets to your repository:

# No secrets required for basic quality checks (lint, typecheck, build, format)

Recommended Configuration

For full functionality, configure the following secrets:

Workflows

CI Quality Checks (ci.yml)

Triggers: Pull requests, manual dispatch

Runs on every pull request to validate code quality:

• Lint (ESLint)
• Type checking (TypeScript)
• Formatting (Prettier)
• Build verification
• Security scans (when configured)
• Lighthouse CI (web performance)

Configuration:

# In ci.yml, modify these inputs:
node_version: '22.21.1'
package_manager: 'bun'
skip_jobs: 'test,test:integration,test:e2e'  # Comma-separated list

Release and Deploy (deploy.yml)

Triggers: Push to main, staging, or dev branches; manual dispatch

Handles the complete release lifecycle:

1. Creates a new release with version bump
2. Generates changelog from commits
3. Triggers EAS build (if app.config.ts changed)
4. Publishes OTA update via EAS Update
5. Creates Sentry release (if configured)

Environment Mapping:

EAS Build (build.yml)

Triggers: Changes to app.config.ts, manual dispatch, workflow call

Builds native app binaries via Expo Application Services:

• dev: Development preview builds
• staging: Staging builds with auto-submit to TestFlight/Play Console
• production: Production builds with auto-submit

Quality Checks (quality.yml)

Type: Reusable workflow

Comprehensive quality validation with 20+ configurable jobs. Called by other workflows.

Skippable Jobs:

lint, typecheck, test, test:unit, test:integration, test:e2e,
maestro_e2e, playwright_e2e, format, build, npm_security_scan,
sonarcloud, snyk, secret_scanning, license_compliance

Release (release.yml)

Type: Reusable workflow

Enterprise-grade release management:

• Version strategies: standard-version, semantic, calendar, custom
• Changelog generation
• GPG signing (optional)
• SBOM generation
• Sentry release creation
• Jira release creation
• Compliance validation (SOC2, ISO27001, HIPAA, PCI-DSS)

Blackout Periods (configurable):

• Production: No weekends, no late nights (10 PM - 6 AM)
• Holiday blackouts: Dec 24 - Jan 2, Jul 3-5, Nov 27-29

Lighthouse CI (lighthouse.yml)

Type: Reusable workflow

Web performance budget validation using Google Lighthouse.

Claude Code (claude.yml)

Triggers: Comments/reviews mentioning @claude

AI-powered code assistance that can:

• Review code changes
• Suggest improvements
• Run tests and builds
• Answer questions about the codebase

Load Testing (load-test.yml)

Type: Reusable workflow

Performance load testing using k6:

• Scenarios: smoke, load, stress, spike, soak
• Configurable thresholds
• Result artifact uploads

Secrets Configuration

How to Add Secrets

1. Go to Settings > Secrets and variables > Actions
2. Click New repository secret
3. Enter the secret name and value

Or use the GitHub CLI:

gh secret set SECRET_NAME --body "secret-value"

For bulk setup, copy .github/workflows/.env.example and run:

gh secret set --env-file .env

Core Secrets

EXPO_TOKEN

Purpose: Authenticate with Expo/EAS for builds and updates

How to get it:

1. Go to [expo.dev/settings/access-tokens](https://expo.dev/settings/access-tokens

...