GitHub Actions Workflows
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub Actions Workflows in the Engineering Platform serve as the automated backbone for maintaining engineering standards, verifying system integrity, and tracking team velocity across consolidated projects. These workflows provide a multi-layered validation strategy encompassing database security, environment consistency, end-to-end testing, and DORA metrics collection.
By centralizing these workflows, the platform ensures that any project utilizing the shared infrastructure benefits from high-frequency checks such as nightly environment drift detection and 5-layer regression testing. These automated processes are designed to be domain-agnostic, allowing them to be applied to various projects including frontend, backend, or fullstack applications.
Sources: README.md:158-164, README.md:11-20
Workflow Architecture and Categories
The platform organizes its automation into several distinct categories to address different aspects of the software development lifecycle. Each workflow is designed with specific triggers, ranging from scheduled cron jobs for nightly maintenance to event-based triggers for pull requests and manual workflow_dispatch events.
Core Workflow Suite
| Workflow | Purpose | Frequency |
|---|---|---|
| Engineering Metrics | Collects DORA metrics and engineering velocity data. | Daily (6 AM UTC) / Weekly Issue |
| Nightly Drift Check | Detects schema and environment differences across dev/staging/prod. | Nightly (2 AM UTC) |
| Database Validation | Validates schema integrity, RLS, and tenant isolation. | Push/PR/Daily (6 AM UTC) |
| Regression Tests | Executes 5-layer regression suite based on test impact. | Push/PR |
| Nightly E2E | Runs cross-browser end-to-end tests. | Nightly |
Sources: workflows/engineering-metrics.yml:7-12, workflows/nightly-drift-check.yml:4-5, workflows/database-validation.yml:3-23, README.md:166-173
Engineering Metrics and DORA Tracking
The Engineering Metrics workflow automates the collection of DORA (DevOps Research and Assessment) metrics by analyzing git history and GitHub PR data. This workflow provides visibility into team performance through metrics such as Deployment Frequency and Lead Time.
The following diagram illustrates the flow of metrics collection and reporting:
The workflow utilizes scripts/metrics/engineering-velocity.js to process the last 4 weeks (default) of data and generates both JSON and Markdown reports.
Sources: workflows/engineering-metrics.yml:39-72, workflows/engineering-metrics.yml:106-120
Key Metrics Tracked
- Deployment Frequency: Average deployments per week.
- Lead Time: Median hours from commit to production.
- Change Failure Rate: Percentage of deployments resulting in failure.
- MTTR (Mean Time to Recovery): Median hours to restore service.
Sources: workflows/engineering-metrics.yml:180-184
Database Schema and Security Validation
The Database Schema Validation workflow is a critical security and integrity gate. It enforces Row Level Security (RLS) and verifies tenant isolation to prevent data leakage in multi-tenant environments.
This workflow treats tenant isolation failures as critical; while other steps may use continue-on-error: true, the tenant isolation check will immediately fail the build if RLS is not properly verified.
Sources: workflows/database-validation.yml:78-83, workflows/database-validation.yml:109-138
Environment Drift Detection
The Nightly Environment Drift Check monitors the consistency of schema and configuration across different environments (dev, staging, production). It identifies "drift" where an environment has diverged from the source of truth.
Drift Detection Logic
- SHA Manifesting: Retrieves the currently deployed git SHAs for all environments using
scripts/deployment/get-deployed-sha.js. - Environment Comparison: Compares staging vs. production and dev vs. staging using
scripts/deployment/compare-environments.js. - Alerting: If high-severity drift is detected (high-severity issues > 0), the workflow creates a GitHub Issue and alerts the team via Slack.
Sources: workflows/nightly-drift-check.yml:45-65, workflows/nightly-drift-check.yml:84-90
Artifact Management
The workflow retains artifacts for 30 days, including:
environment-drift-report.jsonenvironment-drift-summary.mddeployed-sha-manifest.json
Sources: workflows/nightly-drift-check.yml:67-75
Regression and E2E Testing
The platform employs a "5-Layer Regression" strategy to organize testing by dependency depth, ensuring that foundational components are validated before high-level business logic.
5-Layer Regression Structure
- Layer 0 (Foundation): Auth, routing, and health checks.
- Layer 1 (Core): Database, API, and business logic.
- Layer 2 (Data): Ingestion, validation, and transformations.
- Layer 3 (UI/UX): Components, accessibility, and responsiveness.
- Layer 4 (Business): Complete end-to-end workflows.
Sources: README.md:143-149
The Nightly E2E workflow complements this by running cross-browser tests using Playwright across Chromium, Firefox, and WebKit to ensure UI stability.
Sources: README.md:167-168
Summary of Workflow Triggers and Permissions
The following table details the required permissions and common triggers used across the platform's workflow files.
| Permission | Usage | Workflows |
|---|---|---|
| contents: write | Committing metrics reports and schema artifacts. | Engineering Metrics, Drift Check |
| issues: write | Creating automated alerts for drift or weekly metrics. | Engineering Metrics, Drift Check, DB Validation |
| pull-requests: read | Analyzing PR data for DORA metrics. | Engineering Metrics |
| actions: read | Checking workflow run status. | Database Validation |
Sources: workflows/engineering-metrics.yml:25-28, workflows/nightly-drift-check.yml:14-16, workflows/database-validation.yml:25-28
The Engineering Platform workflows provide a robust, automated framework for maintaining high software quality and operational visibility. By combining security-focused database validation with performance-oriented DORA tracking and environment drift detection, the system ensures that engineering teams can move quickly while maintaining stability across multiple project environments.