CI/CD Pipelines

Relevant source files

• .github/workflows/codeql.yml

This document covers the automated Continuous Integration and Continuous Deployment (CI/CD) infrastructure for the RealWorld repository. The CI/CD system validates code quality, runs comprehensive API tests, performs security scans, and ensures specification compliance through GitHub Actions workflows.

For information about manually running tests using the Makefile, see Makefile Commands. For details on the underlying testing infrastructure, see Testing Infrastructure.

---

Overview

The RealWorld repository implements a multi-layered CI/CD strategy using GitHub Actions to automate quality assurance across three primary dimensions:

Workflow	File	Primary Function	Trigger
API Testing	api.yaml	Validates reference implementation against Postman collection	Push, PR
Playwright E2E	api-testing-playwright.yaml	Browser-based end-to-end testing	Push, PR
CodeQL Security	codeql.yml	Static security analysis	Weekly schedule
Chromatic Visual	chromatic.yml	Visual regression testing (docs)	Push

The workflows are orchestrated through GitHub Actions and integrate with the Makefile-based build system documented in Build System & Workflows.

Sources: .github/workflows/codeql.yml1-35

---

Workflow Architecture

Overall CI/CD Flow

Sources: .github/workflows/codeql.yml3-6

---

CodeQL Security Analysis Workflow

The codeql.yml workflow performs static security analysis on the JavaScript codebase to identify potential vulnerabilities, coding errors, and security issues.

Workflow Configuration

Workflow Details

Property	Value	Description
Workflow Name	CodeQL	Displayed name in Actions UI
Triggers	workflow_dispatch, schedule	Manual or weekly automated execution
Schedule	24 3 * * 3	Every Wednesday at 3:24 AM UTC
Runner	ubuntu-latest	GitHub-hosted Ubuntu environment
Language Matrix	javascript	Analyzes JavaScript/TypeScript code

Permissions Model

The workflow operates with minimal required permissions .github/workflows/codeql.yml12-15:

• actions: read - Access to workflow run information
• contents: read - Read access to repository code
• security-events: write - Ability to upload security scan results

Execution Steps

1. Repository Checkout .github/workflows/codeql.yml23-24

   • Uses actions/checkout@v6 to clone the repository
   • Provides CodeQL access to the full codebase

2. CodeQL Initialization .github/workflows/codeql.yml26-29

   • Uses github/codeql-action/init@v4
   • Configures analysis for JavaScript language via matrix strategy .github/workflows/codeql.yml19-20

3. Security Analysis .github/workflows/codeql.yml31-34

   • Uses github/codeql-action/analyze@v4
   • Categorizes results by language: /language:${{matrix.language}}
   • Uploads findings to GitHub Security tab

Strategy Configuration

The workflow uses a fail-fast: false strategy .github/workflows/codeql.yml18 ensuring that if the JavaScript analysis fails, it doesn't prevent other potential language analyses from running (though currently only JavaScript is configured).

Sources: .github/workflows/codeql.yml1-35

---

API Testing Workflow

The api.yaml workflow validates the reference implementation against the Postman test collection to ensure specification compliance.

Workflow Execution Flow

Key Environment Variables

The API testing workflow sets critical environment variables during test execution:

Variable	Purpose	Example Value
JWT_SECRET	JWT token signing key	Set in workflow secrets
APIURL	Target API base URL	http://localhost:3000
USERNAME	Test user credentials	john
EMAIL	Test user email	[email protected]
PASSWORD	Test user password	johnnyjohn

These variables are consumed by run-api-tests.sh and passed to Newman for test execution.

Sources: Based on context from Diagram 3 and section 4.2 references

---

Playwright E2E Testing Workflow

The api-testing-playwright.yaml workflow performs browser-based end-to-end testing against the reference implementation.

E2E Test Architecture

The Playwright workflow tests the API through a browser context, validating both the API behavior and potential frontend integration patterns.

Sources: Based on context from Diagram 2 and architecture overview

---

Workflow Triggers and Scheduling

Trigger Matrix

Scheduling Configuration

The CodeQL workflow runs on a weekly schedule .github/workflows/codeql.yml5-6:

This translates to:

• Minute: 24
• Hour: 3 (3:24 AM)
• Day of Month: * (any)
• Month: * (any)
• Day of Week: 3 (Wednesday)

The specific time (3:24 AM) is chosen to avoid peak GitHub Actions usage hours and reduce queue times.

Sources: .github/workflows/codeql.yml5-6

