CI/CD Pipeline

Purpose and Scope

This document explains the GitHub Actions workflows that automate testing, code quality checks, and guideline synchronization for the laravel-boost-copilot-cli package. The CI/CD pipeline ensures code quality through automated testing across multiple PHP versions, enforces code style standards, and maintains synchronized documentation.

For information about writing tests that run in this pipeline, see Writing Tests. For details about code style rules enforced by the linting workflow, see Code Quality and Formatting.

Workflow Overview

The package implements three GitHub Actions workflows:

Workflow	File	Purpose	Trigger Events
tests	.github/workflows/tests.yml	Run test suite and code coverage across PHP versions	Push to main, pull request opened/synchronized
linter	.github/workflows/lint.yml	Run Laravel Pint for code style enforcement	Push to main
copy-guideline	.github/workflows/copy-guideline.yml	Synchronize AI guidelines between locations	Push to main when core.blade.php changes

Sources: .github/workflows/tests.yml1-48 .github/workflows/lint.yml1-37 .github/workflows/copy-guideline.yml1-27

CI/CD Pipeline Architecture

Sources: .github/workflows/tests.yml3-8 .github/workflows/lint.yml3-6 .github/workflows/copy-guideline.yml3-8

Test Workflow

The tests.yml workflow executes the complete test suite with code coverage reporting across multiple PHP versions.

Matrix Testing Strategy

The workflow uses a matrix strategy to test against PHP 8.3, 8.4, and 8.5 on Ubuntu latest:

Sources: .github/workflows/tests.yml14-21 .github/workflows/tests.yml28-32

Workflow Steps Detail

Step 1: Checkout Code

The workflow uses actions/checkout@v6 to clone the repository.

Sources: .github/workflows/tests.yml24-25

Step 2: Setup PHP Environment

Configures PHP with required extensions and Xdebug for code coverage:

Sources: .github/workflows/tests.yml27-32

Step 3: Install Dependencies

Runs composer install with flags for CI environment:

• --prefer-dist: Download distribution packages rather than cloning repositories
• --no-interaction: Disable interactive prompts
• --no-progress: Suppress progress display

Sources: .github/workflows/tests.yml34-35

Step 4: Execute Tests with Coverage

Runs the composer test:coverage script, which executes Pest with coverage reporting. This generates build/logs/clover.xml.

Sources: .github/workflows/tests.yml37-38

Step 5: Execute Linter

Runs composer test:lint to verify code style compliance using Laravel Pint in test mode (non-fixing).

Sources: .github/workflows/tests.yml40-41

Step 6: Upload Coverage Report

Uses qltysh/qlty-action/coverage@v1 with OIDC authentication to upload the coverage report from build/logs/clover.xml.

Sources: .github/workflows/tests.yml43-47

Permissions

The workflow requires specific permissions:

Permission	Access Level	Purpose
contents	read	Read repository files
id-token	write	OIDC authentication for coverage upload

Sources: .github/workflows/tests.yml9-11

Linting Workflow

The lint.yml workflow enforces code style standards using Laravel Pint.

Sources: .github/workflows/lint.yml1-37

Linter Configuration

The workflow runs on PHP 8.5 only and uses the Testing environment. It executes composer lint, which runs Laravel Pint in fix mode.

Auto-commit Functionality

The workflow includes commented-out code for automatically committing style fixes. This feature is disabled to prevent automatic changes to the codebase. If enabled, it would:

1. Run Pint to fix code style issues
2. Commit changes with message "fix code style"
3. Exclude workflow files from auto-commit

Sources: .github/workflows/lint.yml29-36

Permissions

Permission	Access Level	Purpose
contents	write	Required for potential auto-commit (currently disabled)

Sources: .github/workflows/lint.yml7-8

Guideline Synchronization Workflow

The copy-guideline.yml workflow maintains synchronization between the core guideline template and the AI guidelines directory.

Sources: .github/workflows/copy-guideline.yml1-27

Path-Based Triggering

The workflow only executes when changes are pushed to main branch and the file resources/boost/guidelines/core.blade.php is modified:

This ensures the workflow runs only when the core guideline template changes, avoiding unnecessary executions.

Sources: .github/workflows/copy-guideline.yml3-7

Synchronization Process

Step 1: Copy Guideline File

Copies the core guideline template to the AI guidelines directory:

Sources: .github/workflows/copy-guideline.yml18-19

Step 2: Auto-commit Changes

Uses stefanzweifel/git-auto-commit-action@v5 to automatically commit the synchronized file:

• Commit message: "Update guideline"
• Commit options: --no-verify to skip Git hooks
• File pattern: .ai/guidelines/copilot-cli.blade.php (only commits the guideline file)

Sources: .github/workflows/copy-guideline.yml21-26

Purpose

This workflow ensures that the guideline file used by AI agents in .ai/guidelines/ stays synchronized with the canonical source in resources/boost/guidelines/. This is important because:

1. The core.blade.php template is the source of truth for AI guidelines (see Guidelines and Instructions)
2. The .ai/ directory is used by GitHub Copilot for contextual awareness
3. Manual synchronization would be error-prone and easily forgotten

Permissions

Permission	Access Level	Purpose
contents	write	Commit synchronized guideline file

Sources: .github/workflows/copy-guideline.yml9-10

Composer Script Integration

The workflows invoke Composer scripts defined in composer.json:

Workflow Command	Composer Script	Description
composer test:coverage	Runs Pest with Xdebug coverage	Generates build/logs/clover.xml
composer test:lint	Runs Pint in test mode	Checks style without fixing
composer lint	Runs Pint in fix mode	Fixes style issues

These scripts are documented in detail in Command Reference.

Sources: .github/workflows/tests.yml38 .github/workflows/tests.yml41 .github/workflows/lint.yml27

Workflow Execution Flow

Sources: .github/workflows/tests.yml3-8 .github/workflows/lint.yml3-6 .github/workflows/copy-guideline.yml3-8 .github/workflows/tests.yml16-19

Failure Handling

Matrix Strategy Fail-Fast

The test workflow uses fail-fast: true in the matrix strategy. This means if tests fail on any PHP version, all other matrix jobs are immediately cancelled. This behavior:

• Saves CI resources
• Provides faster feedback
• Prevents unnecessary test runs when failures are detected

Sources: .github/workflows/tests.yml17

No Automatic Remediation

Neither the test workflow nor the currently active linting workflow perform automatic fixes. This ensures:

• Code changes are deliberate and reviewed
• CI remains a validation gate rather than a code modification system
• Developers maintain control over their code

The auto-commit functionality in lint.yml is intentionally commented out to enforce this policy.

Sources: .github/workflows/lint.yml29-36

Coverage Reporting

The test workflow generates code coverage reports using Xdebug and uploads them to Qlty:

The workflow uses OIDC (OpenID Connect) authentication with id-token: write permission for secure coverage upload without storing credentials.

Sources: .github/workflows/tests.yml32 .github/workflows/tests.yml37-38 .github/workflows/tests.yml43-47

Integration with Development Workflow

The CI/CD pipeline integrates with the development workflow described in other sections:

• Test Development (Writing Tests): Tests written following the patterns documented in 6.3 are executed in the pipeline
• Code Style (Code Quality and Formatting): Style rules configured in pint.json are enforced by the linting workflow
• Local Development (Development Environment Setup): Developers can run the same Composer scripts locally before pushing
• Testbench Environment (Testing with Orchestra Testbench): The CI environment uses the same Testbench configuration

Sources: .github/workflows/tests.yml34-41 .github/workflows/lint.yml26-27