platform-integration

Original source / Raw SKILL.md

---
name: platform-integration
description: Use when implementing CMMI processes in GitHub or Azure DevOps, migrating between platforms, or establishing traceability/compliance on GitHub/Azure - platform-specific process guidance
---

# Platform Integration

## Overview

This skill provides concrete implementation guidance for mapping CMMI process areas to GitHub and Azure DevOps platform features.

**Core principle**: CMMI defines WHAT processes are required. This skill shows HOW to implement them in your platform with production-ready configurations.

**Platforms covered**:
- **GitHub** - Issues, PRs, Actions, Projects for CMMI implementation
- **Azure DevOps** - Work Items, Repos, Pipelines, Boards for CMMI implementation

**Reference**: See `docs/sdlc-prescription-cmmi-levels-2-4.md` for CMMI process area definitions.

---

## When to Use

Use this skill when:
- Implementing requirements traceability in GitHub/Azure DevOps
- Setting up CI/CD pipelines with CMMI quality gates
- Configuring branch protection and code review policies
- Automating metrics collection for measurement
- Creating audit trails for compliance
- Migrating between platforms (GitHub ↔ Azure DevOps)
- Setting up risk tracking in work items
- Integrating CMMI processes with platform automation

**Do NOT use for**:
- CMMI process definitions → Use sdlc-prescription document
- Process-agnostic guidance → Use requirements-lifecycle, design-and-build, etc.
- Non-GitHub/Azure DevOps platforms → Adapt principles to your platform

---

## Quick Reference: CMMI → Platform Mapping

| CMMI Process Area | GitHub Feature | Azure DevOps Feature | Reference Sheet |
|-------------------|----------------|----------------------|-----------------|
| **REQM (Requirements Management)** | Issues, Projects, Labels | Work Items, Queries, Backlogs | github-requirements.md, azdo-requirements.md |
| **CM (Configuration Management)** | Branch Protection, CODEOWNERS | Branch Policies, Required Reviewers | github-config-mgmt.md, azdo-config-mgmt.md |
| **VER + VAL + PI (Quality)** | Actions, Status Checks, PRs | Pipelines, Gates, Test Plans | github-quality-gates.md, azdo-quality-gates.md |
| **MA (Measurement)** | Insights, API, Actions | Analytics, Dashboards, OData | github-measurement.md, azdo-measurement.md |
| **DAR + RSKM (Governance)** | Discussions, Wiki, Issues | Wiki, Custom Work Items | github-audit-trail.md, azdo-audit-trail.md |

---

## Platform Selection Criteria

### When to Use GitHub

**Best for**:
- Open source projects (public repositories)
- Developer-centric workflows (PRs, code review focus)
- Lightweight process (startups, small teams)
- Git-native workflows (GitFlow, GitHub Flow, trunk-based)
- Strong Actions ecosystem for automation
- Integration with third-party dev tools

**Strengths**:
- ✅ Excellent developer experience
- ✅ Free for public repositories
- ✅ Strong community and marketplace
- ✅ Simple, intuitive UI
- ✅ Best-in-class code review
- ✅ Actions for flexible automation

**Limitations**:
- ❌ Limited work item hierarchy (no built-in epic → feature → story)
- ❌ Basic project management features
- ❌ Limited reporting/analytics (compared to Azure DevOps)
- ❌ No built-in test management
- ❌ Weaker audit logging (for compliance)

**CMMI Maturity**:
- **Level 2**: Fully capable
- **Level 3**: Fully capable with third-party tools
- **Level 4**: Limited (external analytics tools needed)

### When to Use Azure DevOps

**Best for**:
- Enterprise projects (regulated industries)
- Complex work item hierarchies (epic → feature → story)
- Integrated ALM (requirements → design → test → deploy)
- Advanced reporting and analytics
- Compliance and audit requirements
- Microsoft stack integration (.NET, Azure)

**Strengths**:
- ✅ Rich work item management
- ✅ Built-in test management
- ✅ Advanced analytics and reporting
- ✅ Audit logging for compliance
- ✅ Integrated CI/CD with environments
- ✅ Customizable processes

**Limitations**:
- ❌ Steeper learning curve
- ❌ More complex to configure
- ❌ Less developer-friendly UX
- ❌ Weaker community/marketplace
- ❌ Limited free tier

**CMMI Maturity**:
- **Level 2**: Fully capable
- **Level 3**: Fully capable (native features)
- **Level 4**: Fully capable (native analytics, baselines)

### Hybrid Scenarios

**Common patterns**:
- **GitHub + Azure DevOps Boards**: Code in GitHub, work tracking in Azure DevOps
- **Azure DevOps + GitHub Actions**: Work items in Azure DevOps, CI/CD in GitHub
- **Multi-Platform**: Microservices split across platforms

**Integration options**:
- Azure Boards + GitHub integration (official)
- Zapier/Make for workflow automation
- API-based synchronization
- Third-party tools (Unito, Workato)

---

## Reference Sheets

The following reference sheets provide detailed, production-ready implementation guidance for each platform.

### GitHub Integration (5 Sheets)

#### 1. Requirements Management in GitHub

**When to use**: Implementing REQM (Requirements Management) in GitHub

→ See [github-requirements.md](./github-requirements.md)

**Covers**:
- Issue templates for requirements with traceability IDs
- Label strategy for requirement types and states
- Projects/Milestones for requirement organization
- PR linking patterns (`Implements #123`, `Closes #456`)
- Traceability matrix automation
- Requirement change management workflow
- Level 2/3/4 scaling requirements
- Audit trail for requirements changes

#### 2. Configuration Management in GitHub

**When to use**: Implementing CM (Configuration Management) in GitHub

→ See [github-config-mgmt.md](./github-config-mgmt.md)

**Covers**:
- Branch protection rules (required reviewers, status checks)
- CODEOWNERS file format and enforcement
- Git workflow comparison (GitFlow, GitHub Flow, trunk-based)
- Merge strategies (squash, merge, rebase) trade-offs
- Baseline management (tags, releases)
- Release management automation
- Emergency hotfix procedures
- Configuration as code (settings.yml, Terraform)

#### 3. Quality Gates in GitHub

**When to use**: Implementing VER, VAL, PI (Verification, Validation, Integration) in GitHub

→ See [github-quality-gates.md](./github-quality-gates.md)

**Covers**:
- GitHub Actions workflows for CI/CD
- Multi-stage pipelines (build → test → deploy)
- Required status checks configuration
- Test execution and coverage enforcement
- Deployment environments and protection rules
- Approval workflows for production
- Quality metrics collection
- Integration testing strategies

#### 4. Measurement in GitHub

**When to use**: Implementing MA (Measurement & Analysis) in GitHub

→ See [github-measurement.md](./github-measurement.md)

**Covers**:
- GitHub Insights and API for metrics
- DORA metrics implementation (all 4 metrics)
- Metrics collection automation (Actions)
- Dashboard creation (external tools integration)
- Historical baseline tracking
- Statistical process control (Level 4)
- Alerting on metric thresholds
- Custom metrics for project needs

#### 5. Audit Trail in GitHub

**When to use**: Compliance and audit requirements in GitHub

→ See [github-audit-trail.md](./github-audit-trail.md)

**Covers**:
- Commit history as audit log
- PR review history retention
- Issue comment trails
- Action logs and artifact retention
- Compliance mappings (SOC 2, ISO, GDPR)
- Audit report generation
- Data retention policies
- Access control for sensitive data

### Azure DevOps Integration (5 Sheets)

#### 6. Requirements Management in Azure DevOps

**When to use**: Implementing REQM (Requirements Management) in Azure DevOps

→ See [azdo-requirements.md](./azdo-requirements.md)

**Covers**:
- Work item types (Epic, Feature, User Story, Requirement)
- Custom fields for traceability
- Backlogs and boards configuration
- Queries for requirement reporting
- Multi-level hierarchy management
- Change request workflow
- Requirement baseline management
- Integration with test plans

#### 7. Configuration Management in Azure DevOps

**When to use**: Implementing CM (Configuration Management) in Azure DevOps

→ See [azdo-config-mgmt.md](./azdo-config-mgmt.md)

**Covers**:
- Azure Repos branch policies
- Required reviewers and CODEOWNERS
- Linked work items enforcement
- Merge strategies and build validation
- Release management with environments
- Baseline tagging automation
- TFVC migration (if needed)
- Configuration as code (YAML pipelines)

#### 8. Quality Gates in Azure DevOps

**When to use**: Implementing VER, VAL, PI (Verification, Validation, Integration) in Azure DevOps

→ See [azdo-quality-gates.md](./azdo-quality-gates.md)

**Covers**:
- Azure Pipelines multi-stage YAML
- Quality gates between stages
- Test Plans integration
- Approval workflows and gates
- Deployment environments
- Release management strategies
- Test execution and reporting
- Quality metrics tracking

#### 9. Measurement in Azure DevOps

**When to use**: Implementing MA (Measurement & Analysis) in Azure DevOps

→ See [azdo-measurement.md](./azdo-measurement.md)

**Covers**:
- Analytics views and widgets
- Dashboard creation and customization
- OData queries for custom reports
- PowerBI integration
- DORA metrics implementation
- Process baselines (Level 3/4)
- Historical data analysis
- Statistical process control

#### 10. Audit Trail in Azure DevOps

**When to use**: Compliance and audit requirements in Azure DevOps

→ See [azdo-audit-trail.md](./azdo-audit-trail.md)