---

Integration with Makefile Build System

The CI/CD workflows leverage Makefile targets documented in Makefile Commands to standardize execution between local development and CI environments.

Workflow-to-Makefile Mapping

This integration ensures that:

1. Workflows use the same commands as developers
2. Changes to build process only need updates in one place (Makefile)
3. CI failures can be reproduced locally using identical commands

Sources: Based on context from Diagram 3 and section 5.1 references

---

Workflow Outputs and Reporting

Status Reporting Channels

Workflow	Success Indicator	Failure Handling	Artifacts
api.yaml	✅ All Postman tests pass	❌ Test failure logs, API response diffs	Newman HTML report
api-testing-playwright.yaml	✅ All E2E tests pass	❌ Screenshots, trace files	Playwright report, video recordings
codeql.yml	✅ No security issues	⚠️ Security alerts in Security tab	CodeQL SARIF results
chromatic.yml	✅ No visual regressions	⚠️ Visual diff report	Chromatic snapshots

Security Event Integration

The CodeQL workflow writes results to GitHub's Security Events API .github/workflows/codeql.yml15 enabling:

• Code Scanning Alerts - Vulnerabilities appear in the repository's Security tab
• Pull Request Annotations - Security issues highlighted inline in PR diffs
• Dependency Tracking - Links vulnerabilities to affected dependencies
• Trend Analysis - Historical view of security posture over time

Sources: .github/workflows/codeql.yml12-15

---

Permissions and Security Model

Workflow Permissions

Each workflow operates under the principle of least privilege, requesting only necessary permissions:

The permission model .github/workflows/codeql.yml12-15 prevents:

• Workflows from modifying repository contents
• Unauthorized access to secrets
• Escalation of privileges during execution

Sources: .github/workflows/codeql.yml12-15

---

Debugging Workflow Failures

Common Failure Scenarios

Failure Type	Typical Cause	Investigation Steps
API Tests Fail	Schema mismatch, broken endpoint	1. Check Postman test logs 2. Compare API response to spec 3. Run locally: make reference-implementation-test-with-postman
Playwright Timeout	Server startup delay, performance regression	1. Check server startup logs 2. Verify database seeding 3. Increase timeout values
CodeQL Errors	Invalid JavaScript syntax, new vulnerability pattern	1. Review CodeQL logs 2. Check Security tab for details 3. Run CodeQL CLI locally
Build Failure	Dependency issue, version mismatch	1. Check package-lock.json changes 2. Verify Node.js version 3. Clear npm cache

Workflow Re-execution

All workflows support manual re-execution:

1. Navigate to Actions tab in GitHub UI
2. Select failed workflow run
3. Click Re-run jobs dropdown
4. Choose Re-run failed jobs or Re-run all jobs

The CodeQL workflow additionally supports manual triggering via workflow_dispatch .github/workflows/codeql.yml4 for on-demand security scans.

Sources: .github/workflows/codeql.yml4

---

Performance Considerations

Workflow Execution Times

Typical execution durations (approximate):

• api.yaml: 2-4 minutes (setup + ~30 seconds of tests)
• api-testing-playwright.yaml: 5-8 minutes (browser setup + E2E tests)
• codeql.yml: 3-5 minutes (JavaScript analysis)
• chromatic.yml: 2-3 minutes (visual regression)

Optimization Strategies

1. Caching Dependencies - Workflows cache node_modules to reduce installation time
2. Parallel Execution - Multiple workflows run concurrently for different trigger events
3. Matrix Strategy - CodeQL uses matrix for potential multi-language support .github/workflows/codeql.yml18-20
4. Conditional Steps - Skip unnecessary steps based on file changes

Sources: .github/workflows/codeql.yml18-20

---

Summary

The RealWorld CI/CD infrastructure provides comprehensive automated validation through four specialized GitHub Actions workflows:

1. API Testing (api.yaml) - Validates specification compliance via Postman/Newman
2. E2E Testing (api-testing-playwright.yaml) - Browser-based integration testing
3. Security Scanning (codeql.yml) - Weekly automated vulnerability detection
4. Visual Testing (chromatic.yml) - Documentation site visual regression

These workflows integrate with the Makefile build system to ensure consistency between local development and CI environments, while maintaining minimal required permissions for security. The CodeQL workflow's scheduled execution provides ongoing security monitoring, while the testing workflows provide immediate feedback on code changes through push and pull request triggers.

Sources: .github/workflows/codeql.yml1-35