Skip to content

Migration Guide

1. Overview

This guide provides step-by-step instructions for migrating existing CI/CD pipelines to ATTEST, including strategies for different scenarios and risk mitigation approaches.

2. Migration Strategies

The safest approach is to migrate incrementally:

# Phase 1: Add ATTEST alongside existing CI
attest init --coexist
git add attest.yaml .attest/
git commit -m "Add ATTEST configuration"

# Phase 2: Parallel execution
attest migrate --parallel-mode

2.2 Big Bang Migration

For smaller projects or when tight control is needed:

# Complete migration in one step
attest migrate --complete --backup-existing

2.3 Hybrid Approach

Keep both systems running for different environments:

# Different strategies per environment
environments:
  development:
    migration_strategy: "traditional"
  staging:
    migration_strategy: "parallel"
  production:
    migration_strategy: "attest_only"

3. Pre-Migration Assessment

3.1 Current State Analysis

# Analyze existing CI/CD setup
attest analyze ci-config --input .github/workflows/
attest analyze dependencies --scan-all
attest analyze security-posture --compliance-check

# Generated report:
Migration Readiness Report
==========================
Current CI System: GitHub Actions
Complexity Score: Medium (7/10)
Security Gaps: 3 issues found
Estimated Migration Time: 2-3 weeks
Risk Level: Low

3.2 Compatibility Check

# Check tool compatibility
attest compat check --tools npm,docker,kubectl
attest compat check --platforms github-actions,gitlab-ci

# Results:
Tool Compatibility:
- npm: Fully Compatible
- docker: Compatible (minor config needed)
- kubectl: Compatible
- maven: Requires plugin update

4. Migration Planning

4.1 Migration Plan Template

# migration-plan.yaml
migration:
  timeline: "4 weeks"
  phases:
    - name: "Preparation"
      duration: "1 week"
      tasks:
        - "Team training"
        - "Environment setup"
        - "Backup current system"

    - name: "Pilot Migration"
      duration: "1 week"
      scope: "Non-critical workloads"
      rollback_plan: "Immediate revert"

    - name: "Staged Rollout"
      duration: "1 week"
      scope: "Development and staging"

    - name: "Production Migration"
      duration: "1 week"
      scope: "Production workloads"

  success_criteria:
    - "Build time improvement >= 20%"
    - "Zero security regressions"
    - "Team adoption >= 80%"

  rollback_triggers:
    - "Build failure rate > 5%"
    - "Performance degradation > 50%"
    - "Critical security issues"

5. Step-by-Step Migration

5.1 Step 1: Environment Preparation

# Install ATTEST
curl -sSL https://install.attest.continuu.ms | bash
attest version

# Initialize workspace
cd your-project/
attest init

# Configure global settings
attest config set cache.enabled true
attest config set verification.strict_mode false  # Initially

5.2 Step 2: Configuration Migration

# Convert existing CI configuration
attest convert --from .github/workflows/ci.yml --to attest.yaml

# Review generated configuration
attest config validate
attest config show --format yaml

5.3 Step 3: Parallel Execution Setup

# .github/workflows/hybrid.yml
name: Hybrid CI/CD
on: [push, pull_request]

jobs:
  traditional-build:
    runs-on: ubuntu-latest
    steps:
      - name: Traditional Build
        run: |
          npm install
          npm test
          npm run build

  attest-build:
    runs-on: ubuntu-latest
    steps:
      - name: ATTEST Build
        run: |
          attest run --sign
        continue-on-error: true  # Don't fail initially

  compare-results:
    needs: [traditional-build, attest-build]
    runs-on: ubuntu-latest
    steps:
      - name: Compare Outputs
        run: |
          attest compare-builds \
            --traditional-output ./dist-traditional/ \
            --attest-output ./dist-attest/ \
            --report comparison-report.html

5.4 Step 4: Validation and Testing

# Run validation tests
attest test migration-plan.yaml
attest benchmark --compare-with-baseline

