Skip to content

docs(dev-lead): concurrency ownership, @main pin, and the permission contract #404

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
don-petry merged 11 commits into from
Jun 8, 2026
Merged

docs(dev-lead): concurrency ownership, @main pin, and the permission contract #404

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
33099f2
docs(dev-lead): document concurrency ownership, @main pin, and permis…
claude Jun 7, 2026
cc0ac22
docs(dev-lead): fix review nits — terminology, grammar, autolink
claude Jun 7, 2026
a5b1b6a
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 7, 2026
41085fa
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 7, 2026
0f6a843
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 7, 2026
d7a81f8
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 7, 2026
1b7fe42
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 7, 2026
1cdc8d9
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 8, 2026
2faafe7
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 8, 2026
46099ee
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 8, 2026
17e08a4
Merge branch 'main' into docs/dev-lead-stub-standard
don-petry Jun 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 57 additions & 5 deletions standards/ci-standards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@ reusable, not a local edit.
> (most are `@v1`; `pr-review-mention` is `@v2`). A tag is bumped deliberately
> when a backward-compatible release is ready; breaking changes publish a new
> tag that downstream repos opt into explicitly.
>
> **Exception — `dev-lead`.** The dev-lead reusable lives in the private
> `petry-projects/.github-private` repo (it checks out private prompts/scripts)
> and is pinned `@main`, not a tag — so permission and security fixes
> propagate immediately instead of waiting for a tag bump or the monthly
> standards-sync. See [Dev-Lead Agent](#dev-lead-agent).
Comment on lines +43 to +47

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Align the Tier 1 row with this dev-lead carve-out

This new exception says dev-lead lives in .github-private and tracks @main, but the Tier 1 table just above still includes dev-lead.yml in a generic rule that says stubs delegate to petry-projects/.github/...@<version> and that the matching reusable lives in this repo. Readers and compliance agents following the table before this carve-out can still generate or validate the old public @v1 shape, so please update the Tier 1 row to either exclude dev-lead or explicitly mention the private @main exception there as well.

Useful? React with 👍 / 👎.


### Available templates

Expand Down Expand Up @@ -937,16 +943,19 @@ incorrect pinned one.

### Exception: Internal Reusable Workflow References

Calls to `petry-projects/.github` reusable workflows use tag references
(`@v1`, `@v2`, or `@main`) — **not SHA pins** — and are exempt from this policy.
Calls to `petry-projects/.github` and `petry-projects/.github-private` reusable
workflows use tag or branch references (`@v1`, `@v2`, or `@main`) — **not SHA
pins** — and are exempt from this policy.

```yaml
# CORRECT — tag ref for internal reusable workflow
uses: petry-projects/.github/.github/workflows/dev-lead-reusable.yml@v1
# CORRECT — tag ref for a public internal reusable workflow
uses: petry-projects/.github/.github/workflows/pr-review-mention-reusable.yml@v2

# CORRECT — dev-lead lives in the private repo and tracks @main (see Dev-Lead Agent)
uses: petry-projects/.github-private/.github/workflows/dev-lead-reusable.yml@main

# WRONG — do not SHA-pin internal reusable workflow refs
uses: petry-projects/.github/.github/workflows/dev-lead-reusable.yml@ee22b427cbce9ecadcf2b436acb57c3adf0cb63d
uses: petry-projects/.github-private/.github/workflows/dev-lead-reusable.yml@ee22b427cbce9ecadcf2b436acb57c3adf0cb63d
```

**Why:** Pinning the `uses:` line in a Tier 1 caller stub creates a diff from
Expand Down Expand Up @@ -1185,6 +1194,49 @@ All repos MUST align to the latest version of each action:
The dev-lead agent is a reactive, write-enabled automation that keeps pull requests in a clean, approvable, and mergeable state.
It responds to CI failures, bot reviews, human `@mentions`, and labeled issues.

### Concurrency, pinning, and the permission contract

Three things are deliberately **not** tuned in the caller stub — they are owned
centrally so they cannot drift per repo:

- **Concurrency.** The stub carries **no `concurrency:` block**. Concurrency is
centralized in `dev-lead-reusable.yml` with per-issue / per-PR / ci-relay
Comment thread
don-petry marked this conversation as resolved.
lanes (`dev-lead-issue-<n>`, `dev-lead-pr-<n>`, `dev-lead-ci-relay-<sha>`,
`cancel-in-progress: false`). This keeps a labeled-issue pickup from being
cancelled by unrelated PR follow-up traffic — per-stub concurrency previously
drifted into three incompatible variants and starved issue pickups
(petry-projects/.github#402). Running lanes in parallel is safe because the
agent checks out PR branches in an isolated worktree (petry-projects/.github-private#448).
- **Pin.** The stub pins
`petry-projects/.github-private/.github/workflows/dev-lead-reusable.yml@main`
— `@main`, not a tag — so a permission or security fix reaches every
repo immediately rather than waiting for a tag bump or the monthly
standards-sync.
- **Permissions.** The stub's `jobs.dev-lead.permissions` must grant the **full
set that the reusable requests**:

```yaml
permissions:
contents: write
pull-requests: write
issues: write
actions: read
checks: read
statuses: read
Comment thread
don-petry marked this conversation as resolved.
```

A reusable workflow can only use permissions its caller grants; if the
reusable requests a scope the stub lacks, **every consumer fails at startup**
(`startup_failure`, with no runtime error). When the reusable needs a new
scope, add it to the template **and** every shim *before* the reusable
requests it — the `caller-permissions` CI guard in `.github-private` enforces
that ordering.

To exclude a specific PR or issue from the agent — e.g. a PR that edits the
dev-lead workflow itself, so the agent doesn't pile commits onto its own infra
change — add the **`dev-lead:hands-off`** label; the classifier then skips every

@chatgpt-codex-connector chatgpt-codex-connector Bot Jun 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Provision the hands-off label before documenting it

This new escape-hatch relies on a dev-lead:hands-off label, but the standard label set and the label automation I checked (standards/github-settings.md and scripts/apply-repo-settings.sh) only create the existing standard labels and do not include this one. In repos managed by these settings, maintainers following this instruction will not be able to apply the label until it is manually created, so the classifier cannot skip the PR/issue. Please add the label to the standard/automation, or document an explicit creation step, with this guidance.

Useful? React with 👍 / 👎.

event on it.

### Adopting the Dev-Lead Agent

1. Copy `standards/workflows/dev-lead.yml` verbatim to `.github/workflows/dev-lead.yml` in your repo.
Expand Down
Loading