Component Governance and Change Management

This guide covers governance policies, approval processes, and change management for CI/CD components across 70+ projects.

Governance Model

Stakeholders

Component Owners

• Platform Team: Overall component strategy and architecture
• Component Maintainers: Day-to-day maintenance and releases
• Domain Experts: Technology-specific guidance (Docker, K8s, etc.)

Component Consumers

• Project Teams: 70+ projects using components
• Engineering Managers: Approval for breaking changes
• Security Team: Security review and compliance

Responsibility Matrix (RACI)

Legend: R = Responsible, A = Accountable, C = Consulted, I = Informed

Change Classification

Change Types

Type 1: Non-Breaking Changes (Patch)

Examples:

• Bug fixes
• Performance improvements
• Documentation updates
• Internal refactoring
• Security patches (non-breaking)

Approval Required: Component Maintainer only Testing: Automated tests + smoke test Rollout: Automatic (projects using ~X.Y) Communication: Release notes

Type 2: Backward-Compatible Features (Minor)

Examples:

• New optional inputs (with defaults)
• New components
• New features (opt-in)
• Deprecation warnings (but keeping functionality)

Approval Required: Component Maintainer + Platform Team Testing: Full test suite + beta testing (3-5 projects) Rollout: Gradual (2-4 weeks) Communication: Announcement + documentation

Type 3: Breaking Changes (Major)

Examples:

• Removing/renaming inputs
• Changing input types
• Removing components
• Changing default behavior
• Removing deprecated features

Approval Required: All stakeholders (RACI matrix) Testing: Comprehensive testing + beta (10+ projects) Rollout: Phased (6-12 weeks) Communication: Early announcement (4+ weeks) + migration guide + support

Type 4: Emergency Security Patches

Examples:

• Critical security vulnerabilities (CVE)
• Zero-day exploits
• Data leak prevention

Approval Required: Security Team + Platform Team Testing: Expedited security testing Rollout: Immediate (with communication) Communication: Security advisory + mandatory update notice

Approval Processes

Patch Release Process

Timeline: 1-3 days

graph LR
    A[Bug Report] --> B[Fix Developed]
    B --> C[PR Created]
    C --> D[Automated Tests]
    D --> E{Tests Pass?}
    E -->|No| B
    E -->|Yes| F[Maintainer Review]
    F --> G[Merge + Tag]
    G --> H[Release]
    H --> I[Notify Users]

Steps:

1. Issue Created: Bug reported in component repository
2. Fix Developed: Maintainer creates fix
3. PR Submitted: Pull request with fix
4. Automated Testing: CI/CD runs full test suite
5. Maintainer Review: Code review by maintainer
6. Merge: Merge to main branch
7. Tag: Create patch version tag (e.g., 2.1.5)
8. Release: Automated release to catalog
9. Notify: Post in #ci-cd-updates channel

Approval Matrix:

Minor Release Process

Timeline: 1-2 weeks

graph TB
    A[Feature Proposal] --> B[Design Review]
    B --> C[Implementation]
    C --> D[PR + Tests]
    D --> E[Code Review]
    E --> F[Platform Team Approval]
    F --> G[Beta Release]
    G --> H[Beta Testing]
    H --> I{Issues Found?}
    I -->|Yes| C
    I -->|No| J[Stable Release]
    J --> K[Gradual Rollout]

Steps:

1. Proposal: Feature request or enhancement issue
2. Design Review: Platform team reviews design
3. Implementation: Develop feature with tests
4. PR Submitted: Pull request with comprehensive tests
5. Code Review: Maintainer + domain expert review
6. Platform Approval: Platform team approves feature
7. Beta Release: Tag beta version (e.g., 2.2.0-beta.1)
8. Beta Testing: 3-5 projects test beta version
9. Issue Resolution: Fix any issues found in beta
10. Stable Release: Tag stable version (e.g., 2.2.0)
11. Gradual Rollout: Phased rollout over 2-4 weeks

Approval Matrix:

Major Release Process

Timeline: 4-12 weeks

