CI/CD Pipeline

Complete automation pipeline for Prism Package Manager.

---

Overview

Prism uses GitHub Actions for continuous integration and deployment with a multi-stage workflow:

Figure 1: CI/CD Pipeline

flowchart LR
    F["feature/*"] -->|PR, 1 approval| DEV["dev"]
    DEV -->|PR, 1 approval| STAGE["stage"]
    STAGE -->|PR, 2 approvals| MAIN["main"]
    F -.->|Basic CI| F
    DEV -.->|Full CI| DEV
    STAGE -.->|Full CI| STAGE
    MAIN -.->|Release| MAIN

    style F fill:#8b5cf6,color:#fff
    style DEV fill:#3b82f6,color:#fff
    style STAGE fill:#f59e0b,color:#000
    style MAIN fill:#10b981,color:#fff

4 Workflows:

1. ci.yml - PR checks (lint, test, coverage, security)
2. deploy-dev.yml - Dev deployment (7-day artifacts)
3. deploy-stage.yml - Stage deployment (30-day artifacts)
4. deploy-main.yml - Production deployment (90-day artifacts + releases)

---

Makefile Commands

Quick Reference

make help              # See all 40+ commands

# Development
make dev               # Quick start (install + run)
make run               # Start installer server

# Testing
make test              # Fast tests (unit + CLI)
make test-all          # All tests (590+ tests)
make test-coverage     # With coverage report

# Code Quality
make format            # Auto-format (black + isort)
make lint              # Run linters (flake8 + mypy)
make format-check      # Check format (CI mode)

# CI/CD
make check             # All CI checks
make pre-commit        # Quick pre-commit checks
make ci                # Full CI pipeline

See all commands: make help

---

Workflows

1. Pull Request Checks (ci.yml)

Trigger: PR to dev, stage, or main

Jobs (run in parallel):

• ✅ Lint → isort, black, flake8, mypy
• ✅ Unit Tests → pytest tests/unit/
• ✅ CLI Tests → pytest tests/e2e/test_cli_installer.py
• ✅ E2E Tests → Playwright browser tests
• ✅ Coverage → Generate coverage report
• ✅ Security → bandit + safety scans
• ✅ Summary → Final gate (all must pass)

Artifacts:

• Test results (HTML reports)
• Coverage reports (HTML)
• Playwright traces (on failure)
• Security scan results

2. Dev Deployment (deploy-dev.yml)

Trigger: Push to dev branch

Jobs:

1. Quick Tests → lint + unit (fast feedback)
2. Build → Create dev-{sha}.tar.gz
3. Deploy → Deploy to dev environment
4. Notify → Send notifications

Artifacts:

• prism-dev-{sha}.tar.gz
• Retention: 7 days

3. Stage Deployment (deploy-stage.yml)

Trigger: Push to stage branch

Jobs:

1. Comprehensive Tests → All tests + coverage
2. Build RC → Release candidate package
3. Deploy → Deploy to stage
4. Smoke Tests → Verify deployment
5. Notify → Send notifications

Artifacts:

• prism-stage-{sha}.tar.gz
• Python wheel (.whl)
• Source dist (.tar.gz)
• SHA256 checksums
• Retention: 30 days

4. Production Deployment (deploy-main.yml)

Trigger: Push to main branch OR git tag

Jobs:

1. Full Test Suite → All 590+ tests
2. Build Distribution → Wheel + source + archive
3. Publish Artifacts → Upload to GitHub
4. GitHub Release → Auto-create (if tagged)
5. Deploy Production → Deploy to prod
6. Notify → Send notifications

Artifacts:

• prism-release-{version}.tar.gz (complete source)
• Python wheel (.whl)
• Source distribution (.tar.gz)
• SHA256SUMS.txt
• Retention: 90 days

GitHub Release (for tags):

• Automatic release notes
• All artifacts attached
• Installation instructions

---

Branch Protection

Main Branch (Production)

• ✅ 2 required approvals
• ✅ All CI checks must pass
• ✅ Conversation resolution required
• ✅ Signed commits required
• ✅ Linear history enforced
• ✅ Admins cannot bypass
• ✅ CODEOWNERS review required

Stage Branch (Pre-Production)

• ✅ 1 required approval
• ✅ All CI checks must pass
• ✅ Conversation resolution required
• ✅ Linear history enforced

Dev Branch (Development)

• ✅ 1 required approval
• ✅ Basic CI checks (lint, unit, CLI)
• ✅ Conversation resolution required

---

Development Workflow

1. Create Feature Branch

git checkout dev
git pull origin dev
git checkout -b feature/my-feature

2. Make Changes

# Write code
vim scripts/my_feature.py

# Format and lint
make format
make lint

# Test
make test

# Commit
git add .
git commit -m "feat: add my feature"

3. Push and Create PR

git push origin feature/my-feature

# Create PR on GitHub
# Fill out PR template

4. CI Runs Automatically

• Linting
• Unit tests
• CLI tests
• E2E tests
• Coverage
• Security scan

