🟡 HIGH: Configure GitHub Actions to run linting before merge

[isaaceliape]

Story Points

5

User Story

As a developer,
I want to have automated linting checks run on all pull requests,
So that I can ensure code quality standards are maintained before merging to master.

Description

Set up GitHub Actions workflow to automatically run ESLint on all pull requests targeting the master branch. This will prevent code that violates project style guidelines from being merged, ensuring consistent code quality.

Acceptance Criteria

• GitHub Actions workflow file created (.github/workflows/lint.yml)
• Workflow runs ESLint on all pull requests to master
• Workflow displays linting results as PR check status
• Developers cannot merge PRs with linting failures
• Workflow completes in reasonable time (<2 minutes)
• Documentation updated with workflow information

Implementation Plan

Phase 1: Create GitHub Actions Workflow (1 SP)

• Create file
• Configure workflow to trigger on pull requests to master
• Set up Node/BUN environment
• Run bun install to install dependencies
• Run bun run lint to execute ESLint
• Report results with appropriate status checks

Phase 2: Configure Workflow Details (2 SP)

• Add job for linting check
• Set up caching for node_modules/bun.lock for speed
• Configure job to run on multiple OS if needed
• Add timeout configuration
• Set appropriate permissions for workflow token
• Add workflow dispatch option for manual trigger

Phase 3: Branch Protection & Testing (1 SP)

• Configure branch protection rule on master:
  • Require status checks to pass before merging
  • Require pull request reviews before merging
  • Dismiss stale pull request approvals
  • Require branches to be up to date before merging
• Test workflow on development branch
• Verify failure detection works
• Verify success detection works

Phase 4: Documentation & Monitoring (1 SP)

• Update README.md with CI/CD workflow information
• Document workflow behavior in AGENTS.md
• Add workflow badge to README.md
• Monitor workflow performance
• Document troubleshooting steps

Implementation Notes

Technical Considerations:

• Use BUN as package manager (bun@latest)
• Leverage bun.lock for deterministic builds
• Cache strategy: cache bun modules and lock file
• Node version: 20.x or later for best compatibility

Dependencies:

• GitHub Actions (built-in, no external dependencies)
• ESLint (already configured in project)
• Node.js/BUN runtime environment

Files to Create/Modify:

• Create: .github/workflows/lint.yml
• Modify: README.md - Add CI/CD section
• Modify: AGENTS.md - Add workflow documentation

Potential Risks:

• Workflow performance: May slow down PR review process if not optimized
  • Mitigation: Implement caching strategy
• False failures: Edge cases in linting rules
  • Mitigation: Review ESLint config before enabling requirement
• Breaking existing PRs: If enforcement enabled on existing PRs
  • Mitigation: Only enforce on new PRs, or temporarily disable for bulk fixes

Performance Target:

• Target workflow execution time: < 2 minutes
• Include caching to avoid reinstalling dependencies

Definition of Done

• Code implemented
  • Workflow file created and tested
  • Branch protection rules configured
• Unit tests written (N/A - infrastructure)
• Tests passing
  • Workflow runs successfully on test PR
  • Linting failures properly detected
• Code reviewed (PR for workflow file)
• Merged to main branch
• Documentation updated
  • README.md updated with CI/CD info
  • Workflow badge added
  • Team notified of new requirement

Additional Context

Related Issues: None

Resources:

• GitHub Actions Documentation
• ESLint Documentation
• BUN Documentation
• Branch Protection Rules

[isaaceliape]

✅ Implementation Complete

All phases have been successfully implemented and merged to master (PR #32).

What Was Completed

Phase 1: GitHub Actions Workflow ✅

• Created .github/workflows/lint.yml
• Configured to run on PRs and pushes to master
• Set up BUN and Node.js environments
• ESLint checks execute and report status

Phase 2: Workflow Details ✅

• Caching for BUN modules and node_modules
• Frozen lockfile for deterministic builds
• 10-minute timeout
• Artifact upload for results
• ~2 minute average execution time

Phase 3: Branch Protection ✅

• Master branch now requires ESLint checks to pass
• Requires 1+ code review approval
• Stale reviews automatically dismissed
• Force pushes and deletions blocked
• Enforced for all users including admins

Phase 4: Documentation ✅

• Workflow badge added to README
• Comprehensive CI/CD Pipeline section added
• Branch protection rules documented
• PR workflow guidelines included
• Troubleshooting guide provided
• AGENTS.md updated

Key Achievements

✨ Branch protection is active and working - Direct pushes to master are now blocked

🚀 Developers must create PRs - All code goes through ESLint checks

📊 Fast execution - ~2 minutes average with smart caching

📖 Well documented - Comprehensive guides for developers

How It Works

1. Developer creates a PR to master
2. GitHub Actions automatically runs ESLint
3. If linting passes → Check status ✅
4. If linting fails → Check status ❌ (must fix)
5. After review approval + passing checks → Can merge
6. Merged code is guaranteed to meet quality standards

Resources

• Workflow file: .github/workflows/lint.yml
• Documentation: README.md "CI/CD Pipeline" section
• Branch protection: Master branch settings on GitHub
• Developer guide: AGENTS.md CI/CD section