RFC: Release Management - Staging Repos & Promotion Workflow

[brandonrc]

Summary

A staging and promotion workflow that gates artifacts before they reach production repositories. Artifacts are pushed to a staging repo, validated against security and compliance policies, then promoted (or blocked) based on the results.

Problem

Currently, artifacts go directly into repositories with no intermediate validation step. Organizations need:

• Pre-production validation before artifacts are available for deployment
• Policy gates that block non-compliant artifacts automatically
• Approval workflows for manual review when needed
• Audit trail of what was promoted, when, and by whom

Proposed Solution

1. New Repository Type: Staging

pub enum RepositoryType {
    Local,      // Standard hosted repo
    Remote,     // Proxy to upstream
    Virtual,    // Aggregates multiple repos
    Staging,    // NEW: Holds artifacts pending promotion
}

Staging repo characteristics:

• Artifacts are uploaded here first (via normal push)
• Not included in virtual repo aggregation by default
• Artifacts are immutable once uploaded (no overwrites)
• Configurable retention policy for unpromoted artifacts

2. Promotion API

POST /api/v1/staging/{repo}/promote
{
  "artifact_path": "com/example/myapp/1.0.0/myapp-1.0.0.jar",
  "target_repo": "releases",
  "force": false  // Skip policy checks (requires admin)
}

Response:

{
  "status": "promoted",  // or "blocked", "pending_approval"
  "artifact": { ... },
  "policy_results": [
    { "policy": "cve-severity", "passed": true },
    { "policy": "license-compliance", "passed": true },
    { "policy": "artifact-age", "passed": false, "reason": "Artifact older than 30 days" }
  ],
  "promoted_at": "2024-01-15T10:30:00Z",
  "promoted_by": "user@example.com"
}

3. Policy Gates

Promotion is blocked if any policy fails:

Policy	Description
CVE Severity	Block if CRITICAL or HIGH CVEs (configurable threshold)
License Compliance	Block if non-approved licenses detected
Artifact Age	Block if artifact is older than X days
Required Signatures	Block if not signed or signature invalid
Manual Approval	Require human approval before promotion

4. Bulk Promotion

Promote all artifacts from a build:

POST /api/v1/staging/{repo}/promote-build
{
  "build_id": "build-123",
  "target_repo": "releases"
}

5. Promotion Rules (Optional)

Auto-promote when all policies pass:

promotion_rules:
  - name: auto-promote-to-releases
    source: staging-maven
    target: releases-maven
    auto_promote: true
    policies:
      - cve_max_severity: MEDIUM
      - allowed_licenses: [MIT, Apache-2.0, BSD-3-Clause]
      - require_signature: true

Workflow Example

Developer                Staging Repo              Policy Engine            Production Repo
    │                        │                          │                        │
    ├──push artifact────────►│                          │                        │
    │                        ├──trigger scan───────────►│                        │
    │                        │◄─────scan results────────┤                        │
    │                        │                          │                        │
    ├──request promotion────►│                          │                        │
    │                        ├──evaluate policies──────►│                        │
    │                        │◄─────all passed──────────┤                        │
    │                        ├──copy artifact──────────────────────────────────►│
    │◄──promotion success────┤                          │                        │

UI Integration

• Staging Dashboard - View pending artifacts and their policy status
• Promotion Button - One-click promote from artifact detail page
• Bulk Actions - Select multiple artifacts for batch promotion
• Policy Violations - Clear display of why an artifact is blocked
• Approval Queue - For manual approval workflows

Dependencies

This feature builds on existing work:

• artifact-keeper-cdg - CVE severity blocking (beads)
• artifact-keeper-fpq - License compliance blocking (beads)
• Dependency-Track integration (PR feat(security): OWASP Dependency-Track Integration #46)

Questions

1. Should staging repos support the same formats as local repos, or be format-specific?
2. Should promotion copy or move the artifact?
3. How should we handle promotion rollback?
4. Should there be a "quarantine" state for artifacts that fail policies?

Labels

enhancement release-management policies priority:p2

[brandonrc]

Implementation Status Update (Feb 2026)

Most of this RFC has been implemented. Here's the current state:

✅ Completed

Feature	Implementation	Details
Staging Repository Type	RepositoryType::Staging in models/repository.rs, migration 047	Includes promotion_target_id and promotion_policy_id fields
Promotion API (single artifact)	POST /api/v1/promotion/repositories/{key}/artifacts/{id}/promote	handlers/promotion.rs (650 LOC)
Bulk Promotion	POST /api/v1/promotion/repositories/{key}/promote	Same handler, per-artifact error handling
Promotion History	GET /api/v1/promotion/repositories/{key}/promotion-history	Full audit with who/when/policy results (JSONB)
Quality Gates (CRUD + evaluation)	Full CRUD + trigger + evaluate + suppress issues	handlers/quality_gates.rs (950 LOC)
Health Scores	Weighted: security 40%, quality 25%, license 20%, metadata 15%. Grades A-F.	services/quality_check_service.rs (1050 LOC)
CVE Severity Policy	Evaluates critical/high/medium counts against configurable thresholds	services/promotion_policy_service.rs (330 LOC)
License Compliance Policy	Checks against allowed/denied license lists	Same service
Staging UI	Repo list, detail view, promotion dialog, history, policy violations	artifact-keeper-web/src/app/(app)/staging/
Quality Check DB	quality_check_results, quality_check_issues, artifact_health_scores, repo_health_scores, quality_gates, quality_gate_evaluations	Migration 053

🔲 Remaining Work

1. Auto-promotion rules engine (P2) — Rule definitions (source → target, criteria), periodic scheduler, event-driven triggers on scan completion
2. Manual approval workflow (P2) — Approval queue, approve/reject endpoints, reviewer role permissions, notification hooks
3. Age-based promotion gates (P3) — Minimum time in staging, maximum artifact age, configurable thresholds
4. Signature verification gates (P3) — GPG/cosign signature validation before promotion
5. Artifact rejection workflow (P3) — Explicit reject action with reason, uploader notification, rejection history

Answers to Original Questions

1. Should staging repos support the same formats as local repos?

Format-specific. Staging repos have a format field. Promotion validates source/target formats match.

2. Should promotion copy or move the artifact?

Copy. Content is copied from staging to target storage. Original remains in staging (immutable).

3. How should we handle promotion rollback?

Not yet implemented. Promotion history provides audit trail but no automated rollback. Could be part of auto-promotion rules.

4. Should there be a quarantine state?

Partially addressed. Quality gates can block artifacts. The rejection workflow feature will add explicit quarantine with reason tracking.

[brandonrc]

Final Status Update — Closing

All core features from this RFC are now implemented and merged. Here's the complete picture:

✅ Fully Implemented & Merged

Feature	PR	Details
Staging Repository Type	Various	RepositoryType::Staging with promotion_target_id, promotion_policy_id
Single Artifact Promotion	PR #151	POST /api/v1/promotion/repositories/{key}/artifacts/{id}/promote
Bulk Promotion	PR #151	POST /api/v1/promotion/repositories/{key}/promote with artifact_ids array
Promotion History & Audit	PR #151	Full audit with who/when/policy results, status filter (promoted/rejected/pending_approval)
CVE Severity Policy Gates	PR #151	Configurable thresholds, evaluates critical/high/medium counts
License Compliance Policy	PR #151	Allowed/denied license lists, unknown license handling
Age-Based Promotion Gates	PR #151	min_staging_hours and max_artifact_age_days on scan policies
Signature Verification Gates	PR #151	require_signature checks signing config and audit trail
Manual Approval Workflow	PR #151	Request/approve/reject endpoints, promotion_approvals table, pending queue
Artifact Rejection Workflow	PR #151	POST .../reject with reason, rejection status in history
Quality Gates (CRUD + eval)	Earlier PRs	Full CRUD, trigger, evaluate, suppress issues
Health Scores	Earlier PRs	Weighted composite (security 40%, quality 25%, license 20%, metadata 15%)
Staging UI	artifact-keeper-web	Repo list, detail view, promotion dialog, history, policy violations
Documentation	site PR #7	Health scores, quality gates, staging & promotion docs

🔲 Remaining (tracked as beads)

Feature	Bead	Priority	Notes
Auto-promotion rules engine	artifact-keeper-o39	P2	Rule definitions, scheduler, event-driven triggers
Approval queue UI	artifact-keeper-18m	P2	Frontend for manual approval review
Rejection workflow UI	artifact-keeper-qiw	P3	Reject button + reason modal in staging UI
Promote-by-build	artifact-keeper-zis	P3	Bulk promote by build ID tag
Promotion rollback	artifact-keeper-sj3	P4	Undo a promotion (remove from target repo)
Staging retention policy	artifact-keeper-hoo	P4	Auto-cleanup unpromoted artifacts after X days

The remaining items are incremental improvements on a fully working system. The core workflow (upload → stage → evaluate → promote/reject with full audit) is complete and in production.

Closing this RFC as implemented.