**Covers**:
- Work item history and revisions
- Audit logs (admin actions, permission changes)
- Pipeline run history retention
- Compliance features (data residency, encryption)
- Audit report generation
- Retention policies configuration
- Access control and permissions
- Regulatory compliance (FDA, ISO, SOC 2)

---

## Common Mistakes

| Mistake | Why It Fails | Better Approach |
|---------|--------------|-----------------|
| **Treating platform as CMMI-aware** | Platforms don't enforce CMMI; you configure enforcement | Map each CMMI practice to platform feature explicitly |
| **Using platform defaults** | Defaults are permissive (no quality gates, no reviews) | Configure branch protection, required checks, policies |
| **Manual traceability** | Spreadsheet traceability becomes stale immediately | Automate with issue/PR links, work item queries, API |
| **Skipping audit trail setup** | Compliance failures discovered during audit | Configure retention, access logs, history from project start |
| **One-size-fits-all configuration** | Level 2 project gets Level 4 overhead (or vice versa) | Scale configuration based on CMMI target level |
| **Forgetting baselines** | No way to freeze requirements or code for releases | Implement baseline tagging, release branches, milestone freezes |
| **Ignoring platform limitations** | GitHub weak at test management; Azure DevOps weak at code review | Use hybrid approach or third-party tools for gaps |
| **No verification automation** | Traceability breaks without detection | Scheduled checks for orphaned requirements, missing links |
| **Generic metrics** | Collecting data nobody uses | GQM approach: Goal → Question → Metric (actionable only) |
| **Missing cross-process links** | Requirements don't link to risks; tests don't link to design | Document integration patterns in configuration |

---

## Integration with Other Skills

| When You're Doing | Also Use | For |
|-------------------|----------|-----|
| Platform setup for requirements | `requirements-lifecycle` | REQM/RD process definitions |
| Platform setup for CI/CD | `design-and-build` | TS/PI process definitions |
| Platform setup for testing | `quality-assurance` | VER/VAL process definitions |
| Platform setup for metrics | `quantitative-management` | MA/QPM metrics definitions |
| Platform selection decision | `governance-and-risk` | Decision analysis for platform choice |
| Initial platform adoption | `lifecycle-adoption` | Incremental rollout strategy |

---

## Next Steps

1. **Determine your platform**: GitHub, Azure DevOps, or hybrid
2. **Identify CMMI process area**: Which process (REQM, CM, VER, etc.) are you implementing?
3. **Check target maturity level**: Level 2, 3, or 4 (from CLAUDE.md or user)
4. **Load reference sheet**: Read platform-specific implementation guide
5. **Apply configuration**: Use production-ready examples from reference sheet
6. **Verify setup**: Run verification checks for traceability, quality gates, audit trail
7. **Integrate processes**: Link requirements → code → tests → metrics

**Remember**: Platforms don't enforce CMMI compliance automatically. You must configure them to implement CMMI practices. This skill provides the configuration patterns to bridge CMMI policy to platform reality.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### github-requirements.md

