ci: Add branch policy enforcement and PR template by DanielKellerM · Pull Request #102 · pulp-platform/iDMA

DanielKellerM · 2026-05-16T17:19:12Z

Description

Adds a staging-branch workflow so that all external contributions land on devel first, are verified by the existing gitlab-ci pipeline (which already includes the proprietary nonfree/ child pipeline running on the internal GitLab mirror), and only then get promoted to master automatically.

What's included

File	Purpose
`.github/workflows/retarget-to-devel.yml`	Auto-retargets PRs from non-maintainers (`author_association ∉ {OWNER, MEMBER, COLLABORATOR}`) that aim at `master`, redirecting them to `devel` with a polite comment. Maintainers can still PR `master` directly.
`.github/workflows/promote-to-master.yml`	Listens for `ci` workflow_run completions. On success+push+devel, opens (or refreshes) a single rolling `devel → master` promotion PR.
`.github/pull_request_template.md`	Surfaces the branch policy + a short checklist.
`CONTRIBUTING.md`	Documents the policy with rationale and the fast-track escape hatch.
`.gitlint`	Tightened to reject extra colons in the subject (matches `util/lint-commits.py`).

⚠️ Repo-level setting required before this can fully work

Tested end-to-end on a sandbox (DanielKellerM/iDMA-policy-sandbox). Found that the promote workflow fails with:

GitHub Actions is not permitted to create or approve pull requests.

unless the repo setting is enabled at:

Settings → Actions → General → Workflow permissions → ☑ "Allow GitHub Actions to create and approve pull requests"

The retarget workflow does not need this (it uses pulls.update, which is covered by the existing pull-requests: write token scope). Only the promote workflow's pulls.create is gated by this org/repo setting.

How promotion works end-to-end

Contributor opens PR — gets auto-retargeted to devel if it pointed at master.
PR review + ci runs (lint, build, analyze, gitlab-ci, etc.); gitlab-ci includes the nonfree/ child pipeline.
PR merges into devel.
Push to devel re-triggers ci.
When ci completes green, promote-to-master.yml fires and opens/refreshes the rolling devel → master PR.
A maintainer merges the promotion PR.

Caveat — fork PRs

gitlab-ci.yml skips on fork PRs (no secrets). To verify a fork PR, push its branch as an internal branch first (e.g. git push origin pr-NNN:pr-NNN-internal) so gitlab-ci runs.

Validation done before this PR

actionlint-style static review (workflow YAML, permission scopes, expression syntax)
act -n gating tests across 11 scenarios (7 retarget + 4 promote — all match expected)
Node-based unit tests of the actions/github-script bodies with mocked Octokit (10/10 pass) — covers dedup marker, comment-failure tolerance, 422 narrow-swallow, idempotent update vs. create
Two rounds of adversarial agent review — all findings addressed
End-to-end sandbox test (DanielKellerM/iDMA-policy-sandbox): real ci → promote-to-master chain produces correct devel → master PR with correct body, head, base.

Test plan after merge

Maintainer enables the Actions PR-creation setting on pulp-platform/iDMA (one-time, see above)
Open a test fork PR targeting master; verify auto-retarget to devel with explanatory comment
Land a small PR on devel; verify the rolling devel → master promotion PR is opened by the bot after ci goes green
Land a second PR on devel; verify the same promotion PR is refreshed (body updated), not duplicated

Notes

master remains the default branch.
Maintainers retain the ability to push to master directly when needed.
No existing CI is touched.

Copilot

Pull request overview

This PR introduces branch-policy automation for GitHub PRs and adds a new documentation site + verification assets, including a new rw_obi backend job suite and build-matrix wiring.

Changes:

Add GitHub workflows to (a) auto-retarget non-maintainer PRs from master to devel, and (b) open/update a rolling devel -> master promotion PR when verified-internal is applied.
Add/expand contributor-facing process docs (PR template + CONTRIBUTING branch policy).
Add rw_obi backend support wiring (idma.mk, jobs/jobs.json, new job suite) and introduce an Astro/Starlight docs site with architecture/guides content and diagrams.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`.github/workflows/retarget-to-devel.yml`	Auto-retarget external PRs from `master` to `devel` and comment with policy.
`.github/workflows/promote-to-master.yml`	Label-driven rolling promotion PR from `devel` to `master`.
`.github/pull_request_template.md`	PR template describing the branch policy + contributor checklist.
`CONTRIBUTING.md`	Documents the new branch policy and fast-track process.
`idma.mk`	Adds `rw_obi` to the generated backend ID list.
`jobs/jobs.json`	Registers `rw_obi` variant and its job suite + params.
`jobs/backend_rw_obi/*`	Adds the `rw_obi` job files suite (simple/small/medium/large/huge/etc).
`doc/.gitignore`	Ignores Astro build artifacts and local diagram outputs.
`doc/site/package.json`	Adds Astro/Starlight docs site dependencies and scripts.
`doc/site/astro.config.mjs`	Starlight sidebar + site configuration.
`doc/site/tsconfig.json`	Strict TS config for the docs site.
`doc/site/src/content.config.ts`	Defines the `docs` content collection schema.
`doc/site/src/content/docs/**`	New documentation content (overview, architecture, guides).
`doc/site/public/fig/*.svg`	Adds diagrams referenced by the docs pages.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Add devel as the staging branch for all external contributions: - retarget-to-devel.yml auto-retargets external PRs from master to devel via author_association check (OWNER/MEMBER/COLLABORATOR may still target master directly for promotion PRs). - promote-to-master.yml opens or extends a rolling devel->master PR when a maintainer applies the verified-internal label to a merged devel PR. - pull_request_template.md surfaces the policy in every new PR. - CONTRIBUTING.md documents the policy with rationale. Maintainers need to create the verified-internal label once (any color, description optional) before promote-to-master.yml fires.

