Project Board Automation
Keep your GitHub project's status in step with the CodeLantern workflow, and check that it's working.
As an issue moves through the workflow, skills add cl-* workflow labels that record its stage. Project board automation uses those labels, and your pull requests, to move the issue across your project board, so the board shows where work stands without anyone dragging cards.
Project board automation supports GitHub Projects. cl-init adds a workflow that updates your project's Status field. It's optional: you can use the CodeLantern workflow without enabling board automation.
How issues move
cl-init asks you to match three stages to options in your project's Status field. The column names here are examples. Yours are whatever you confirmed.
| When this happens | The issue moves to |
|---|---|
cl-spec-complete is added (spec) | Ready |
cl-planning is added (claim-issue) | In Progress |
cl-plan-approved is added (approve-plan) | In Progress |
cl-implementing is added (implement) | In Progress |
| A draft pull request that closes the issue is opened | In Progress |
| A pull request that closes the issue is opened ready for review, marked ready for review, or reviewed | In Review |
cl-implementation-complete is added (finalize) | In Review |
cl-plan-ready, which marks a plan waiting for approval, doesn't move the issue. It stays in In Progress. A pull request counts as closing an issue when its description links it with a keyword such as Closes #42. The workflow skills write that link for you.
Set it up
- Make sure the project is owned by your GitHub organization and has a single-select Status field with an option for each of the three stages.
- Run
/cl-dev:cl-initand accept board automation. It reads your project's Status options and proposes a match for each stage. Confirm or change them. It uses only options that already exist and never creates or renames columns. - Have an owner of your GitHub organization approve the CodeLantern GitHub App's organization Projects (read and write) permission, if they haven't already.
- Commit
.github/workflows/cl-board-automation.ymland merge it into your default branch. - Make sure issues reach the board. A label change adds the issue to the project if it isn't there yet, but pull request events only move issues already in the project. Turn on auto-add in the project's settings, or add issues from their Projects sidebar.
To turn it on later, run cl-init again and accept board automation. cl-init never overwrites an existing workflow file, so to point it at a different project, delete .github/workflows/cl-board-automation.yml first, then run cl-init again. To rename a stage's column, edit the three status names near the top of the workflow file.
Check that it's working
Add a workflow label to an issue on the board, or open a draft pull request that closes it, and watch its status change. Each move is a Project Board Automation run in the repository's Actions tab. When a run fails, its log says why:
- "is not on Project board." A pull request event found an issue that isn't in the project. Add the issue to the project, or turn on auto-add.
- "does not have an option matching" a column name. The column was renamed or removed after setup. Update the status names at the top of the workflow file.
- "CodeLantern token exchange failed." The CodeLantern GitHub App isn't installed on the repository.
- "did not resolve to a ProjectV2." An organization owner hasn't approved the App's Projects permission, or the project isn't owned by this organization.
- "does not have a 'Status' single-select field." Add a Status field whose options match the names in the workflow.
- "Failed to get bot token." The CodeLantern GitHub App isn't installed on the repository, or it lacks Projects access.
The automation only updates the board. Don't make it a required status check on pull requests, so a board problem never blocks a merge.