graph TB
    A[Breaking Change RFC] --> B[Stakeholder Review]
    B --> C{Approved?}
    C -->|No| D[Revise or Reject]
    C -->|Yes| E[Early Announcement]
    E --> F[Implementation]
    F --> G[Alpha Release]
    G --> H[Alpha Testing]
    H --> I[Beta Release]
    I --> J[Beta Testing]
    J --> K[RC Release]
    K --> L[Final Testing]
    L --> M[Stable Release]
    M --> N[Migration Support]
    N --> O[Deprecate Old Version]

Steps:

1. RFC: Request for Comments document created
2. Stakeholder Review: All stakeholders review and comment
3. Approval Meeting: Decision meeting with all RACI stakeholders
4. Early Announcement: 4+ weeks before release
5. Implementation: Develop with migration guide
6. Alpha Release: Internal testing only (e.g., 3.0.0-alpha.1)
7. Alpha Testing: Test projects + component maintainers
8. Beta Release: Early adopters (e.g., 3.0.0-beta.1)
9. Beta Testing: 10+ projects test beta
10. RC Release: Release candidate (e.g., 3.0.0-rc.1)
11. Final Testing: Production-like testing
12. Stable Release: Tag and release 3.0.0
13. Migration Support: Help projects migrate
14. Deprecation: Old version enters deprecation cycle

Approval Matrix:

Emergency Security Patch Process

Timeline: Hours to 1 day

graph LR
    A[Security Issue] --> B[Security Team Review]
    B --> C[Critical?]
    C -->|Yes| D[Expedited Fix]
    C -->|No| E[Normal Process]
    D --> F[Security Testing]
    F --> G[Platform Approval]
    G --> H[Immediate Release]
    H --> I[Security Advisory]
    I --> J[Mandatory Update]

Steps:

1. Security Report: CVE or security issue reported
2. Triage: Security team assesses severity
3. Critical Path: If critical, expedited process
4. Fix Development: Security fix implemented
5. Security Testing: Verify fix without disclosing vulnerability
6. Platform Approval: Platform team aware and approves
7. Release: Immediate patch release (all supported versions)
8. Security Advisory: Public disclosure with fix
9. Mandatory Update: Alert all projects to update immediately

Approval Matrix:

Request for Comments (RFC) Template

RFC Document Structure

# RFC: [Component Change Title]

**RFC Number:** RFC-2026-001
**Status:** Draft | Review | Approved | Rejected
**Author:** @username
**Created:** 2026-01-08
**Updated:** 2026-01-15
**Approvers:** @platform-team @security-team

## Summary

One-paragraph explanation of the proposed change.

## Motivation

Why are we doing this? What problem does it solve?

## Proposed Change

### What Changes

Detailed description of the change:
- What components are affected
- What inputs/outputs change
- What behavior changes

### Breaking Changes

Explicit list of all breaking changes:
- [ ] Removed input: `old_name`
- [ ] Renamed input: `cluster_name`  `cluster`
- [ ] Changed default: `timeout` now defaults to 300 (was 60)

### Migration Path

How will users migrate?
- Step-by-step migration guide
- Automated migration tools (if any)
- Backward compatibility shims (if any)

## Impact Analysis

### Affected Projects

- **Total projects affected:** 45/70
- **Critical projects:** 5
- **Standard projects:** 30
- **Low-priority projects:** 10

### Effort Estimate

- **Component development:** 2 weeks
- **Testing:** 2 weeks
- **Migration support:** 4 weeks
- **Total rollout:** 12 weeks

## Alternatives Considered

### Alternative 1: [Description]

**Pros:**
- ...

**Cons:**
- ...

**Decision:** Rejected because...

### Alternative 2: [Description]

**Pros:**
- ...

**Cons:**
- ...

**Decision:** Rejected because...

## Timeline

- **RFC Review:** 2026-01-08 to 2026-01-22 (2 weeks)
- **Implementation:** 2026-01-23 to 2026-02-06 (2 weeks)
- **Beta Testing:** 2026-02-07 to 2026-02-21 (2 weeks)
- **Stable Release:** 2026-02-22
- **Rollout:** 2026-02-22 to 2026-05-22 (12 weeks)
- **Deprecation:** 2026-05-23
- **EOL:** 2026-08-22 (3 months after deprecation)

## Success Metrics

