|
| 1 | +# GitHub Actions CI/CD Configuration |
| 2 | + |
| 3 | +This directory contains GitHub Actions workflows for continuous integration and deployment. |
| 4 | + |
| 5 | +## PR Comment Commands |
| 6 | + |
| 7 | +### `/run-skipped-ci` - Run Full CI Suite |
| 8 | + |
| 9 | +When you open a PR, CI automatically runs a subset of tests for faster feedback (latest Ruby/Node versions only). To run the **complete CI suite** including all dependency combinations, add a comment to your PR: |
| 10 | + |
| 11 | +``` |
| 12 | +/run-skipped-ci |
| 13 | +``` |
| 14 | + |
| 15 | +This command will trigger: |
| 16 | + |
| 17 | +- ✅ Main test suite with both latest and minimum supported versions |
| 18 | +- ✅ All example app generator tests |
| 19 | +- ✅ React on Rails Pro integration tests |
| 20 | +- ✅ React on Rails Pro package tests |
| 21 | + |
| 22 | +The bot will: |
| 23 | + |
| 24 | +1. React with a 🚀 to your comment |
| 25 | +2. Post a confirmation message with links to the triggered workflows |
| 26 | +3. Start all CI jobs on your PR branch |
| 27 | + |
| 28 | +### Why This Exists |
| 29 | + |
| 30 | +By default, PRs run a subset of CI jobs to provide fast feedback: |
| 31 | + |
| 32 | +- Only latest dependency versions (Ruby 3.4, Node 22) |
| 33 | +- Skips example generator tests |
| 34 | +- Skips some Pro package tests |
| 35 | + |
| 36 | +This is intentional to keep PR feedback loops fast. However, before merging, you should verify compatibility across all supported versions. The `/run-skipped-ci` command makes this easy without waiting for the PR to be merged to master. |
| 37 | + |
| 38 | +### Security & Access Control |
| 39 | + |
| 40 | +**Only repository collaborators with write access can trigger full CI runs.** This prevents: |
| 41 | + |
| 42 | +- Resource abuse from external contributors |
| 43 | +- Unauthorized access to Pro package tests |
| 44 | +- Potential DoS attacks via repeated CI runs |
| 45 | + |
| 46 | +If an unauthorized user attempts to use `/run-skipped-ci`, they'll receive a message explaining the restriction. |
| 47 | + |
| 48 | +### Concurrency Protection |
| 49 | + |
| 50 | +Multiple `/run-skipped-ci` comments on the same PR will cancel in-progress runs to prevent resource waste and duplicate results. |
| 51 | + |
| 52 | +## Testing Comment-Triggered Workflows |
| 53 | + |
| 54 | +**Important**: Comment-triggered workflows (`issue_comment` event) only execute from the **default branch** (master). This creates a chicken-and-egg problem when developing workflow changes. |
| 55 | + |
| 56 | +### Recommended Testing Approach |
| 57 | + |
| 58 | +1. **Develop the workflow**: Create/modify the workflow in your feature branch |
| 59 | +2. **Test locally**: Validate YAML syntax and logic as much as possible |
| 60 | +3. **Merge to master**: The workflow must be in master to be triggered by comments |
| 61 | +4. **Test on a PR**: Create a test PR and use the comment command to verify |
| 62 | + |
| 63 | +### Why This Limitation Exists |
| 64 | + |
| 65 | +GitHub Actions workflows triggered by `issue_comment` events always use the workflow definition from the default branch, not the PR branch. This is a security feature to prevent malicious actors from modifying workflows through PRs. |
| 66 | + |
| 67 | +For more details, see [GitHub's documentation on issue_comment events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#issue_comment). |
| 68 | + |
| 69 | +## Available Workflows |
| 70 | + |
| 71 | +### CI Workflows (Triggered on Push/PR) |
| 72 | + |
| 73 | +- **`main.yml`** - Main test suite (dummy app integration tests) |
| 74 | +- **`lint-js-and-ruby.yml`** - Linting for JavaScript and Ruby code |
| 75 | +- **`package-js-tests.yml`** - JavaScript unit tests for the package |
| 76 | +- **`rspec-package-specs.yml`** - RSpec tests for the Ruby package |
| 77 | +- **`examples.yml`** - Generator tests for example apps |
| 78 | +- **`playwright.yml`** - Playwright E2E tests |
| 79 | +- **`pro-integration-tests.yml`** - Pro package integration tests |
| 80 | +- **`pro-package-tests.yml`** - Pro package unit tests |
| 81 | +- **`pro-lint.yml`** - Pro package linting |
| 82 | + |
| 83 | +### Utility Workflows |
| 84 | + |
| 85 | +- **`run-skipped-ci.yml`** - Triggered by `/run-skipped-ci` comment on PRs |
| 86 | +- **`pr-welcome-comment.yml`** - Auto-comments on new PRs with helpful info |
| 87 | +- **`detect-changes.yml`** - Detects which parts of the codebase changed |
| 88 | + |
| 89 | +### Code Review Workflows |
| 90 | + |
| 91 | +- **`claude.yml`** - Claude AI code review |
| 92 | +- **`claude-code-review.yml`** - Additional Claude code review checks |
| 93 | + |
| 94 | +### Other Workflows |
| 95 | + |
| 96 | +- **`check-markdown-links.yml`** - Validates markdown links |
| 97 | + |
| 98 | +## Workflow Permissions |
| 99 | + |
| 100 | +Most workflows use minimal permissions. The comment-triggered workflows require: |
| 101 | + |
| 102 | +- `contents: read` - To read the repository code |
| 103 | +- `pull-requests: write` - To post comments and reactions |
| 104 | +- `actions: write` - To trigger other workflows |
| 105 | + |
| 106 | +## Conditional Execution |
| 107 | + |
| 108 | +Many workflows use change detection to skip unnecessary jobs: |
| 109 | + |
| 110 | +- Runs all jobs on pushes to `master` |
| 111 | +- Runs only relevant jobs on PRs based on changed files |
| 112 | +- Can be overridden with `workflow_dispatch` or `/run-skipped-ci` command |
| 113 | + |
| 114 | +See `script/ci-changes-detector` for the change detection logic. |
0 commit comments