# Validate artifacts
attest verify receipts/*.yaml --strict
attest validate artifacts --against-baseline

5.5 Step 5: Progressive Rollout

# Enable ATTEST for specific branches
attest migrate enable --branches feature/*,develop

# Monitor performance
attest monitor --duration 7d --alerts-to slack://webhook

# Gradual expansion
attest migrate expand --to-branches main --confidence-threshold 95%

6. Platform-Specific Migration

6.1 GitHub Actions Migration

# Convert GitHub Actions workflow
attest convert github-actions \
  --input .github/workflows/ \
  --output attest.yaml \
  --preserve-secrets

# Generated migration summary:
Migration Summary:
- 12 jobs converted
- 3 custom actions require manual review
- 2 marketplace actions need alternatives
- Estimated 15% performance improvement

6.2 GitLab CI Migration

# Convert GitLab CI configuration
attest convert gitlab-ci \
  --input .gitlab-ci.yml \
  --output attest.yaml \
  --preserve-variables

# Handle GitLab-specific features
attest migrate gitlab-features \
  --artifacts .gitlab-ci.yml \
  --cache-config

6.3 Jenkins Migration

# Convert Jenkins pipeline
attest convert jenkins \
  --input Jenkinsfile \
  --output attest.yaml \
  --preserve-node-labels

# Migrate Jenkins plugins
attest migrate jenkins-plugins \
  --list-alternatives \
  --suggest-replacements

7. Data Migration

7.1 Build History Migration

# Import historical build data
attest import build-history \
  --from jenkins \
  --url $JENKINS_URL \
  --credentials jenkins-creds.json \
  --projects myapp,mylib

# Import artifacts
attest import artifacts \
  --from s3://old-artifacts-bucket/ \
  --generate-receipts \
  --verify-integrity

7.2 Configuration Migration

# Migrate environment variables
attest import env-vars \
  --from .env.example \
  --to .attest/config.yaml

# Migrate secrets (requires manual review)
attest import secrets \
  --from-vault vault.company.com \
  --mapping secrets-mapping.yaml

8. Risk Mitigation

8.1 Rollback Procedures

# Prepare rollback plan
attest rollback prepare \
  --backup-location s3://backup-bucket/ \
  --rollback-script rollback.sh

# Quick rollback if needed
attest rollback execute \
  --to-commit abc123 \
  --preserve-artifacts

8.2 Monitoring During Migration

# migration-monitoring.yaml
monitoring:
  alerts:
    - name: "migration-failure-rate"
      condition: "failure_rate > 5%"
      action: "pause-migration"

    - name: "performance-degradation"
      condition: "build_time_increase > 50%"
      action: "investigate"

  dashboards:
    - "migration-progress"
    - "performance-comparison"
    - "error-tracking"

8.3 Safety Measures

# Enable safety checks
attest migrate --safety-checks \
  --max-failure-rate 5% \
  --rollback-on-critical \
  --require-manual-approval

# Canary deployment
attest migrate canary \
  --percentage 10% \
  --duration 24h \
  --success-criteria migration-criteria.yaml

9. Common Migration Scenarios

9.1 Monorepo Migration

# Migrate large monorepo
attest migrate monorepo \
  --discovery-mode auto \
  --parallel-workspaces \
  --shared-cache

# Handle workspace dependencies
attest config set workspace.dependency_resolution smart

9.2 Multi-Platform Builds

# Migrate cross-platform builds
attest migrate platforms \
  --from docker-compose.yml \
  --targets linux/amd64,linux/arm64,darwin/amd64

# Configure platform-specific steps
attest config set platforms.build_matrix auto

9.3 Compliance-Heavy Environments

# Migrate regulated environments
attest migrate compliance \
  --framework SOX,HIPAA,PCI-DSS \
  --preserve-audit-trails \
  --require-signatures

# Enable compliance features
attest config set compliance.strict_mode true
attest config set verification.require_all_steps true

10. Post-Migration Tasks

10.1 Performance Optimization

# Optimize after migration
attest optimize --profile production
attest tune cache --target-hit-rate 85%
attest tune performance --baseline pre-migration-metrics.json

10.2 Team Training

# Generate training materials
attest docs generate-training \
  --level beginner,intermediate \
  --format presentation,hands-on

# Team onboarding
attest onboard team \
  --interactive \
  --custom-examples your-project/

10.3 Success Validation

# Validate migration success
attest validate migration \
  --success-criteria migration-plan.yaml \
  --generate-report

# Migration Success Report:
# - Performance: 25% improvement
# - Security: 0 regressions
# - Team Adoption: 92%
# - Cost Savings: $2,400/month

11. Troubleshooting Migration Issues

11.1 Common Problems

# Build failures after migration
attest debug build-failure \
  --compare-with-baseline \
  --suggest-fixes

# Performance regressions
attest debug performance \
  --profile current \
  --compare-with pre-migration.profile

# Configuration issues
attest debug config \
  --validate-all \
  --suggest-optimizations

11.2 Support Resources

# Get migration help
attest help migration
attest community --topic migration
attest support --priority high --issue "migration-blocker"

# Professional services
attest migrate --with-support \
  --contact contact@alien6.com

12. Best Practices

12.1 Planning

  1. Start with assessment - Understand current state fully
  2. Plan incrementally - Avoid big-bang migrations
  3. Test thoroughly - Validate each phase
  4. Monitor continuously - Watch for regressions
  5. Prepare rollbacks - Always have an escape plan

12.2 Execution

  1. Begin with non-critical workloads
  2. Maintain parallel systems during transition
  3. Involve the team early and often
  4. Document everything for future reference
  5. Celebrate milestones to maintain momentum

12.3 Long-term Success

  1. Optimize post-migration for best performance
  2. Train teams on ATTEST best practices
  3. Regular reviews of migration outcomes
  4. Continuous improvement of processes
  5. Share learnings with the broader team

13. Migration Timeline Template

13.1 Week 1: Preparation

  • Team training sessions
  • Environment setup
  • Current state analysis
  • Migration plan finalization

13.2 Week 2: Pilot Migration

  • Non-critical workload migration
  • Parallel execution setup
  • Initial performance testing
  • Issue identification and resolution

13.3 Week 3: Staged Rollout

  • Development environment migration
  • Staging environment migration
  • Performance optimization
  • Team feedback incorporation

13.4 Week 4: Production Migration

  • Production workload migration
  • Final validation
  • Performance monitoring
  • Documentation updates

This migration guide provides a comprehensive approach to safely transitioning to ATTEST while minimizing risks and maximizing benefits.