```markdown
# Reference Sheet: Requirements Management in GitHub

## Purpose & Context

Implements CMMI **REQM (Requirements Management)** and **RD (Requirements Development)** process areas using GitHub Issues, Projects, and automation.

**When to apply**: Setting up requirements tracking with bidirectional traceability for CMMI compliance

**Prerequisites**: GitHub repository, Issues enabled, Projects access

---

## CMMI Maturity Scaling

### Level 2: Managed

**Required Practices**:
- Requirements documented as GitHub Issues
- Basic traceability (PR links to issue)
- Change tracking via issue comments

**Work Products**:
- Issue template for requirements
- PR description with requirement reference
- Simple traceability matrix (spreadsheet or wiki)

**Quality Criteria**:
- All requirements have unique IDs
- All PRs reference at least one requirement
- Requirements status tracked (Open/Closed)

**Audit Trail**:
- Issue creation/modification history
- PR → Issue links visible
- Comment history on requirement changes

### Level 3: Defined

**Enhanced Practices**:
- Standardized issue templates with acceptance criteria
- Automated traceability verification
- Requirement baselines (milestones)
- Change impact analysis documented

**Additional Work Products**:
- Automated traceability matrix (generated from GitHub data)
- Requirement change log
- Impact analysis template
- Baseline reports

**Quality Criteria**:
- Bidirectional traceability enforced (requirement ↔ code ↔ test)
- All requirements peer-reviewed
- Change requests follow approval workflow
- Coverage metrics tracked

**Audit Trail**:
- Approval history in issue comments
- Baseline tags/releases
- Change request workflow documented
- Traceability verification logs

### Level 4: Quantitatively Managed

**Statistical Practices**:
- Requirements volatility metrics (changes/week)
- Traceability coverage percentage
- Requirements stability trends

**Quantitative Work Products**:
- Requirements churn rate dashboard
- Defect density by requirement
- Lead time from requirement to deployment

**Quality Criteria**:
- Requirements volatility within control limits
- >95% traceability coverage
- Predictive models for requirement stability

**Audit Trail**:
- Metrics collection automation logs
- Statistical baselines documented
- Process performance data retained

---

## Implementation Guidance

### Quick Start Checklist

**Level 2 Setup** (30 minutes):
- [ ] Create requirement issue template
- [ ] Create PR template with requirement reference
- [ ] Add requirement labels
- [ ] Document traceability approach in README

**Level 3 Setup** (2-3 hours):
- [ ] All Level 2 items
- [ ] Add automated traceability verification (GitHub Actions)
- [ ] Create GitHub Project for requirements tracking
- [ ] Set up milestone baselines
- [ ] Configure change request workflow

**Level 4 Setup** (1-2 days):
- [ ] All Level 3 items
- [ ] Implement requirements metrics collection
- [ ] Create metrics dashboard
- [ ] Establish statistical baselines
- [ ] Set up automated alerting

---

## Templates & Examples

### Issue Template for Requirements

**File**: `.github/ISSUE_TEMPLATE/requirement.yml`

```yaml
name: Requirement
description: Document a system requirement or user story
title: "[REQ-YYYY-NNN] "
labels: ["requirement", "needs-review"]
body:
  - type: markdown
    attributes:
      value: |
        ## Requirement Specification
        Complete all fields for CMMI traceability.
        
  - type: input
    id: req-id
    attributes:
      label: Requirement ID
      description: Auto-generated format REQ-YYYY-NNN
      placeholder: REQ-2026-001
    validations:
      required: true
      
  - type: textarea
    id: statement
    attributes:
      label: Requirement Statement
      description: Clear, testable requirement statement
      placeholder: "The system shall..."
    validations:
      required: true
      
  - type: textarea
    id: acceptance-criteria
    attributes:
      label: Acceptance Criteria
      description: Checklist of criteria that must be met
      value: |
        - [ ] Criterion 1
        - [ ] Criterion 2
        - [ ] Criterion 3
    validations:
      required: true
      
  - type: dropdown
    id: priority
    attributes:
      label: Priority
      options:
        - Critical
        - High
        - Medium
        - Low
    validations:
      required: true
      
  - type: input
    id: source
    attributes:
      label: Source
      description: Stakeholder, regulation, or business need
      
  - type: textarea
    id: dependencies
    attributes:
      label: Dependencies
      description: Link to related requirements (use #issue-number)
      
  - type: dropdown
    id: verification
    attributes:
      label: Verification Method
      options:
        - Unit Test
        - Integration Test
        - System Test
        - Manual Review
        - Inspection
    validations:
      required: true
```

### PR Template with Traceability

**File**: `.github/pull_request_template.md`

```markdown
## Description
<!-- Clear description of changes -->

## Requirements Traceability
**Implements**: Closes #<issue-number>
<!-- Use "Closes #123" to auto-close requirement when PR merges -->

**Related Requirements**:
- #<issue-number>
- #<issue-number>

## Acceptance Criteria Verification
<!-- Copy from requirement issue, check off as completed -->
- [ ] Criterion 1 from #<issue-number>
- [ ] Criterion 2 from #<issue-number>
- [ ] Criterion 3 from #<issue-number>

## Testing
### Test Cases Added
- [ ] Unit tests: `test_file.py::test_function`
- [ ] Integration tests: `test_integration.py::test_scenario`
- [ ] Test coverage: XX% (minimum 80% for new code)

### Verification Evidence
- [ ] All tests passing locally
- [ ] CI/CD pipeline passing
- [ ] Code review completed
- [ ] Documentation updated

## CMMI Traceability
- **Requirement**: #<issue-number>
- **Design**: Link to design doc or ADR
- **Tests**: Link to test files or test run results
- **Documentation**: Link to updated docs

## Checklist
- [ ] Code follows project standards
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Requirement acceptance criteria met
- [ ] Backward compatibility maintained
- [ ] No security vulnerabilities introduced
```

### Automated Traceability Verification

**File**: `.github/workflows/traceability-check.yml`

```yaml
name: Requirements Traceability Check

on:
  pull_request:
    types: [opened, edited, synchronize]
  schedule:
    - cron: '0 0 * * 1'  # Weekly verification

jobs:
  verify-pr-traceability:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - name: Check PR links to requirement
        uses: actions/github-script@v6
        with:
          script: |
            const prBody = context.payload.pull_request.body || '';
            
            // Check for requirement reference
            const hasRequirement = /(?:Implements|Closes|Fixes|Resolves):\s*(?:Closes\s+)?#\d+/i.test(prBody);
            if (!hasRequirement) {
              core.setFailed('❌ PR must link to requirement issue using "Implements: Closes #123"');
              return;
            }
            
            // Check for test coverage mention
            const hasTests = /test coverage:\s*\d+%/i.test(prBody);
            if (!hasTests) {
              core.warning('⚠️  PR should specify test coverage percentage');
            }
            
            // Check for acceptance criteria
            const hasAC = /acceptance criteria/i.test(prBody);
            if (!hasAC) {
              core.warning('⚠️  PR should verify acceptance criteria from requirement');
            }
            
            core.info('✅ PR traceability check passed');
  
  verify-repository-traceability:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      
      - name: Install dependencies
        run: pip install PyGithub tabulate
      
      - name: Verify bidirectional traceability
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          python << 'PYTHON_SCRIPT'
          from github import Github
          import os
          from tabulate import tabulate
          
          g = Github(os.environ['GITHUB_TOKEN'])
          repo = g.get_repo(os.environ['GITHUB_REPOSITORY'])
          
          # Get all requirement issues
          requirements = list(repo.get_issues(state='all', labels=['requirement']))
          
          orphaned_reqs = []
          unverified_reqs = []
          
          for req in requirements:
              # Check for linked PRs
              events = list(req.get_events())
              has_pr = any(e.event in ['connected', 'cross-referenced'] for e in events)
              
              if req.state == 'closed' and not has_pr:
                  orphaned_reqs.append((req.number, req.title))
              
              # Check for test verification
              if 'verified by' not in req.body.lower():
                  unverified_reqs.append((req.number, req.title))
          
          # Generate report
          print("# Requirements Traceability Report\n")
          print(f"**Total Requirements**: {len(requirements)}")
          print(f"**Open**: {len([r for r in requirements if r.state == 'open'])}")
          print(f"**Closed**: {len([r for r in requirements if r.state == 'closed'])}\n")
          
          if orphaned_reqs:
              print("## ❌ Orphaned Requirements (closed without PRs)")
              print(tabulate(orphaned_reqs, headers=['Issue', 'Title'], tablefmt='github'))
              print()
          
          if unverified_reqs:
              print("## ⚠️  Unverified Requirements (no test verification)")
              print(tabulate(unverified_reqs[:10], headers=['Issue', 'Title'], tablefmt='github'))
              if len(unverified_reqs) > 10:
                  print(f"\n...and {len(unverified_reqs) - 10} more")
              print()
          
          if not orphaned_reqs and not unverified_reqs:
              print("## ✅ All requirements have proper traceability")
          
          # Fail if critical issues found
          if orphaned_reqs:
              exit(1)
          PYTHON_SCRIPT
```

---

## Common Anti-Patterns

| Anti-Pattern | Why It Fails | Better Approach |
|--------------|--------------|-----------------|
| **Generic issue titles** | "Fix bug" doesn't indicate requirement | Use "[REQ-YYYY-NNN] Specific requirement title" format |
| **Manual traceability matrix** | Spreadsheet becomes stale immediately | Generate matrix from GitHub API (requirements + linked PRs) |
| **No requirement IDs** | Can't reference requirements uniquely | Use REQ-YYYY-NNN format in title and issue body |
| **Mixing requirements with bugs** | Confusion between new functionality and defects | Use separate labels: `requirement` vs `bug` |
| **No acceptance criteria** | "Done" is subjective, leads to rework | Require checklist of testable acceptance criteria |
| **Forgetting test traceability** | Can't prove requirement is verified | Link tests in PR description, use test naming convention |
| **No baseline management** | Requirements change mid-sprint without control | Use milestones for requirement baselines, freeze before sprint |
| **Skipping change impact analysis** | Requirement changes break existing functionality | Document affected PRs/tests when changing requirements |
| **No requirement review** | Bad requirements waste development time | Require `needs-review` label, approval comment before implementation |
| **Orphaned requirements** | Requirements approved but never implemented | Weekly verification workflow finds requirements without PRs |

---

## Tool Integration

### Traceability Matrix Generation

**Script**: `scripts/generate-traceability-matrix.py`

```python
#!/usr/bin/env python3
"""Generate Requirements Traceability Matrix from GitHub."""

from github import Github
import os
import sys
from tabulate import tabulate

def generate_matrix(repo_name, token):
    g = Github(token)
    repo = g.get_repo(repo_name)
    
    requirements = list(repo.get_issues(state='all', labels=['requirement']))
    
    matrix = []
    for req in requirements:
        req_id = req.title.split(']')[0].strip('[') if '[' in req.title else f"#{req.number}"
        status = '✅ Closed' if req.state == 'closed' else '🔄 Open'
        
        # Find linked PRs
        prs = []
        for event in req.get_timeline():
            if event.event == 'cross-referenced' and event.source and event.source.issue and event.source.issue.pull_request:
                prs.append(f"#{event.source.issue.number}")
        
        pr_links = ', '.join(prs[:3]) if prs else '❌ None'
        if len(prs) > 3:
            pr_links += f" (+{len(prs)-3} more)"
        
        matrix.append([req_id, req.title[:50], status, pr_links])
    
    print("# Requirements Traceability Matrix\n")
    print(tabulate(matrix, headers=['Req ID', 'Title', 'Status', 'Implemented By'], tablefmt='github'))
    print(f"\n**Total Requirements**: {len(requirements)}")
    print(f"**With PR Links**: {len([r for r in matrix if '❌' not in r[3]])}")
    
if __name__ == '__main__':
    repo = os.environ.get('GITHUB_REPOSITORY', 'owner/repo')
    token = os.environ.get('GITHUB_TOKEN')
    
    if not token:
        print("ERROR: Set GITHUB_TOKEN environment variable")
        sys.exit(1)
    
    generate_matrix(repo, token)
```

Run weekly and commit to docs:

```yaml
# Add to .github/workflows/traceability-check.yml
- name: Generate traceability matrix
  run: python scripts/generate-traceability-matrix.py > docs/traceability-matrix.md

- name: Commit matrix
  run: |
    git config user.name "GitHub Actions"
    git config user.email "[email protected]"
    git add docs/traceability-matrix.md
    git diff --quiet && git diff --staged --quiet || git commit -m "docs: update traceability matrix"
    git push
```

---

## Verification & Validation

### How to Verify This Practice is Working

**Observable Indicators**:
- All requirement issues use standardized template
- Every PR references at least one requirement issue
- Traceability matrix generated weekly without errors
- No orphaned requirements (closed issues without PR links)
- Acceptance criteria documented and verified in PRs

**Metrics to Track** (Level 3+):
- Requirements traceability coverage: (PRs with requirement links / Total PRs) × 100%
- Orphaned requirements: Count of closed requirements without PR links
- Requirements churn: Count of changes to closed requirements per week

**Metrics to Track** (Level 4):
- Requirements volatility rate: Changes per requirement per month
- Lead time: Days from requirement opened to closed
- Requirements defect escape rate: Defects found in production / Total defects

### Common Failure Modes

| Failure Mode | Symptom | Remediation |
|--------------|---------|-------------|
| **PRs missing requirement links** | Traceability check workflow fails frequently | Add required status check, train team on PR template |
| **Stale traceability matrix** | Matrix shows requirements without PRs, but PRs exist | Fix PR template to use "Closes #123", not just mentions |
| **Orphaned requirements** | Requirements closed without implementation | Add weekly verification workflow, require PR link before closing |
| **No test verification** | Requirements marked complete but no tests | Require test coverage field in PR template, enforce minimum coverage |
| **Requirement ID conflicts** | Multiple requirements with same ID | Use auto-incrementing IDs (REQ-YYYY-NNN), document ID assignment process |

---

## Related Practices

**Cross-References**:
- `../requirements-lifecycle/SKILL.md` - CMMI REQM/RD process definitions
- `./github-config-mgmt.md` - Branch protection, baselines, release management
- `./github-quality-gates.md` - Testing and verification for requirements
- `../governance-and-risk/dar-methodology.md` - Architecture decisions for requirements

**Integration with Other Process Areas**:
- **VER (Verification)**: Link tests to requirements via test naming convention
- **VAL (Validation)**: Use acceptance criteria for validation
- **CM (Configuration Management)**: Use milestones for requirement baselines
- **MA (Measurement)**: Track requirements volatility, traceability coverage

---

**Last Updated**: 2026-01-25
**Review Schedule**: Update templates when GitHub releases new features, review annually

```

### github-config-mgmt.md

```markdown
# Reference Sheet: Configuration Management in GitHub

## Purpose & Context

Implements CMMI **CM (Configuration Management)** using GitHub branch protection, CODEOWNERS, and release management.

**CMMI Process Area**: CM (Configuration Management)
**Platforms**: GitHub Repositories

---

## CMMI Maturity Scaling

**Level 2**: Basic branch protection, manual reviews, tag-based releases
**Level 3**: CODEOWNERS enforcement, automated baselines, standardized workflows
**Level 4**: Metrics on branch health, merge frequency, baseline stability

---

## Branch Protection (Level 3 Requirements)

**Settings → Branches → Add rule**:

```yaml
Pattern: main
Require pull request reviews: 2 reviewers
Dismiss stale reviews: Yes
Require status checks: Yes
  - build-and-test
  - code-quality
Require branches up-to-date: Yes
Require conversation resolution: Yes
Include administrators: Yes
```

**As code** (Terraform):

```hcl
resource "github_branch_protection" "main" {
  repository_id = github_repository.repo.node_id
  pattern       = "main"
  
  required_pull_request_reviews {
    required_approving_review_count = 2
    dismiss_stale_reviews          = true
  }
  
  required_status_checks {
    strict = true
    contexts = [
      "build-and-test",
      "code-quality"
    ]
  }
  
  enforce_admins = true
}
```

---

## CODEOWNERS File

**File**: `.github/CODEOWNERS`

```plaintext
# Default owners for everything
* @org/core-team

# Backend code requires backend team review
/src/backend/ @org/backend-team
/api/ @org/backend-team

# Frontend code requires frontend team review
/src/frontend/ @org/frontend-team
/ui/ @org/frontend-team

# Infrastructure changes require DevOps review
/infrastructure/ @org/devops-team
/.github/workflows/ @org/devops-team
/terraform/ @org/devops-team

# Security-sensitive files require security team
/src/auth/ @org/security-team
/config/secrets/ @org/security-team

# Documentation can be reviewed by anyone
/docs/ @org/core-team
```

**Enforcement**: Enable "Require review from Code Owners" in branch protection

---

## Git Workflow Comparison

| Workflow | Best For | Pros | Cons | CMMI Fit |
|----------|----------|------|------|----------|
| **GitFlow** | Release-based products | Clear release process, hotfix support | Complex, many branches | ✅ Level 3/4 |
| **GitHub Flow** | Continuous deployment | Simple, fast | Limited release control | ✅ Level 2/3 |
| **Trunk-Based** | High-velocity teams | Fastest integration | Requires discipline | ✅ Level 3/4 |

**Recommendation for CMMI Level 3**: GitHub Flow with release branches

---

## Baseline Management

**Create baseline** (milestone freeze):

```bash
# Tag release baseline
git tag -a v1.2.0 -m "Release 1.2.0 baseline"
git push origin v1.2.0

# Create GitHub Release
gh release create v1.2.0 \
  --title "Release 1.2.0" \
  --notes "Baseline for Sprint 12" \
  --target main
```

**Lock baseline** (protect tag):

```yaml
# .github/workflows/protect-tags.yml
name: Protect Release Tags

on:
  push:
    tags:
      - 'v*'

jobs:
  protect:
    runs-on: ubuntu-latest
    steps:
      - name: Prevent tag deletion
        run: |
          # Tags starting with 'v' are protected baselines
          echo "Tag created: ${{ github.ref_name }}"
          # Configure tag protection via API (requires Enterprise)
```

---

## Merge Strategies

**Squash** (recommended for Level 3):
- Clean history (one commit per PR)
- Easier to revert features
- Simpler bisect for debugging

**Merge commit**:
- Preserves full PR history
- Better for audit trail
- More complex history

**Rebase**:
- Linear history
- Loses PR merge point
- Can complicate traceability

**Configuration**: Settings → Pull Requests → Allow squash merging (only)

---

## Emergency Hotfix Procedure

**Level 3 hotfix workflow**:

1. Create hotfix branch from production tag
2. Implement fix with expedited review (1 reviewer)
3. Fast-track through CI/CD
4. Deploy to production
5. **Post-facto review** within 24 hours
6. Backport to main

```bash
# Create hotfix
git checkout -b hotfix/critical-bug v1.2.0
# Fix + commit
git tag v1.2.1
git push origin v1.2.1 hotfix/critical-bug

# Deploy (expedited approval)

# Backport to main
git checkout main
git cherry-pick <hotfix-commit>
```

---

## Related Practices

- `./github-requirements.md` - Requirement baselines with milestones
- `./github-quality-gates.md` - Build validation for branch protection
- `../design-and-build/SKILL.md` - CM process definitions

---

**Last Updated**: 2026-01-25

```

### github-quality-gates.md

```markdown
# Reference Sheet: Quality Gates in GitHub

## Purpose & Context

Implements CMMI **VER (Verification)**, **VAL (Validation)**, and **PI (Product Integration)** process areas using GitHub Actions, status checks, and deployment environments.

**When to apply**: Setting up CI/CD pipelines with quality gates for CMMI compliance

**Prerequisites**: GitHub repository, Actions enabled, deployment environments configured

---

## CMMI Maturity Scaling

### Level 2: Managed
- Basic CI (build + test on PR)
- Manual code review
- Simple pass/fail gates
- Deployment to single environment

### Level 3: Defined
- Multi-stage pipelines (build → test → deploy)
- Required status checks
- Automated quality metrics (coverage, linting)
- Multiple environments (dev, staging, prod)
- Approval workflows

### Level 4: Quantitatively Managed
- Pipeline metrics (success rate, duration)
- Statistical process control on quality
- Predictive failure detection
- Performance benchmarking

---

## Implementation Guidance

### Multi-Stage Pipeline Example

**File**: `.github/workflows/ci-cd.yml`

```yaml
name: CI/CD Pipeline

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  # Stage 1: Build and Unit Test
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up environment
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-cov
      
      - name: Run unit tests
        run: |
          pytest tests/unit/ --cov=src --cov-report=xml --cov-report=term
      
      - name: Check coverage threshold
        run: |
          coverage report --fail-under=80
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage.xml
          flags: unittests
  
  # Stage 2: Integration Tests
  integration-tests:
    needs: build-and-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Set up environment
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      
      - name: Install dependencies
        run: pip install -r requirements.txt
      
      - name: Run integration tests
        run: pytest tests/integration/ -v
      
      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: integration-test-results
          path: test-results/
  
  # Stage 3: Security Scan
  security-scan:
    needs: build-and-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run security scan
        uses: snyk/actions/python@master
        env:
          SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
      
      - name: Check for vulnerabilities
        run: |
          # Fail if high/critical vulnerabilities found
          exit 0  # Customize based on security policy
  
  # Stage 4: Deploy to Staging (on main branch only)
  deploy-staging:
    if: github.ref == 'refs/heads/main'
    needs: [build-and-test, integration-tests, security-scan]
    runs-on: ubuntu-latest
    environment:
      name: staging
      url: https://staging.example.com
    steps:
      - uses: actions/checkout@v3
      
      - name: Deploy to staging
        run: |
          # Your deployment script
          echo "Deploying to staging..."
      
      - name: Run smoke tests
        run: |
          # Post-deployment verification
          curl -f https://staging.example.com/health || exit 1
  
  # Stage 5: Deploy to Production (requires approval)
  deploy-production:
    if: github.ref == 'refs/heads/main'
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - uses: actions/checkout@v3
      
      - name: Deploy to production
        run: |
          # Your deployment script
          echo "Deploying to production..."
      
      - name: Run smoke tests
        run: |
          curl -f https://example.com/health || exit 1
      
      - name: Notify team
        run: |
          # Send deployment notification
          echo "Production deployment complete"
```

### Branch Protection Configuration

**GitHub UI**: Settings → Branches → Branch protection rules

**Required settings for Level 3**:
- ✅ Require pull request reviews before merging (2 reviewers)
- ✅ Dismiss stale pull request approvals when new commits are pushed
- ✅ Require status checks to pass before merging
  - ✅ `build-and-test`
  - ✅ `integration-tests`
  - ✅ `security-scan`
- ✅ Require branches to be up to date before merging
- ✅ Require conversation resolution before merging
- ✅ Include administrators (enforce for everyone)

**As code** (using GitHub CLI):

```bash
gh api repos/OWNER/REPO/branches/main/protection \
  --method PUT \
  --field required_status_checks[strict]=true \
  --field required_status_checks[contexts][]=build-and-test \
  --field required_status_checks[contexts][]=integration-tests \
  --field required_status_checks[contexts][]=security-scan \
  --field required_pull_request_reviews[required_approving_review_count]=2 \
  --field required_pull_request_reviews[dismiss_stale_reviews]=true \
  --field enforce_admins=true \
  --field required_conversation_resolution=true
```

---

## Common Anti-Patterns

| Anti-Pattern | Why It Fails | Better Approach |
|--------------|--------------|-----------------|
| **No required status checks** | PRs can merge with failing tests | Configure branch protection with required checks |
| **Tests only on main** | Defects discovered after merge | Run tests on all PRs before merge |
| **Manual deployment** | Human error, no audit trail | Automate deployment via Actions with approval gates |
| **Single-stage pipeline** | No isolation between unit/integration/deploy | Multi-stage pipeline with dependencies |
| **No coverage enforcement** | Code quality degrades over time | Fail pipeline if coverage drops below threshold |
| **Skipping smoke tests** | Broken deployments reach users | Post-deployment smoke tests as final gate |

---

## Environment Protection Rules

**Staging Environment** (auto-deploy on main):
- No reviewers required
- Deployment branches: `main` only
- Environment secrets: Staging API keys

**Production Environment** (manual approval):
- Required reviewers: 2 from CODEOWNERS
- Wait timer: 5 minutes (allows cancellation)
- Deployment branches: `main` only
- Environment secrets: Production API keys

**Configuration**: Settings → Environments → [Environment] → Protection rules

---

## Verification Metrics (Level 3/4)

**Pipeline metrics to track**:
- Build success rate: (Successful builds / Total builds) × 100%
- Test pass rate: (Passing tests / Total tests) × 100%
- Deployment frequency: Count per day/week
- Lead time: Commit to production deployment time
- Change failure rate: (Failed deployments / Total deployments) × 100%
- Mean time to recovery (MTTR): Time to fix broken pipeline

**Collect via**:
```yaml
- name: Record metrics
  run: |
    # Store metrics in artifact or external service
    echo "build_duration_seconds,${{ job.duration }}" >> metrics.csv
```

---

## Related Practices

- `../quality-assurance/SKILL.md` - VER/VAL process definitions
- `./github-measurement.md` - Pipeline metrics collection
- `./github-config-mgmt.md` - Branch protection, baselines
- `../design-and-build/SKILL.md` - Integration strategies (PI)

---

**Last Updated**: 2026-01-25

```

### github-measurement.md

```markdown
# Reference Sheet: Measurement in GitHub

## Purpose & Context

Implements CMMI **MA (Measurement & Analysis)** using GitHub Insights, API, and Actions for automated metrics collection.

**CMMI Process Area**: MA (Measurement & Analysis)
**Platforms**: GitHub API, Actions, third-party integrations

---

## CMMI Maturity Scaling

**Level 2**: Manual metrics collection, basic GitHub Insights
**Level 3**: Automated collection, dashboards, trend analysis
**Level 4**: Statistical baselines, predictive models, control charts

---

## DORA Metrics Implementation

### 1. Deployment Frequency

**Collect via GitHub Actions**:

```yaml
name: Track Deployment

on:
  deployment_status:

jobs:
  record-deployment:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Record deployment
        run: |
          echo "${{ github.event.deployment.environment }},${{ github.event.deployment.created_at }}" >> deployments.csv
      
      - name: Calculate frequency
        run: |
          # Deployments per day
          python scripts/calculate_deployment_frequency.py
```

### 2. Lead Time for Changes

**Track commit to deployment time**:

```python
from github import Github
from datetime import datetime

def calculate_lead_time(repo_name, token):
    g = Github(token)
    repo = g.get_repo(repo_name)
    
    deployments = repo.get_deployments()
    
    for deploy in deployments[:10]:  # Last 10 deployments
        # Get deployment SHA
        sha = deploy.sha
        commit = repo.get_commit(sha)
        
        # Lead time = deployment time - commit time
        lead_time = deploy.created_at - commit.commit.author.date
        
        print(f"Deployment {deploy.id}: {lead_time.total_seconds()/3600:.2f} hours")
```

### 3. Change Failure Rate

**Track failed deployments**:

```yaml
- name: Record deployment outcome
  if: always()
  run: |
    STATUS="${{ job.status }}"
    echo "${{ github.sha }},$STATUS,$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> deployment-outcomes.csv
```

Calculate: `Failed deployments / Total deployments × 100%`

### 4. Mean Time to Recovery (MTTR)

**Track incident resolution time**:

```python
# Link incidents to fix deployments
incidents = repo.get_issues(labels=['incident'])

for incident in incidents:
    created = incident.created_at
    closed = incident.closed_at or datetime.now()
    
    mttr = (closed - created).total_seconds() / 3600
    print(f"Incident #{incident.number}: {mttr:.2f} hours to resolve")
```

---

## Dashboard Creation

**Option 1: GitHub API + External Dashboard**

Use Grafana, PowerBI, or custom dashboard:

```python
# Fetch metrics via GitHub API
import requests

headers = {"Authorization": f"token {GITHUB_TOKEN}"}
metrics = requests.get(
    f"https://api.github.com/repos/{OWNER}/{REPO}/stats/commit_activity",
    headers=headers
).json()

# Send to dashboard service
```

**Option 2: GitHub Pages Static Dashboard**

Generate static HTML from metrics:

```yaml
- name: Generate dashboard
  run: |
    python scripts/generate_dashboard.py > docs/metrics-dashboard.html
    
- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./docs
```

**Option 3: Third-Party Integrations**

- **CodeClimate**: Quality metrics
- **Codecov**: Test coverage
- **SonarQube**: Code quality, tech debt

---

## Metrics Collection Automation

**Weekly metrics snapshot**:

```yaml
name: Collect Weekly Metrics

on:
  schedule:
    - cron: '0 0 * * 1'  # Monday midnight

jobs:
  collect-metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Collect GitHub metrics
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          python << 'PYTHON'
          from github import Github
          import os
          import json
          from datetime import datetime, timedelta
          
          g = Github(os.environ['GITHUB_TOKEN'])
          repo = g.get_repo(os.environ['GITHUB_REPOSITORY'])
          
          # Last 7 days
          since = datetime.now() - timedelta(days=7)
          
          metrics = {
              'date': datetime.now().isoformat(),
              'commits': repo.get_commits(since=since).totalCount,
              'prs_opened': len(list(repo.get_pulls(state='all', since=since))),
              'prs_merged': len(list(repo.get_pulls(state='closed', since=since))),
              'issues_opened': len(list(repo.get_issues(state='all', since=since))),
              'issues_closed': len(list(repo.get_issues(state='closed', since=since))),
          }
          
          with open('metrics/weekly-snapshot.json', 'w') as f:
              json.dump(metrics, f, indent=2)
          PYTHON
      
      - name: Commit metrics
        run: |
          git config user.name "GitHub Actions"
          git config user.email "[email protected]"
          git add metrics/
          git commit -m "chore: weekly metrics snapshot"
          git push
```

---

## Statistical Baselines (Level 4)

**Establish organizational baselines**:

```python
# Calculate mean and standard deviation for lead time
import statistics

lead_times = [12.5, 15.3, 11.8, 14.2, 13.9]  # hours

mean = statistics.mean(lead_times)
stdev = statistics.stdev(lead_times)

print(f"Baseline Lead Time: {mean:.2f} ± {stdev:.2f} hours")
print(f"Control Limits: [{mean - 2*stdev:.2f}, {mean + 2*stdev:.2f}]")

# Alert if new deployment exceeds control limits
if new_lead_time > mean + 2*stdev:
    print("⚠️ Lead time exceeded control limit!")
```

---

## Common Anti-Patterns

| Anti-Pattern | Better Approach |
|--------------|-----------------|
| Manual metrics collection | Automate via GitHub Actions |
| Vanity metrics (stars, forks) | Actionable metrics (DORA, defect density) |
| No baselines | Establish mean + control limits (Level 3/4) |
| Stale dashboards | Automated daily/weekly updates |

---

## Related Practices

- `../quantitative-management/SKILL.md` - MA process definitions, GQM framework
- `./github-quality-gates.md` - Pipeline metrics
- `./github-audit-trail.md` - Metrics retention for compliance

---

**Last Updated**: 2026-01-25

```

### github-audit-trail.md

```markdown
# Reference Sheet: Audit Trail in GitHub

## Purpose & Context

Implements CMMI compliance and audit requirements using GitHub's built-in history, logs, and retention features.

**Use for**: SOC 2, ISO 9001, GDPR, FDA compliance, audit preparation

---

## Audit Trail Components

### 1. Commit History

**What's captured**:
- Who made the change (author, committer)
- When (timestamp with timezone)
- What changed (diff)
- Why (commit message)

**Retention**: Permanent (in Git history)

**Verification**:
```bash
# Verify commit signature (if using GPG)
git log --show-signature

# Full audit trail
git log --all --pretty=format:"%H|%an|%ae|%ad|%s" > commit-audit.csv
```

### 2. Pull Request Review History

**What's captured**:
- Reviewers and approval status
- Review comments and discussions
- Changes requested / approved
- Merge actor and timestamp

**Retention**: Permanent (in GitHub database)

**Access**: PR page → "Reviewers" section, comment history

### 3. Issue Comment Trails

**What's captured**:
- All comments and edits (with edit history)
- State changes (open → closed)
- Label changes
- Assignment changes

**Retention**: Permanent

### 4. GitHub Actions Logs

**What's captured**:
- Workflow runs (success/failure)
- Job execution logs
- Artifacts generated
- Deployment events

**Retention**: 90 days default (configurable up to 400 days with paid plan)

**Extend retention**:
```yaml
- name: Archive logs for compliance
  if: always()
  uses: actions/upload-artifact@v3
  with:
    name: audit-logs-${{ github.run_id }}
    path: logs/
    retention-days: 400  # Maximum retention
```

### 5. Audit Log (Enterprise only)

**What's captured**:
- Organization-level events
- Repository settings changes
- Permission changes
- Security events

**Access**: Organization → Settings → Audit log

**Export**:
```bash
gh api /orgs/ORG/audit-log \
  --paginate \
  --jq '.[] | [.created_at, .action, .actor, .repo] | @csv' \
  > org-audit-log.csv
```

---

## Compliance Mappings

### SOC 2 Requirements

| Control | GitHub Feature | Evidence |
|---------|----------------|----------|
| **Change Management (CC8.1)** | Branch protection, required reviews | PR approval history |
| **Logical Access (CC6.1)** | Repository permissions, 2FA | Audit log (Enterprise) |
| **System Operations (CC7.1)** | Actions logs, deployment history | Workflow run logs |
| **Monitoring (CC7.2)** | GitHub Insights, metrics | Metrics dashboards |

### ISO 9001 Requirements

| Clause | Requirement | GitHub Implementation |
|--------|-------------|----------------------|
| **8.5.1** | Control of production | Branch protection, required tests |
| **8.5.2** | Identification and traceability | Issue/PR linking, commit SHAs |
| **8.5.6** | Control of changes | PR review process, change log |

### GDPR Requirements

| Article | Requirement | GitHub Implementation |
|---------|-------------|----------------------|
| **Art 32** | Security of processing | Branch protection, access control |
| **Art 30** | Records of processing | Audit logs, commit history |
| **Art 17** | Right to erasure | Manual process (contact GitHub support) |

---

## Audit Report Generation

**Monthly audit report**:

```python
#!/usr/bin/env python3
"""Generate monthly audit report from GitHub."""

from github import Github
from datetime import datetime, timedelta
import os

def generate_audit_report(repo_name, token):
    g = Github(token)
    repo = g.get_repo(repo_name)
    
    # Last 30 days
    since = datetime.now() - timedelta(days=30)
    
    print("# GitHub Audit Report")
    print(f"**Repository**: {repo_name}")
    print(f"**Period**: {since.date()} to {datetime.now().date()}\n")
    
    # Commits
    commits = list(repo.get_commits(since=since))
    print(f"## Commits: {len(commits)}")
    print(f"- Unique contributors: {len(set(c.author.login for c in commits if c.author))}")
    
    # Pull Requests
    prs = list(repo.get_pulls(state='all', since=since))
    merged_prs = [pr for pr in prs if pr.merged]
    print(f"\n## Pull Requests: {len(prs)}")
    print(f"- Merged: {len(merged_prs)}")
    print(f"- Code review compliance: {len([pr for pr in merged_prs if pr.review_comments > 0])/len(merged_prs)*100:.1f}%")
    
    # Security
    print(f"\n## Security")
    print(f"- Branch protection: {'✅ Enabled' if repo.get_branch('main').protected else '❌ Disabled'}")
    print(f"- Required reviews: {repo.get_branch('main').get_required_pull_request_reviews().required_approving_review_count if repo.get_branch('main').protected else 'N/A'}")
    
    # Compliance
    print(f"\n## Compliance Checklist")
    print("- [✅] All PRs reviewed before merge")
    print("- [✅] Commit history intact (no force pushes)")
    print("- [✅] Issue traceability maintained")
    print("- [✅] Audit logs retained")

if __name__ == '__main__':
    generate_audit_report(os.environ['GITHUB_REPOSITORY'], os.environ['GITHUB_TOKEN'])
```

---

## Data Retention Policy

**Recommended retention periods**:

| Artifact | Retention | Rationale |
|----------|-----------|-----------|
| **Git commits** | Permanent | Historical record, compliance |
| **PR discussions** | Permanent | Decision rationale |
| **Actions logs** | 1 year minimum | Deployment evidence, compliance |
| **Artifacts** | 90-400 days | Test results, build outputs |
| **Metrics snapshots** | 2 years | Trend analysis, baselines |

**Implementation**:
```yaml
# .github/workflows/archive-logs.yml
- name: Archive to external storage
  run: |
    # Export to S3, Azure Blob, etc. for long-term retention
    aws s3 cp audit-logs.tar.gz s3://compliance-bucket/$(date +%Y%m%d)/
```

---

## Common Compliance Gaps

| Gap | Risk | Mitigation |
|-----|------|------------|
| No branch protection | Unreviewed changes | Enable required reviews |
| Actions logs expire | No deployment proof | Archive logs externally |
| No traceability | Can't prove requirement implemented | Enforce issue/PR linking |
| No access controls | Unauthorized changes | Enable 2FA, review permissions |

---

## Related Practices

- `./github-requirements.md` - Traceability for compliance
- `./github-config-mgmt.md` - Change control processes
- `../governance-and-risk/SKILL.md` - DAR/RSKM compliance

---

**Last Updated**: 2026-01-25

```

### azdo-requirements.md

```markdown
# Reference Sheet: Requirements Management in Azure DevOps

## Purpose & Context

Implements CMMI **REQM** and **RD** using Azure DevOps Work Items, Queries, and Backlogs.

**Key Advantage over GitHub**: Built-in hierarchical work items (Epic → Feature → User Story), rich custom fields, advanced queries.

---

## Work Item Type Hierarchy

```
Epic (Business Initiative)
  ↓
Feature (Capability)
  ↓
User Story (Requirement)
  ↓
Task (Implementation)
```

**Traceability**: Parent-child links automatically maintained

---

## Custom Fields for CMMI REQM

**Settings → Process → [Process] → Work Item Types → User Story → Add Field**

| Field Name | Type | Purpose | CMMI Practice |
|------------|------|---------|---------------|
| Requirement ID | Text | Unique identifier (REQ-YYYY-NNN) | REQM SP 1.1 |
| Verification Method | Dropdown | Unit Test, Integration Test, Review | REQM SP 1.4 |
| Source | Text | Stakeholder or regulation | RD SP 1.1 |
| Risk Level | Dropdown | Critical, High, Medium, Low | RSKM integration |
| Baseline | Text | Milestone or release version | CM integration |
| Approval Status | Dropdown | Draft, Under Review, Approved | REQM SP 1.2 |

---

## Bidirectional Traceability

### Requirements → Code

**Link work items to commits**:

```bash
git commit -m "Implement OAuth login

Related work items: #12345"
```

Azure DevOps automatically creates link between commit and work item #12345.

### Requirements → Tests

**Link test cases to requirements**:

1. Create Test Plan
2. Add Test Suites
3. Link Test Cases to User Story work items
4. Execute tests, results automatically linked

**Query for test coverage**:

```
SELECT [System.Id], [System.Title], [System.State]
FROM WorkItemLinks
WHERE ([Source].[Work Item Type] = 'User Story')
  AND ([Target].[Work Item Type] = 'Test Case')
  AND ([System.Links.LinkType] = 'Tests')
MODE (MustContain)
```

---

## Requirement Approval Workflow

**Custom workflow states**:

1. **New** → Requirements created
2. **Under Review** → Stakeholder review in progress
3. **Approved** → Ready for implementation
4. **Committed** → Included in sprint backlog
5. **Done** → Implementation verified
6. **Closed** → Deployment complete

**State transition rules** (enforce workflow):

- New → Under Review: No restrictions
- Under Review → Approved: Requires review comment with approval
- Approved → Committed: Only during sprint planning
- Committed → Done: All linked test cases must pass
- Done → Closed: Deployment to production confirmed

---

## Automated Traceability Reports

**Azure DevOps Analytics**:

Dashboard widget → Work Item Query → Custom Query:

```
SELECT [ID], [Title], [State], [Assigned To]
FROM WorkItems
WHERE [Work Item Type] = 'User Story'
  AND [State] != 'Closed'
  AND [System.Links.LinkCount] = 0  -- No linked PRs/commits
```

**PowerBI Integration**:

```powerquery
// Connect to Azure DevOps Analytics
let
    Source = AzureDevOps.Analytics("https://analytics.dev.azure.com/YOUR_ORG"),
    WorkItems = Source{[Name="WorkItems"]}[Data],
    Requirements = Table.SelectRows(WorkItems, each [WorkItemType] = "User Story"),
    WithLinks = Table.ExpandRecordColumn(Requirements, "Links", {"Count"})
in
    WithLinks
```

---

## Level 2/3/4 Scaling

**Level 2**:
- Use built-in User Story work items
- Manual traceability via linked work items
- Basic queries for reporting

**Level 3**:
- Custom fields for CMMI compliance
- Automated workflow state transitions
- Required approvals before state changes
- Analytics dashboards for traceability coverage

**Level 4**:
- Requirements volatility metrics (changes per requirement per week)
- Defect density by requirement
- Lead time from requirement to deployment
- Predictive models (PowerBI)

---

## Common Anti-Patterns

| Anti-Pattern | Better Approach |
|--------------|-----------------|
| Flat work item structure | Use Epic → Feature → Story hierarchy |
| No custom fields | Add CMMI-specific fields (Requirement ID, Approval Status) |
| Manual traceability | Auto-link commits via commit messages |
| No test plans | Create test plans linked to requirements |

---

## Related Practices

- `./azdo-quality-gates.md` - Test Plans integration
- `./azdo-config-mgmt.md` - Work item baseline management
- `./github-requirements.md` - GitHub comparison

---

**Last Updated**: 2026-01-25

```

### azdo-config-mgmt.md

```markdown
# Reference Sheet: Configuration Management in Azure DevOps

## Purpose & Context

Implements CMMI **CM** using Azure Repos branch policies, required reviewers, and work item integration.

**Key Advantage**: Tighter integration with work items, policy-based merge enforcement.

---

## Branch Policies (Level 3 Requirements)

**Repos → Branches → main → Branch policies**

```yaml
Require reviewers:
  Minimum: 2 reviewers
  Allow requestors to approve: No
  Reset votes when source branch updated: Yes
  
Build validation:
  Build pipeline: CI-Pipeline
  Trigger: Automatic
  Policy requirement: Required
  Build expiration: Immediately when main is updated
  
Status checks:
  - Code coverage >= 80%
  - Security scan passed
  
Work item linking:
  Require work items: Yes
  Check for linked work items: Required
  
Comment resolution:
  Require all comments resolved: Yes
```

**As code** (ARM template):

```json
{
  "minimumApproverCount": 2,
  "creatorVoteCounts": false,
  "resetOnSourcePush": true,
  "requiredReviewers": [],
  "buildValidation": {
    "buildDefinitionId": 12,
    "validDuration": 0
  },
  "statusChecks": [
    {
      "name": "coverage-check",
      "genre": "quality",
      "isRequired": true
    }
  ]
}
```

---

## Work Item Linking Enforcement

**Policy**: "Check for linked work items" = Required

**Link work item in PR**:

1. Create PR
2. Click "Add link" → "Existing item"
3. Select work item (User Story, Bug, Task)
4. PR cannot complete until work item linked

**In commit message**:

```bash
git commit -m "Fix authentication bug

Related work items: #12345"
```

---

## Merge Strategies

**Repos → Settings → Repository policies**

| Strategy | Use Case | Traceability Impact |
|----------|----------|---------------------|
| **Squash merge** (recommended) | Clean history | One commit per work item |
| **Merge commit** | Preserve full history | Full PR history visible |
| **Rebase and fast-forward** | Linear history | Loses PR merge point |
| **Semi-linear merge** | Balance | Merge commit + linear first-parent |

**Configuration**: Enable "Squash merge" only for Level 3

---

## Release Baseline Management

**Create baseline (Git tag)**:

```bash
git tag -a v1.2.0 -m "Release 1.2.0 baseline"
git push origin v1.2.0
```

**Lock baseline** (prevent branch deletion):

Repos → Branches → main → Security → Deny "Force push" and "Delete branch"

**Associate work items with release**:

Pipelines → Releases → v1.2.0 → Work items (automatically linked via commits)

---

## Emergency Hotfix Workflow

**Azure DevOps hotfix pattern**:

1. Create hotfix branch from release tag
2. Expedited review (1 reviewer, bypass status checks with justification)
3. Deploy via Release pipeline
4. **Post-facto review** documented in work item
5. Cherry-pick to main

**Override branch policy** (requires permissions):

- Click "Override branch policies"
- Provide reason: "Hotfix for critical production issue #12345"
- Requires "Override branch policies" permission

---

## Audit Trail

**Work item revisions**:

Work Item → History tab → View all revisions with field changes

**Branch policy bypasses**:

Repos → Branches → main → Policy → History of overrides

---

## Related Practices

- `./azdo-requirements.md` - Work item integration
- `./azdo-quality-gates.md` - Build validation policies
- `./github-config-mgmt.md` - GitHub comparison

---

**Last Updated**: 2026-01-25

```

### azdo-quality-gates.md

```markdown
# Reference Sheet: Quality Gates in Azure DevOps

## Purpose & Context

Implements CMMI **VER**, **VAL**, **PI** using Azure Pipelines multi-stage YAML, gates, and Test Plans.

**Key Advantage**: Built-in test management, approval gates, environment protection.

---

## Multi-Stage Pipeline (Level 3)

**File**: `azure-pipelines.yml`

```yaml
trigger:
  branches:
    include:
      - main

stages:
  - stage: Build
    jobs:
      - job: BuildAndTest
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - task: UsePythonVersion@0
            inputs:
              versionSpec: '3.10'
          
          - script: |
              pip install -r requirements.txt
              pytest tests/unit/ --cov=src --cov-report=xml
            displayName: 'Unit Tests'
          
          - task: PublishCodeCoverageResults@1
            inputs:
              codeCoverageTool: 'Cobertura'
              summaryFileLocation: '$(System.DefaultWorkingDirectory)/coverage.xml'
              failIfCoverageEmpty: true
  
  - stage: IntegrationTest
    dependsOn: Build
    condition: succeeded()
    jobs:
      - job: IntegrationTests
        steps:
          - script: pytest tests/integration/
            displayName: 'Integration Tests'
  
  - stage: DeployStaging
    dependsOn: IntegrationTest
    condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
    jobs:
      - deployment: DeployToStaging
        environment: Staging
        strategy:
          runOnce:
            deploy:
              steps:
                - script: echo "Deploying to staging..."
  
  - stage: DeployProduction
    dependsOn: DeployStaging
    condition: succeeded()
    jobs:
      - deployment: DeployToProduction
        environment: Production
        strategy:
          runOnce:
            deploy:
              steps:
                - script: echo "Deploying to production..."
```

---

## Environment Protection Rules

**Pipelines → Environments → Production → Approvals and checks**

**Approvals**:
- Approvers: 2 people from "Release Approvers" group
- Minimum number: 2
- Timeout: 30 days
- Instructions: "Verify staging deployment before approving"

**Gates**:
- **Invoke Azure Function**: Health check endpoint
- **Query Work Items**: No critical bugs open
- **Azure Monitor**: Alert count = 0

**Configuration**:

```yaml
environment:
  name: Production
  resourceType: None
approvals:
  - approver: approvers-group
    minRequired: 2
gates:
  - gate: AzureFunction
    inputs:
      function: '$(HealthCheckUrl)'
    successCriteria: 'eq(root[''status''], ''healthy'')'
```

---

## Test Plans Integration

**Test Plans → New Test Plan → Link to User Stories**

**Structure**:

```
Test Plan: Sprint 12
  ├─ Test Suite: Authentication
  │    ├─ Test Case: Login with valid credentials (linked to User Story #12345)
  │    └─ Test Case: Login with invalid credentials
  └─ Test Suite: Authorization
       └─ Test Case: Access control verification
```

**Automated test execution**:

```yaml
- task: VSTest@2
  inputs:
    testSelector: 'testAssemblies'
    testAssemblyVer2: |
      **\*test*.dll
      !**\*TestAdapter.dll
      !**\obj\**
    testPlan: $(TestPlanId)
    testSuite: $(TestSuiteId)
    publishRunAttachments: true
```

**Traceability**: Test results automatically linked to work items

---

## Quality Metrics Dashboard

**Dashboards → New Dashboard → Add widgets**

**Recommended widgets**:
- Build success rate (last 30 builds)
- Test pass rate (by test suite)
- Code coverage trend
- Deployment frequency (releases per week)
- Failed deployments

**Query example** (test coverage by requirement):

```
SELECT [ID], [Title], [Test Coverage %]
FROM WorkItems
WHERE [Work Item Type] = 'User Story'
ORDER BY [Test Coverage %] ASC
```

---

## Common Anti-Patterns

| Anti-Pattern | Better Approach |
|--------------|-----------------|
| Single-stage pipeline | Multi-stage with gates between stages |
| No test plans | Create test plans linked to requirements |
| Manual approvals only | Automate with gates (health checks, work item queries) |
| No deployment rollback | Define rollback strategy in release pipeline |

---

## Related Practices

- `./azdo-requirements.md` - Work item integration with tests
- `./azdo-measurement.md` - Pipeline metrics
- `./github-quality-gates.md` - GitHub comparison

---

**Last Updated**: 2026-01-25

```

### azdo-measurement.md

```markdown
# Reference Sheet: Measurement in Azure DevOps

## Purpose & Context

Implements CMMI **MA** using Azure DevOps Analytics, Dashboards, and PowerBI integration.

**Key Advantage**: Built-in analytics engine, rich dashboards, PowerBI direct connect.

---

## Azure DevOps Analytics

**Access**: Analytics → Analytics views

**Pre-built views**:
- Work Items: Current state, historical trends
- Pipelines: Build/release success rates, duration
- Test Results: Pass rate, duration, flaky tests

**OData API endpoint**:
```
https://analytics.dev.azure.com/{organization}/{project}/_odata/v3.0-preview/
```

---

## DORA Metrics in Azure DevOps

### 1. Deployment Frequency

**Dashboard widget**: Deployment status

**Custom query** (via API):

```odata
https://analytics.dev.azure.com/ORG/PROJECT/_odata/v3.0-preview/Deployments
?$filter=Environment eq 'Production'
&$select=CompletedDate
&$orderby=CompletedDate desc
```

Calculate deployments per day/week.

### 2. Lead Time for Changes

**Track commit to deployment**:

Query: Work Items → Deployment time

```odata
WorkItems
?$expand=Links($filter=LinkTypeName eq 'Commit')
&$select=CreatedDate,ClosedDate
```

Lead time = ClosedDate - CreatedDate

### 3. Change Failure Rate

**Track failed deployments**:

```odata
Deployments
?$filter=DeploymentStatus eq 'Failed'
&$select=CompletedDate,Environment
```

Calculate: Failed / Total deployments × 100%

### 4. MTTR (Mean Time to Recovery)

**Track incidents**:

```odata
WorkItems
?$filter=WorkItemType eq 'Bug' and Severity eq 'Critical'
&$select=CreatedDate,ClosedDate
```

MTTR = Average(ClosedDate - CreatedDate)

---

## Dashboard Creation

**Dashboards → New Dashboard → Add widgets**

**Recommended widgets for CMMI Level 3**:

1. **Velocity** - Story points completed per sprint
2. **Burndown** - Sprint progress tracking
3. **Code Coverage** - Trend over time
4. **Build Success Rate** - Last 30 builds
5. **Test Pass Rate** - By test suite
6. **Deployment Frequency** - Releases per week
7. **Lead Time** - Commit to deployment

**Widget configuration example** (Velocity):

```json
{
  "name": "Velocity",
  "position": {"row": 1, "column": 1},
  "size": {"rowSpan": 2, "columnSpan": 2},
  "settings": {
    "iterations": 6,
    "teamId": "TEAM_ID"
  }
}
```

---

## PowerBI Integration

**Connect to Azure DevOps Analytics**:

1. PowerBI Desktop → Get Data → Azure DevOps (Boards only)
2. Enter organization URL
3. Select project and entity (WorkItems, Pipelines, etc.)
4. Transform data in Power Query

**Example PowerBI query**:

```powerquery
let
    Source = AzureDevOps.Analytics("https://analytics.dev.azure.com/YOUR_ORG"),
    WorkItems = Source{[Name="WorkItems"]}[Data],
    FilteredRows = Table.SelectRows(WorkItems, each [WorkItemType] = "Bug"),
    GroupedRows = Table.Group(FilteredRows, {"CreatedDate"}, {{"Count", each Table.RowCount(_), Int64.Type}})
in
    GroupedRows
```

**Publish to PowerBI Service** for shared dashboards.

---

## Statistical Baselines (Level 4)

**Calculate organizational baselines**:

```powerquery
// Lead time baseline from last 6 months
let
    LeadTimes = {...},  // Array of lead times in hours
    Mean = List.Average(LeadTimes),
    StdDev = List.StandardDeviation(LeadTimes),
    UpperControlLimit = Mean + (2 * StdDev),
    LowerControlLimit = Mean - (2 * StdDev)
in
    [Mean = Mean, UCL = UpperControlLimit, LCL = LowerControlLimit]
```

**Create control chart** in PowerBI with UCL/LCL lines.

---

## Automated Metrics Collection

**Pipeline task** to collect metrics:

```yaml
- task: PowerShell@2
  inputs:
    targetType: 'inline'
    script: |
      # Query Analytics API
      $uri = "https://analytics.dev.azure.com/$(System.TeamProject)/_odata/v3.0-preview/WorkItems"
      $result = Invoke-RestMethod -Uri $uri -Headers @{Authorization = "Bearer $(System.AccessToken)"}
      
      # Store metrics
      $metrics = @{
        timestamp = Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ"
        workItemCount = $result.value.Count
      }
      
      $metrics | ConvertTo-Json | Out-File "metrics.json"
```

---

## Common Anti-Patterns

| Anti-Pattern | Better Approach |
|--------------|-----------------|
| Not using Analytics | Leverage built-in Analytics instead of manual queries |
| Static dashboards | Auto-refresh dashboards with real-time data |
| No baselines | Establish mean + control limits (Level 3/4) |
| PowerBI only for reporting | Use for predictive analytics, forecasting |

---

## Related Practices

- `../quantitative-management/SKILL.md` - MA process definitions, GQM
- `./azdo-quality-gates.md` - Pipeline metrics
- `./github-measurement.md` - GitHub comparison

---

**Last Updated**: 2026-01-25

```

### azdo-audit-trail.md

```markdown
# Reference Sheet: Audit Trail in Azure DevOps

## Purpose & Context

Implements CMMI compliance and audit requirements using Azure DevOps audit logs, work item history, and retention policies.

**Key Advantage**: Superior audit capabilities compared to GitHub - built-in audit logs, granular retention control, work item revision history.

---

## Audit Trail Components

### 1. Work Item History

**What's captured**:
- All field changes with before/after values
- State transitions
- Discussion comments
- Attachments
- Links (commits, PRs, other work items)

**Retention**: Permanent (never deleted)

**Access**: Work Item → History tab → View full revision history

**Export**:

```powershell
# Export work item history via API
$uri = "https://dev.azure.com/ORG/PROJECT/_apis/wit/workitems/12345/revisions?api-version=7.0"
Invoke-RestMethod -Uri $uri -Headers @{Authorization = "Bearer $PAT"} | ConvertTo-Json -Depth 10
```

### 2. Audit Log (All tiers)

**What's captured**:
- Project/organization settings changes
- Permission changes
- Pipeline modifications
- Repository operations (branch creation, policy changes)
- Service connection changes

**Retention**: 90 days (standard), configurable up to 365 days

**Access**: Organization Settings → Audit → Download log

**API export**:

```powershell
$uri = "https://auditservice.dev.azure.com/ORG/_apis/audit/auditlog?api-version=7.1-preview.1"
$audit = Invoke-RestMethod -Uri $uri -Headers @{Authorization = "Bearer $PAT"}
$audit.auditEntries | ConvertTo-Csv | Out-File "audit-log.csv"
```

### 3. Pipeline Run History

**What's captured**:
- Pipeline execution logs
- Job/task results
- Artifact downloads
- Approvals and gates
- Variable values (secure variables masked)

**Retention**: Configurable (30, 60, 90 days, or indefinitely)

**Configuration**: Project Settings → Pipelines → Retention → Set retention days

### 4. Test Results

**What's captured**:
- Test execution results
- Test attachments
- Associated work items
- Code coverage

**Retention**: Permanent (linked to test run)

---

## Compliance Mappings

### SOC 2 Requirements

| Control | Azure DevOps Feature | Evidence Location |
|---------|---------------------|-------------------|
| **Change Management** | Branch policies, PR approvals | Audit log, work item history |
| **Logical Access** | Organization/project permissions | Audit log (permission changes) |
| **System Operations** | Pipeline logs, deployment history | Pipeline run history |
| **Monitoring** | Analytics, dashboards | Analytics views |

### ISO 9001 Requirements

| Clause | Requirement | Azure DevOps Evidence |
|--------|-------------|----------------------|
| **8.5.1** | Control of production | Branch policies, approval gates |
| **8.5.2** | Traceability | Work item links (commit → requirement → test) |
| **8.5.6** | Control of changes | Work item history, audit log |

### FDA (21 CFR Part 11) Requirements

| Requirement | Azure DevOps Implementation | Configuration |
|-------------|----------------------------|---------------|
| **Electronic signatures** | PR approvals, deployment approvals | Approval gates with identity |
| **Audit trails** | Audit log, work item history | Enable audit log export |
| **Record retention** | Configurable pipeline retention | Set to indefinite for validation |

---

## Audit Report Generation

**Monthly compliance report**:

```powershell
# Generate compliance report from Azure DevOps
$org = "YOUR_ORG"
$project = "YOUR_PROJECT"
$pat = $env:AZURE_DEVOPS_PAT

$headers = @{Authorization = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$pat"))}

# Get audit events from last 30 days
$since = (Get-Date).AddDays(-30).ToString("yyyy-MM-ddTHH:mm:ssZ")
$auditUri = "https://auditservice.dev.azure.com/$org/_apis/audit/auditlog?startTime=$since&api-version=7.1-preview.1"
$auditLog = Invoke-RestMethod -Uri $auditUri -Headers $headers

# Get work item changes
$wiqlUri = "https://dev.azure.com/$org/$project/_apis/wit/wiql?api-version=7.0"
$wiql = @{query = "SELECT [System.Id] FROM WorkItems WHERE [System.ChangedDate] >= @StartOfMonth"} | ConvertTo-Json
$workItems = Invoke-RestMethod -Uri $wiqlUri -Method Post -Headers $headers -Body $wiql -ContentType "application/json"

# Generate report
@"
# Compliance Audit Report
**Organization**: $org
**Project**: $project
**Period**: Last 30 days

## Summary
- Audit Events: $($auditLog.auditEntries.Count)
- Work Items Modified: $($workItems.workItems.Count)
- Permission Changes: $($auditLog.auditEntries | Where-Object {$_.actionId -like "*Permissions*"} | Measure-Object | Select-Object -ExpandProperty Count)

## Work Item Traceability
- All work items have linked commits: $(Test-Traceability)
- Branch protection enabled: $(Test-BranchProtection)

## Deployment Approvals
- Production deployments: $(Get-ProductionDeployments)
- Approvals obtained: 100%
"@
```

---

## Data Retention Policies

**Project Settings → Pipelines → Retention**

| Artifact | Recommended Retention | Rationale |
|----------|----------------------|-----------|
| **Work items** | Permanent | Historical record, compliance |
| **Audit log** | 1 year minimum | Regulatory requirements |
| **Pipeline runs** | 90 days standard, 1 year for releases | Deployment evidence |
| **Test results** | Permanent | Verification evidence |
| **Artifacts** | 30-90 days | Build outputs, can be reproduced |

**Enterprise retention override**:

```json
{
  "retentionPolicy": {
    "daysToKeepDeletedReleases": 365,
    "daysToKeep": 365,
    "releasesToKeep": 100
  }
}
```

---

## Common Compliance Gaps

| Gap | Risk | Mitigation |
|-----|------|------------|
| Audit log not exported | 90-day limit, data loss | Monthly export to external storage |
| No branch protection | Unreviewed changes | Enable required reviewers |
| Pipeline retention too short | Can't prove deployment | Extend to 1 year for compliance |
| No work item approval | Requirements not validated | Add approval state to workflow |

---

## Audit Log Export for Long-Term Retention

**Automated export via Logic App / Azure Function**:

```powershell
# Function App triggered daily
param($Timer)

$org = $env:AZURE_DEVOPS_ORG
$pat = $env:AZURE_DEVOPS_PAT

# Export audit log
$uri = "https://auditservice.dev.azure.com/$org/_apis/audit/auditlog?api-version=7.1-preview.1"
$audit = Invoke-RestMethod -Uri $uri -Headers @{Authorization = "Bearer $pat"}

# Store in Azure Blob Storage
$storageAccount = "compliance"
$container = "audit-logs"
$blobName = "audit-$(Get-Date -Format 'yyyyMMdd').json"

$audit | ConvertTo-Json -Depth 10 | Set-AzStorageBlobContent `
  -Container $container `
  -Blob $blobName `
  -Context (Get-AzStorageContext -StorageAccountName $storageAccount)
```

---

## Related Practices

- `./azdo-requirements.md` - Work item traceability
- `./azdo-config-mgmt.md` - Change control audit trail
- `./github-audit-trail.md` - GitHub comparison

---

**Last Updated**: 2026-01-25

```