Copilot

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

- retarget-to-devel: also fire on `edited` so a PR re-targeted to master post-open is still caught. - promote-to-master: swallow the 422 from `pulls.create` when two concurrent gitlab-ci runs race to open the promotion PR. - CONTRIBUTING: use ASCII `->` for greppability.

- promote-to-master: trigger on the parent `ci` workflow_run, not `gitlab-ci` (which is workflow_call-only and never produces its own workflow_run event). `ci` aggregates lint+build+gitlab-ci, so its success is a strictly stronger gate. - promote-to-master: narrow the 422 swallow to only the 'pull request already exists' validation error; rethrow other 422s (missing base, invalid head, no commits between, ...). - promote-to-master: add concurrency group to serialise rapid runs. - retarget-to-devel: add concurrency group keyed on PR number with cancel-in-progress, so rapid edited events don't spawn duplicate jobs. - retarget-to-devel: build the CONTRIBUTING.md link from `context.serverUrl` instead of a relative path, so it renders correctly in PR comments regardless of GitHub's markdown context.

- retarget-to-devel: embed a `` HTML marker in the comment body and check for it via paginated listComments before posting. Rapid `edited` events that cancel and re-fire the job no longer post duplicate comments. - retarget-to-devel: wrap createComment in try/catch with core.warning so a transient comment failure (after the retarget already succeeded) does not fail the workflow.

- promote-to-master: downgrade `contents: write` to `contents: read`. The script only calls `repos.compareCommits` (read) and PR APIs already covered by `pull-requests: write`. - CONTRIBUTING: fix pre-existing `pulp_platform` (underscore) to `pulp-platform` (hyphen) — the actual GitHub org slug.

Matches the single-colon rule enforced by util/lint-commits.py in CI. Now gitlint (run locally via pre-commit) catches the same failure mode that broke this PR's commit-msg lint.

Copilot AI review requested due to automatic review settings May 16, 2026 17:19

DanielKellerM requested a review from thommythomaso as a code owner May 16, 2026 17:19

Copilot started reviewing on behalf of DanielKellerM May 16, 2026 17:19 View session

DanielKellerM force-pushed the feat/branch-policy branch from 83a5d13 to 071b1a2 Compare May 16, 2026 17:23

Copilot AI reviewed May 16, 2026

View reviewed changes

Comment thread .github/workflows/retarget-to-devel.yml

Comment thread .github/workflows/retarget-to-devel.yml Outdated

Comment thread .github/workflows/promote-to-master.yml

DanielKellerM force-pushed the feat/branch-policy branch 2 times, most recently from ca9905a to c7360e2 Compare May 17, 2026 06:48

DanielKellerM force-pushed the feat/branch-policy branch from c7360e2 to e22981b Compare May 17, 2026 06:49

DanielKellerM requested a review from Copilot May 17, 2026 07:08

Copilot started reviewing on behalf of DanielKellerM May 17, 2026 07:08 View session

Copilot AI reviewed May 17, 2026

View reviewed changes

Comment thread .github/workflows/promote-to-master.yml

Comment thread .github/workflows/promote-to-master.yml

Comment thread CONTRIBUTING.md Outdated

DanielKellerM added 4 commits May 17, 2026 09:17

DanielKellerM force-pushed the feat/branch-policy branch from 3fbf7cf to 5076e8c Compare May 17, 2026 08:37

ci: Tighten gitlint regex to forbid extra colons in subject

880ba0e

Matches the single-colon rule enforced by util/lint-commits.py in CI. Now gitlint (run locally via pre-commit) catches the same failure mode that broke this PR's commit-msg lint.

DanielKellerM closed this May 17, 2026

DanielKellerM deleted the feat/branch-policy branch May 17, 2026 17:41

DanielKellerM restored the feat/branch-policy branch May 17, 2026 17:45

DanielKellerM reopened this May 17, 2026

This was referenced May 18, 2026

docs: Add Starlight documentation site with architecture diagrams #103

Open

ci: Bump pulp-platform/pulp-actions from v2 to v2.5.0 #104

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ci: Add branch policy enforcement and PR template#102

ci: Add branch policy enforcement and PR template#102
DanielKellerM wants to merge 6 commits into
pulp-platform:develfrom
DanielKellerM:feat/branch-policy

DanielKellerM commented May 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

DanielKellerM commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What's included

⚠️ Repo-level setting required before this can fully work

How promotion works end-to-end

Caveat — fork PRs

Validation done before this PR

Test plan after merge

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DanielKellerM commented May 16, 2026 •

edited

Loading