5. Code Review

• Request reviews from CODEOWNERS
• Address feedback
• Resolve conversations

6. Merge

• All checks green ✅
• Required approvals received
• Squash and merge to dev

---

Release Process

Standard Release (dev → stage → main)

Figure 2: Release Process

flowchart TB
    F["feature/xyz"] -->|PR| DEV["dev"]
    DEV -->|Fast CI, deploy| DEV_ENV["Dev Environment"]
    DEV_ENV -->|7-day artifacts| PROMOTE1{"Promote?"}
    PROMOTE1 -->|PR| STAGE["stage"]
    STAGE -->|Full CI + coverage| STAGE_ENV["Stage Environment"]
    STAGE_ENV -->|Smoke tests, 30-day artifacts| PROMOTE2{"Promote?"}
    PROMOTE2 -->|PR, 2 approvals| MAIN["main"]
    MAIN -->|Full test suite| PROD["Production"]
    PROD -->|90-day artifacts| TAG{"Tag release?"}
    TAG -->|git tag| RELEASE["GitHub Release"]

    style F fill:#8b5cf6,color:#fff
    style DEV fill:#3b82f6,color:#fff
    style DEV_ENV fill:#3b82f6,color:#fff
    style STAGE fill:#f59e0b,color:#000
    style STAGE_ENV fill:#f59e0b,color:#000
    style MAIN fill:#10b981,color:#fff
    style PROD fill:#10b981,color:#fff
    style RELEASE fill:#10b981,color:#fff

Hotfix Release (emergency)

# 1. Branch from main
git checkout main
git checkout -b hotfix/critical-bug

# 2. Fix and test
make test-all

# 3. PR directly to main (with justification)
hotfix/critical-bug → main (PR)
  ↓
  Requires 2 approvals + CI green

# 4. Backport to stage and dev
git checkout stage
git cherry-pick <commit-sha>
git push origin stage

git checkout dev
git cherry-pick <commit-sha>
git push origin dev

---

Local CI Simulation

Run what CI runs locally:

# All checks
make ci

# Step by step
make format-check  # Check formatting
make lint          # Run linters
make test-all      # Run all tests

# Pre-commit checks (quick)
make pre-commit

---

Setup CI/CD

Option 1: Automated (GitHub CLI)

cd .github
./setup-cicd.sh

# Follow prompts:
# 1. Enter repo (owner/repo)
# 2. Script sets up branch protection
# 3. Update CODEOWNERS with team names
# 4. Done!

Option 2: Manual

1. Go to Settings → Branches
2. Add protection rules for:
   • main (2 approvals, all checks)
   • stage (1 approval, all checks)
   • dev (1 approval, basic checks)
3. See .github/BRANCH_PROTECTION.md for details

---

Monitoring

View Workflow Runs

gh run list                    # All runs
gh run view <run-id>           # Specific run
gh run watch                   # Watch live

Download Artifacts

gh run download <run-id> -n prism-release-v1.0.0

View Test Reports

1. Actions tab → Click run
2. Scroll to Artifacts
3. Download test-results
4. Open playwright-report/report.html

---

Troubleshooting

CI Failing?

# Run locally what CI runs
make ci

# Or step by step
make format-check  # Check formatting
make lint          # Check linting
make test-all      # Run all tests

Playwright Tests Failing?

# Run with trace viewer
make test-trace

# View trace
make show-trace

# Or run headed (see browser)
pytest tests/e2e/ --headed --slowmo=500

Merge Conflicts?

# Update your branch
git fetch origin
git rebase origin/dev  # or stage/main

# Resolve conflicts
git add .
git rebase --continue

# Force push (only to feature branches!)
git push --force-with-lease

Can’t Merge PR?

Check:

1. Are all CI checks passing? ✅
2. Do you have required approvals?
3. Are all conversations resolved?
4. Is branch up to date with base?
5. Are you merging to the right branch?

---

Secrets Management

Required Secrets

Set in GitHub repo settings:

GITHUB_TOKEN          # Auto-provided by GitHub

# Optional (for notifications)
SLACK_WEBHOOK_URL     # Slack notifications
TEAMS_WEBHOOK_URL     # Teams notifications

# Optional (for deployments)
DEPLOY_SSH_KEY        # SSH deployments
DEPLOY_API_TOKEN      # API-based deployments

Set Secrets

gh secret set SLACK_WEBHOOK_URL
gh secret set DEPLOY_SSH_KEY < ~/.ssh/deploy_key

---

Status

Component	Status
Makefile	✅ Complete (40+ commands)
PR Checks	✅ Complete (7 jobs)
Dev Deploy	✅ Complete
Stage Deploy	✅ Complete
Prod Deploy	✅ Complete
Branch Protection	⚠️ Setup Required
Documentation	✅ Complete
Tests	✅ Working (590+ tests)

---

Resources

• GitHub Actions Docs
• Makefile Guide
• Branch Protection
• Pull Request Template
• CODEOWNERS

---

Questions? Open an issue