Source Code Delivery (PoC)

1 · The problem

2 · Architecture

Jira is the system of record — the plannable, auditable surface. n8n is the glue at the two edges: it fans intake out into the structure, and it syncs GitLab MR state onto the tickets. Jira Automation handles the in-Jira assignee flips.

flowchart TD
  Dev(["Developer"]) -->|fills intake Form| RR["Review Request
(intake record)"]
  RR -->|n8n fan-out| Epic[["Delivery — Epic"]]
  Epic --> CR1["Code Review · MR a"]
  Epic --> CR2["Code Review · MR b"]
  Epic --> CR3["Code Review · MR c"]
  Epic --> INT["Integration
(1 per delivery)"]
  GL{{"GitLab MR webhooks"}} -->|n8n sync| CR1
  GL -->|n8n sync| CR2
  GL -->|n8n sync| CR3
  CR1 -.->|all Approved → rollup| INT
  CR2 -.-> INT
  CR3 -.-> INT
  classDef rec fill:#eef,stroke:#88a,color:#223;
  classDef int fill:#e8f6ee,stroke:#5aa97a,color:#143;
  class RR rec; class INT int;

3 · Issue model

Three tiers plus a per-delivery integration item. The Form can only create the task-level Review Request; n8n reads it and builds the rest.

4 · Custom fields

Contributors must have Jira accounts, so Assignee is always a real, actionable user. Role fields (Developer/Reviewer/Approver/Integrator) are created single-user — the instance's existing multi-user Reviewers/Approvers fields are the wrong cardinality for the flip.

5 · Code Review workflow

One state = one person's court, which is what the Assignee auto-flip keys off. A change request at either gate returns the ball to the Developer and re-enters via re-review.

stateDiagram-v2
  [*] --> ToReview: n8n creates
  ToReview --> InReview: triage done (Reviewer + Approver set)
  InReview --> InApproval: reviewer approves
  InReview --> ChangesRequested: reviewer requests changes
  InApproval --> Approved: approver approves
  InApproval --> ChangesRequested: approver requests changes
  ChangesRequested --> InReview: dev delivers (always re-review)
  Approved --> ChangesRequested: reopen (integration failure)
  ToReview --> Cancelled
  InReview --> Cancelled
  ChangesRequested --> Cancelled
  InApproval --> Cancelled
  Approved --> [*]
  Cancelled --> [*]

6 · Integration workflow

One Integration ticket per delivery, born with the Epic in Waiting for Review, auto-promoted when the whole delivery is approved. Same project, separate board, so the integration team plans independently.

stateDiagram-v2
  [*] --> WaitingForReview: created with the Epic
  WaitingForReview --> ReadyForIntegration: all Code Review children Approved (n8n)
  ReadyForIntegration --> Integrating: integrator starts
  Integrating --> Integrated: n8n — all delivery MRs merged in GitLab
  Integrating --> WaitingForReview: failure → reopen Code Review item(s)
  Integrated --> [*]

9 · The two engines

Fan-out — n8n, on Review Request submit

• Create the Delivery Epic (name = title, description = context).
• Create the Integration ticket in Waiting for Review, linked to the Epic.
• For each MR URL line: GET the GitLab MR → create a Code Review item (parent = Epic; Developer, GitLab Project, MR IID, MR URL + remote link, Target Branch, Release Track, fixVersion), in To Review, default-assigned to the triage lead.
• Write the new Code Review key back to the MR title as a suffix (e.g. … (SCDX-1234)), idempotently — lights up GitLab's native Jira Dev panel and lets sync resolve by title. Needs a GitLab write/api token; per-MR key, not the Epic's.
• Link the Review Request → Epic and mark it triaged.

Sync — n8n, GitLab → Jira

• Resolve the ticket from a webhook by the SCDX-… key in the MR title (primary), falling back to JQL on GitLab Project + MR IID.
• Map GitLab events → Code Review transitions (gate mapping deferred — §10).
• On Code Review → Approved: if all siblings Approved, move the Integration ticket → Ready for Integration.
• On a GitLab merge event: stamp MR merged at on the Code Review item, then roll up — when every child is merged-or-Cancelled (≥1 merged), n8n moves the Integration ticket → Integrated.

Assignee flips — Jira Automation (UI; no public REST)

Deadlines, SLA & escalation — n8n cron

No JSM = no native SLA engine, so n8n replicates it. Reaction time = age of the current status (one state = one role's court), checked against a priority × waiting-state matrix (tunable n8n config):

10 · Open items & risks

• Gate mapping (deferred). GitLab approvals are flat; our gates are sequential. Leaning toward matching by user identity (GitLab approver → Jira account → Reviewer or Approver?), which needs a GitLab↔Jira user map but no GitLab project changes.
• Infra. Webhook on prpl-foundation/prplos needs Maintainer; a GitLab write/api token is needed for the MR-title writeback; n8n needs a reachable endpoint; the GitLab↔Jira user map must exist.
• MR added after fan-out shifts the “all-approved”/“all-merged” denominator — n8n re-runs for the new MR and reopens the Integration ticket if it had advanced.
• All MRs abandoned (every Code Review Cancelled) → the Integration ticket ends Cancelled, not Integrated.
• “Changes requested” signal from GitLab needs pinning down during n8n work.
• Account provisioning for contributors without Jira accounts (2958 free seats).

11 · Build plan

1. Phase 1 — Foundation (REST): project SCDX (gh-scrum-template) + single-user role fields + GitLab/Blocked-reason fields + versions. Reversible.
2. Phase 2 — Process: create statuses Changes Requested / In Approval, both workflows + schemes + the To-Review→In-Review validator. ⚠ status/scheme/automation REST support uncertain — probe, fall back to UI.
3. Phase 3 — Form (Forms REST, experimental): the intake form.
4. Phase 4 — Glue: Assignee-flip rules R1–R5 (REST probe, else UI) + the tested n8n→Jira REST contract (fan-out incl. title writeback, sync, SLA cron).

12 · Decision log