Auto-manage PRs on org project board (assignee, status by draft state)

[jflowers]

Problem

PRs opened across the unbound-force org don't automatically get assigned or have their Status field set on the Unbound Force Planning project board. The built-in auto-add project workflows handle adding items, but they cannot:

• Set the Assignee to the PR submitter
• Set Status based on draft state (draft → "In Progress", non-draft → "In Review")
• React to draft ↔ ready-for-review transitions

Proposed Behavior

Event	Action
PR opened (draft)	Add to project, assign submitter, Status = "In Progress 📋"
PR opened (non-draft)	Add to project, assign submitter, Status = "In Review 👀"
PR converted to draft	Status = "In Progress 📋"
PR marked ready for review	Status = "In Review 👀"

Auth Options

Org-level Projects V2 mutations require organization_projects: write, which the default GITHUB_TOKEN in Actions does not provide. Four installed GitHub Apps were evaluated -- none currently have this permission.

Option	Approach	Pros	Cons
A	Add organization_projects: write to existing peribolos app	No new app/secrets, reuses APP_ID/APP_PRIVATE_KEY	Expands scope of an app meant for org membership
B	Create a new dedicated GitHub App (e.g., unbound-force-project-bot)	Least privilege, clean separation, follows peribolos pattern	New app + new org secrets to manage
C	Fine-grained PAT as org secret	Simple setup	Tied to personal account, 1-year max expiry, manual rotation
D	Classic PAT with project scope	Works immediately	Overly broad, being deprecated

Recommendation: Option B (dedicated app) for least privilege, or Option A (expand peribolos) for simplicity.

The new app would need only:

• organization_projects: write
• pull_requests: read
• metadata: read

Implementation

A reusable workflow in unbound-force/.github using actions/create-github-app-token (same pattern as peribolos), callable from each repo with minimal boilerplate. Each repo adds a ~10-line caller workflow.

Tracking issue: unbound-force/.github#9

[yvonnedevlinrh]

GitHub's built-in project automation can add PRs to a board but can't set custom fields or react to draft state transitions, so status never gets reflected automatically without something like this.

A few things worth considering before settling on the implementation:

On auth: The discussion recommends Option B (dedicated app) or Option A (expand peribolos), and I'd agree Option B is the cleaner choice. Peribolos was set up specifically for org membership management — adding project board automation to it conflates two distinct responsibilities and makes it harder to reason about what the app does. A dedicated app keeps the separation clean and follows the same pattern peribolos itself set.

Edge cases to handle:

• Bot PRs (dependabot, renovate), assigning a bot as "submitter" will either fail or produce noise. Worth filtering on github.actor or checking github.event.pull_request.user.type != 'Bot'.
• Race condition if a PR is opened and immediately converted to draft before the first workflow run completes, the two event handlers could conflict.
• The Status field values ("In Progress 📋", "In Review 👀") need to match exact field option IDs in the project board. If those change, the workflow will silently do nothing. Worth documenting the project ID and field IDs somewhere, or using a lookup step rather than hardcoding them.

On rollout: unbound-force doesn't currently have an org-infra sync mechanism like complytime does. For 5 repos, adding the caller workflow manually is manageable. But between this, the config sync proposed in #399, and the existing duplication of agents/commands/skills across repos, it might be worth setting up an unbound-force org-infra to handle distribution centrally, the complytime org-infra pattern is already proven and could be adapted.

[marcusburghardt]

Nice discussion, I would like to share some insights not about the implementation but about how to use the Assignee field.

From this doc: "Assignees clarify who is working on specific issues and pull requests."
Differently from Reviewers field, which is more straightforward, the Assignee field is more flexible since the "working" could mean something different among projects. There is no specific definition on how to use it.

That said, GitHub offers out-of-box features (teams, CODEOWNERS, etc) that allow us to automate the suggested Reviewers, which in my interpretation are all, usually more than necessary, potential Assignees. So I see it as a informative mechanism or a suggestion, not expecting that all the suggested reviewers will in fact review the PR.

On the other hand, I see the Assignee as a commitment to work on that Issue or PR. This might me a reason there is no out-of-box mechanism to automatically set an Assignee, but only inform some potential Assignees (Reviewers) and let themselves to commit if they can.

For example, in some communities it is common for maintainers to triage PRs and distribute the Assignments. So, if another maintainer take a look in a PR where there is already one or more Assignees defined based on Governance Rules, it signals that things are on track there and they can move forward in the queue to the next which does not yet have an assignee. This creates a bit more predictability on expectations and workload.

Maybe the mechanism to automatically include the author as Assignee in PRs, assuming the authors has write access to the repository, is fine since the author is expected to work on the PR, but it could be also beneficial to agree on the expectations among maintainers to assign themselves while the mechanism also raises a flag if there is not enough assignments after some time.