- [ ] 95% of projects migrated within 12 weeks
- [ ] <5% rollback rate
- [ ] <3% pipeline failure rate increase
- [ ] Migration guide rated 4+/5 by users

## Stakeholder Sign-Off

- [ ] Platform Team: @platform-lead
- [ ] Component Maintainers: @maintainer1 @maintainer2
- [ ] Security Team: @security-lead
- [ ] Engineering Managers: @em1 @em2 @em3

## Discussion

### Open Questions

1. Should we provide backward compatibility shim?
2. What's the migration deadline for critical projects?

### Comments

_Add comments here_

Change Request Workflow

Creating a Change Request

# Create RFC issue in component repository
glab issue create \
  --repo my-org/gitlab_components \
  --title "RFC: Rename cluster_name to cluster" \
  --label "rfc,breaking-change" \
  --template rfc.md

RFC Review Process

Week 1-2: Review Period

1. Day 1: RFC published
2. Day 1-14: Stakeholder review and comments
3. Day 7: Review meeting with stakeholders
4. Day 14: Final approval or rejection

Stakeholder Actions:

• Comment: Add feedback on RFC
• Approve: Add thumbs-up reaction
• Block: Add stop sign emoji + explanation
• Request Changes: Comment with required changes

Approval Criteria

Minor Release:

• Platform team approval
• 2+ maintainer reviews
• All automated checks pass
• No blocking comments

Major Release:

• All RACI stakeholders approve
• Migration guide completed
• 3+ project teams reviewed
• Security team approval
• No blocking comments
• Communication plan approved

Communication Standards

Announcement Template

Minor Release:

Subject: [Components] New version 2.2.0 released

# Component Version 2.2.0 Available

A new minor version with enhancements is now available.

## What's New
-  New Helm deployment component
-  30% faster Docker builds
-  Enhanced security scanning

## No Breaking Changes
This is a backward-compatible release. Existing pipelines continue to work.

## How to Upgrade
Update your .gitlab-ci.yml component version:
```yaml
component: gitlab.com/org/comp/deploy@2.2.0

Documentation

• Release notes: https://...
• Component docs: https://...

Questions?

Slack: #gitlab-components

**Major Release:**

```markdown
Subject: [Components] BREAKING CHANGES in v3.0.0 - Action Required

#  Component v3.0.0 with Breaking Changes

Version 3.0.0 introduces breaking changes. Please read carefully.

## Breaking Changes

### 1. Input Renamed: cluster_name  cluster

**Before:**
```yaml
inputs:
  cluster_name: production

After:

inputs:
  cluster: production

2. Removed: legacy-deploy component

Use k8s-deploy instead.

Timeline

• Today: v3.0.0 released
• Feb 22 - May 22: Gradual rollout (12 weeks)
• May 23: v2.x deprecated
• Aug 22: v2.x EOL (no support)

Migration Required

All projects must migrate before Aug 22, 2026.

Migration Guide: https://...

Support

• Migration support: @platform-team
• Questions: #gitlab-components Slack
• Issues: https://gitlab.com/org/comp/issues

Your Projects Affected

• project-a (High priority)
• project-b (High priority)
• project-c (Standard)

**Security Advisory:**

```markdown
Subject: [SECURITY] Critical update for gitlab_components - Update immediately

#  Security Advisory: Critical Update Required

A critical security vulnerability has been fixed. Update immediately.

## Severity: CRITICAL
CVE-2026-12345 - Remote code execution in docker-build component

## Affected Versions
- 2.0.0 through 2.1.5
- 3.0.0 through 3.0.2

## Fixed Versions
- 2.1.6 (patch for 2.x)
- 3.0.3 (patch for 3.x)

## Action Required

Update component version in .gitlab-ci.yml immediately:

```yaml
# For projects on 2.x:
component: gitlab.com/org/comp/docker-build@2.1.6

# For projects on 3.x:
component: gitlab.com/org/comp/docker-build@3.0.3

Vulnerability Details

[Details disclosed after grace period]

Timeline

• Now: Patches released
• Jan 15: Full disclosure (7 days grace period)

Compliance

Security team will audit all projects on Jan 10.

Questions?

Contact security team immediately: security@company.com

## Deprecation Policy

### Deprecation Announcement

**Minimum Notice: 90 days**

```markdown
# Deprecation Notice: Component v2.0.x

