quay/agent_docs/workflow.md

Development Workflow

End-to-end process for PROJQUAY/QUAYIO ticketed work: JIRA ticket to merged PR.

Lifecycle Phases

  /start          /code           /pr            /poll           /backport
┌─────────┐   ┌─────────┐   ┌─────────┐   ┌──────────┐   ┌───────────┐
│  JIRA   │──>│  Code   │──>│  Pull   │──>│  Review  │──>│ Backport  │
│  Setup  │   │  & Test │   │ Request │   │  & Fix   │   │ (if needed│
└─────────┘   └─────────┘   └─────────┘   └──────────┘   └───────────┘
 ASSIGNED       ASSIGNED        POST          POST         POST/ON_QA

JIRA Process

Ticket Lifecycle

JIRA Status	When	Triggered By
New	Ticket created	Reporter
ASSIGNED	Work begins	/start or manual
POST	PR created	openshift-ci-robot on PR creation
MODIFIED	PR merged	openshift-ci-robot on merge
ON_QA	In QA pipeline	QE team
Verified	QA passed	QE team
Closed	Released	Release manager

Target Version & Backporting

• Target Version (customfield_10855) holds exactly one version: .0 means master (e.g. quay-v3.19.0), quay-vX.Y.z means redhat-X.Y
• The list of releases to backport to is fixVersions, mapped like Target Version above (quay-vX.Y.z → redhat-X.Y; drop .0 — master already has the change), skipping the sync check's master-synced branch even if named.
• For a PROJQUAY-titled PR, fire the cascade with /jira backport <branch>, one branch per comment; for a NO-ISSUE or QUAYIO-titled PR, use /cherrypick <branch>, also one branch per comment. To skip over an intermediate branch, /jira backport a comma-separated list naming every branch from the current PR down to the target — this also clones the skipped branch's ticket, which a human then sets to Won't Do. /cherrypick has no such form: skip a branch by firing /cherrypick <target> alone on the last merged PR. See agent_docs/backports.md for the cascade order

Release Branch Model

Branch facts go stale every release. Verify before backporting instead of trusting the snapshot below.

• The newest redhat-* branch is kept in sync with master — do not cherry-pick to it. Identify and confirm it:

  git fetch upstream --prune
  git branch -r --list 'upstream/redhat-*' | sed 's|.*upstream/||' | sort -V | tail -1
  git rev-list --left-right --count upstream/<branch>...upstream/master  # "0  0" == synced
  

  As of 2026-09-20 that branch is redhat-3.19. redhat-3.18 is a normal release branch and does take cherry-picks.
• For which older branches are still maintained, check recent activity rather than a hardcoded range:

  git log --oneline --since='3 months ago' upstream/<branch> ^upstream/master
  

  Read the tier off the subjects: a feat subject means regular backports; fixes/CVE/dependency/changelog only means critical/security fixes only; no commits means dormant. The lifecycle API is the authoritative tier check, not this heuristic:

  curl -s 'https://access.redhat.com/product-life-cycles/api/v1/products?name=Red%20Hat%20Quay' | jq -c '.data[].versions[] | {name, type}'
  

  As of 2026-09-25: redhat-3.17/redhat-3.18 (Full Support) take regular backports; redhat-3.15/redhat-3.16 (Maintenance Support) take only critical/important security fixes and urgent or selected high-priority bug fixes; redhat-3.9, redhat-3.10, redhat-3.12, redhat-3.13, redhat-3.14 receive critical/security fixes only; redhat-3.11 is dormant.
• When backporting, target the branches fixVersions names: map quay-vX.Y.z → redhat-X.Y, drop .0 (master has it already), then skip the master-synced branch identified above.
• CodeRabbit auto-review is intentionally scoped to master only — it is not enabled for redhat-* branches. Backport/cherry-pick PRs carry code already reviewed on master, so re-running review on the release branch was evaluated and rejected as unnecessary noise (see PR #6894). Do not re-propose adding base_branches for redhat-* in .coderabbit.yaml without first revisiting this decision explicitly.

Auth

• All JIRA REST operations require JIRA_API_TOKEN
• JIRA_USER defaults to quay-devel@redhat.com
• If acli is installed, it is preferred and uses its own credentials
• Instance: https://redhat.atlassian.net

PR Conventions

Title Format (CI-enforced)

^(?:\[(?:redhat|mirror-registry)-[0-9]+\.[0-9]+\] )?(?:PROJQUAY-[0-9]+|QUAYIO-[0-9]+|NO-ISSUE): [a-z]+(?:\([^)]+\))?: .+$

Examples:

• PROJQUAY-1234: fix(api): add pagination to tag listing
• NO-ISSUE: chore: update dependencies
• [redhat-3.12] PROJQUAY-1234: fix(api): backport tag pagination
• [mirror-registry-3.0] PROJQUAY-1234: fix(omr): backport upgrade health check

Commit Message Format

<subsystem>: <what changed> (PROJQUAY-####)

<why this change was made>

Branch Naming

<type>/projquay-<number>-<kebab-case-description>

Where <type> matches the PR type: fix, feat, test, refactor, docs, chore.

Bot Ecosystem

Four bots interact with PRs. Understanding their roles helps respond correctly.

Bot	Role	Common Actions
openshift-ci-robot	JIRA lifecycle plugin	Validates ticket refs, transitions status (ASSIGNED→POST→MODIFIED), supports /cherrypick and /jira backport for backports
coderabbitai[bot]	AI code review	Runs 7 pre-merge checks with chill profile. Flags are generally valid — fix or reply with rationale
codecov[bot]	Coverage reporting	Reports coverage diffs. Project baseline ~72%
github-actions[bot]	CI results	Playwright reports, Surge preview links

CodeRabbit Pre-merge Checks

Check	What It Validates
Title check	PR title starts with PROJQUAY-XXXX or NO-ISSUE
Description check	Description is relevant to changes
Docstring Coverage	>= 80% on changed functions
Migration Safety at Scale	No unsafe operations on large tables
Migration Downgrade Exists	Every Alembic migration has a real downgrade()
N+1 Query Prevention	No new loop-based query patterns
Read Path Performance	No latency regressions on v2 registry read path

CI Jobs & Common Fixes

CI Job	Common Fix
Format / Pre-commit	pre-commit run --all-files
Unit tests	Run failing test locally, fix code
Types (mypy)	Fix type annotations
Registry tests	make registry-test locally
Playwright	cd web && pnpm run test:e2e
PR Lint	Fix PR title to match regex

Session Setup

All hooks are consolidated in .claude/settings.json — no manual setup required.

Hooks by Event

Event	Hook	Script/Command
SessionStart	Bootstrap + state restore	session-setup.sh — acli, pre-commit, gh auth, restores previous session state
UserPromptSubmit	Embargo check	check-embargo.sh — blocks embargoed JIRA tickets
UserPromptSubmit	JIRA ticket detection	detect-jira-ticket.sh — detects PROJQUAY/QUAYIO refs, suggests /jira or /start
PreToolUse (Bash)	Embargo check	check-embargo.sh — blocks JIRA commands on embargoed tickets
PreToolUse (git commit)	Pre-commit guard	Ensures pre-commit install runs before commit
PreToolUse (git commit)	Commit message hint	Warns if message doesn't match <subsystem>: <what> (PROJQUAY-####)
PreToolUse (gh pr create)	PR title validation	Blocks if title doesn't match CI-enforced regex
PostToolUse (gh pr create)	Poll reminder	Suggests /poll <PR#> after PR creation
PostToolUse (git push)	Target Version check	check-target-version.sh — warns if JIRA ticket missing Target Version
PreCompact	State save	save-session-state.sh — saves branch/ticket/PR to survive compaction
Stop	Next-step reminder	workflow-next-step.sh — suggests /pr, /poll, or /backport based on state

GitHub CLI Notes

• gh pr edit may fail with read:org scope errors on restricted tokens
• Fallback: use gh api repos/{owner}/{repo}/pulls/{number} -X PATCH -f title="..." -f body="..."
• Always verify gh auth status at session start

Backport Process

After a PR merges to master, if it needs to land on a release branch (a PROJQUAY/QUAYIO ticket with fixVersions naming one, or a NO-ISSUE PR whose change a release branch carries):

1. Run the sync check from Release Branch Model to confirm the target branch isn't the master-synced branch — do not cherry-pick to it
2. Post /jira backport <branch> as a comment on the merged PR for a PROJQUAY-titled PR, or /cherrypick <branch> for a NO-ISSUE or QUAYIO-titled PR — one branch per comment; to skip an intermediate branch, /jira backport a comma-separated list naming every branch from the current PR down to the target instead — this also clones the skipped branch's ticket, which a human then sets to Won't Do. /cherrypick has no such form: skip a branch by firing /cherrypick <target> alone on the last merged PR
3. openshift-ci-robot (via the cherrypick plugin) creates a new PR against the release branch
4. The JIRA lifecycle plugin clones on a successful /cherrypick apply only; /jira backport clones first, before any apply is attempted
5. Monitor the backport PR for CI results

For predecessor surveys, the cascade order, bot failures and manual ports, follow agent_docs/backports.md.