**Deprecated:** v2.0.x series
**Reason:** Superseded by v3.0.x with significant improvements
**Replacement:** v3.0.x
**Notice Date:** 2026-01-08
**EOL Date:** 2026-04-08 (90 days)
**Support Status:** Security patches only

## What Happens

- **Now - Apr 8:** Security patches only
- **Apr 8:** No more support or patches
- **Apr 8+:** Components still work, but unsupported

## Action Required

Migrate to v3.0.x before Apr 8, 2026.

**Migration Guide:** https://...

## Projects Still Using v2.0.x

We'll reach out to these projects individually:
- legacy-project-1 (Owner: @alice)
- legacy-project-2 (Owner: @bob)
- old-experiment (Owner: @carol)

Deprecation Enforcement

Phase 1: Soft Deprecation (Days 0-60)

• Warning in CI/CD output
• Slack reminders
• Email to project owners

# Component adds warning to pipeline
deprecated-warning:
  stage: .pre
  script:
    - |
      echo " WARNING "
      echo "You are using deprecated component version 2.0.x"
      echo "Support ends: 2026-04-08"
      echo "Please migrate to v3.0.x: https://..."
  allow_failure: true

Phase 2: Hard Deprecation (Days 61-90)

• MR approval blocked for deprecated versions
• Compliance dashboard shows violations
• Weekly reminders

# GitLab approval rule
compliance-check:
  stage: validate
  script:
    - check-component-versions.sh
  rules:
    - if: $CI_MERGE_REQUEST_IID
  allow_failure: false  # Block MR if using deprecated

Phase 3: EOL (Day 90+)

• No support
• No security patches
• Components removed from catalog (optional)

Metrics and Reporting

Component Health Dashboard

Track key metrics:

interface ComponentHealth {
  total_projects: number;
  version_distribution: {
    [version: string]: {
      count: number;
      percentage: number;
    };
  };
  compliance: {
    using_latest: number;
    using_supported: number;
    using_deprecated: number;
    using_eol: number;
  };
  adoption_velocity: {
    avg_days_to_upgrade: number;
    fastest: number;
    slowest: number;
  };
  quality: {
    pipeline_success_rate: number;
    rollback_rate: number;
    issue_count: number;
  };
}

Weekly Report

# Component Health Report - Week of 2026-01-08

## Version Distribution

| Version | Projects | % | Status |
|---------|----------|---|--------|
| 3.0.0 | 15 | 21% | Current |
| 2.1.6 | 50 | 71% | Supported |
| 2.0.5 | 5 | 7% |  Deprecated |

## Compliance

-  65/70 (93%) using supported versions
-  5/70 (7%) using deprecated versions
-  Target: 100% by 2026-02-01

## Blockers

- project-legacy-1: Waiting for security approval
- project-legacy-2: Custom pipeline needs refactoring

## Action Items

- [ ] Follow up with project-legacy-1 owner
- [ ] Provide migration support to project-legacy-2

Best Practices

DO:

1. Document everything - RFC for major changes
2. Communicate early - 4+ weeks for breaking changes
3. Test thoroughly - Beta testing with real projects
4. Provide migration guides - Step-by-step instructions
5. Support users - Help with migrations
6. Track metrics - Monitor adoption and issues
7. Enforce policies - Block non-compliant changes
8. Review regularly - Quarterly governance review

DON'T:

1. Don't skip approvals - Follow the process
2. Don't rush major changes - Take time to get it right
3. Don't surprise users - Always communicate
4. Don't ignore feedback - Listen to beta testers
5. Don't deprecate abruptly - Give 90 days minimum
6. Don't leave projects behind - Provide migration support
7. Don't ignore security - Security reviews are mandatory
8. Don't forget rollback plans - Always have a backup plan

Next Steps

• Patterns: Common component design patterns
• Testing: Component testing strategies
• Multi-Project Strategy: Managing 70+ projects

References

• GitLab Deprecation Guidelines
• GitLab Rollout Plans
• Breaking Changes Policy