Deployment Workflow

Overview

Our deployment workflow automates the process of building, testing, and publishing documentation and applications using GitHub Actions and various deployment targets.

Deployment Architecture

• Primary Platform: GitHub Pages for static site hosting
• Automation: GitHub Actions for CI/CD pipelines
• Build Process: mdBook static site generation
• Testing: Automated quality checks and validation
• Monitoring: Deployment status and performance tracking

Deployment Targets

GitHub Pages

• Static Sites: mdBook-generated documentation
• Custom Domains: Professional domain configuration
• HTTPS: Automatic SSL certificate management
• CDN: Global content delivery network
• Analytics: Usage tracking and performance monitoring

Alternative Targets

• Netlify: Alternative static hosting with advanced features
• Vercel: Modern deployment platform for static and dynamic sites
• AWS S3: Cloud storage for static site hosting
• Self-hosted: Custom server deployment options

GitHub Actions Pipeline

Core Deployment Workflow

name: Deploy Documentation

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'book.toml'
      - '.github/workflows/deploy.yml'
  workflow_dispatch:

env:
  MDBOOK_VERSION: '0.4.21'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: ${{ env.MDBOOK_VERSION }}
      
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3
      
      - name: Build documentation
        run: |
          mdbook build
          # Post-processing if needed
          find book -name "*.html" -exec sed -i 's|href="/|href="${{ steps.pages.outputs.base_path }}/|g' {} \;
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: ./book
      
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Multi-environment Deployment

# Multi-environment deployment strategy
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
      - name: Test build
        run: mdbook test && mdbook build
      - name: Upload test artifacts
        uses: actions/upload-artifact@v3
        with:
          name: test-build
          path: book/

  deploy-staging:
    needs: test
    if: github.ref == 'refs/heads/develop'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - name: Deploy to staging
        run: echo "Deploy to staging environment"

  deploy-production:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Deploy to production
        run: echo "Deploy to production environment"

Build Process Optimization

Build Performance

# Optimized build configuration
- name: Cache mdBook binary
  uses: actions/cache@v3
  with:
    path: |
      ~/.cargo/bin/mdbook
      ~/.cargo/.crates.toml
      ~/.cargo/.crates2.json
    key: ${{ runner.os }}-mdbook-${{ env.MDBOOK_VERSION }}

- name: Cache build dependencies
  uses: actions/cache@v3
  with:
    path: |
      book/
      ~/.cache/mdbook
    key: ${{ runner.os }}-build-${{ hashFiles('src/**/*.md', 'book.toml') }}
    restore-keys: |
      ${{ runner.os }}-build-

Asset Optimization

- name: Optimize assets
  run: |
    # Compress images
    find book -name "*.png" -exec pngquant --ext .png --force {} \;
    find book -name "*.jpg" -exec jpegoptim --max=85 {} \;
    
    # Minify CSS and JS
    npm install -g csso-cli uglify-js
    find book -name "*.css" -exec csso {} --output {} \;
    find book -name "*.js" -exec uglifyjs {} --compress --mangle --output {} \;
    
    # Generate compressed versions
    find book -name "*.html" -o -name "*.css" -o -name "*.js" | xargs gzip -k

Quality Assurance

Pre-deployment Testing

# Quality assurance workflow
- name: Lint markdown
  run: |
    npm install -g markdownlint-cli
    markdownlint src/

- name: Check links
  run: |
    mdbook build
    npm install -g markdown-link-check
    find book -name "*.html" -exec markdown-link-check {} \;

- name: Validate HTML
  run: |
    npm install -g html-validate
    html-validate book/**/*.html

- name: Accessibility check
  run: |
    npm install -g pa11y-ci
    pa11y-ci --sitemap http://localhost:3000/sitemap.xml

- name: Performance audit
  run: |
    npm install -g lighthouse-ci
    lhci autorun

Security Scanning

- name: Security scan
  uses: github/super-linter@v4
  env:
    DEFAULT_BRANCH: main
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    VALIDATE_ALL_CODEBASE: false
    VALIDATE_MARKDOWN: true
    VALIDATE_HTML: true
    VALIDATE_CSS: true
    VALIDATE_JAVASCRIPT: true

Deployment Monitoring

Status Monitoring

- name: Deployment notification
  if: always()
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    channel: '#deployments'
    webhook_url: ${{ secrets.SLACK_WEBHOOK }}
    fields: repo,message,commit,author,action,eventName,ref,workflow

- name: Update deployment status
  if: always()
  run: |
    if [ "${{ job.status }}" == "success" ]; then
      curl -X POST "${{ secrets.STATUS_WEBHOOK }}" \
        -H "Content-Type: application/json" \
        -d '{"status": "success", "url": "${{ steps.deployment.outputs.page_url }}"}'
    fi

Performance Monitoring

- name: Lighthouse CI
  run: |
    npm install -g @lhci/cli
    lhci autorun --upload.target=temporary-public-storage
  env:
    LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

- name: Web Vitals monitoring
  run: |
    npm install web-vitals
    node scripts/measure-vitals.js ${{ steps.deployment.outputs.page_url }}

Rollback & Recovery

Automated Rollback

# Rollback workflow
name: Rollback Deployment

on:
  workflow_dispatch:
    inputs:
      target_commit:
        description: 'Commit SHA to rollback to'
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout target commit
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.inputs.target_commit }}
      
      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
      
      - name: Build and deploy rollback
        run: |
          mdbook build
          # Deploy using same process as main deployment

Backup Strategy

- name: Backup current deployment
  run: |
    # Create backup before deployment
    curl -o backup.tar.gz https://site.com/backup-endpoint
    aws s3 cp backup.tar.gz s3://backup-bucket/$(date +%Y%m%d-%H%M%S)/

Environment Management

Configuration Management

# Environment-specific configuration
- name: Configure environment
  run: |
    case "${{ github.ref }}" in
      refs/heads/main)
        export BASE_URL="https://docs.example.com"
        export ANALYTICS_ID="GA-PRODUCTION"
        ;;
      refs/heads/develop)
        export BASE_URL="https://staging-docs.example.com"
        export ANALYTICS_ID="GA-STAGING"
        ;;
    esac
    
    # Update configuration
    sed -i "s|BASE_URL_PLACEHOLDER|${BASE_URL}|g" book.toml
    sed -i "s|ANALYTICS_ID_PLACEHOLDER|${ANALYTICS_ID}|g" theme/index.hbs

Secret Management

- name: Configure secrets
  env:
    API_KEY: ${{ secrets.API_KEY }}
    DATABASE_URL: ${{ secrets.DATABASE_URL }}
  run: |
    echo "API_KEY=${API_KEY}" >> .env
    echo "DATABASE_URL=${DATABASE_URL}" >> .env

Deployment Strategies

Blue-Green Deployment

# Blue-green deployment strategy
- name: Deploy to blue environment
  run: deploy-to-blue.sh
  
- name: Health check blue environment
  run: health-check.sh blue
  
- name: Switch traffic to blue
  if: success()
  run: switch-traffic.sh blue
  
- name: Cleanup green environment
  run: cleanup-environment.sh green

Canary Deployment

# Canary deployment strategy
- name: Deploy canary version
  run: |
    # Deploy to 5% of traffic
    deploy-canary.sh 5
    
- name: Monitor canary metrics
  run: |
    sleep 300  # Wait 5 minutes
    check-metrics.sh canary
    
- name: Gradual rollout
  run: |
    deploy-canary.sh 25   # 25% traffic
    sleep 300
    deploy-canary.sh 100  # Full rollout

Learning & Optimization

Deployment Metrics

• Build Time: Track build performance over time
• Deployment Frequency: Monitor deployment cadence
• Success Rate: Track deployment success/failure rates
• Recovery Time: Measure time to recover from failures
• Lead Time: Time from commit to production

Continuous Improvement

# Metrics collection
- name: Collect deployment metrics
  run: |
    echo "BUILD_TIME=${{ steps.build.outputs.time }}" >> metrics.txt
    echo "DEPLOY_TIME=${{ steps.deploy.outputs.time }}" >> metrics.txt
    curl -X POST metrics-endpoint -d @metrics.txt

Integration with Development Workflow

Git Workflow Integration

• Branch-based Deployment: Automatic deployment from specific branches
• Tag-based Releases: Deploy specific versions using Git tags
• Pull Request Previews: Deploy preview environments for PRs
• Commit-triggered Builds: Automatic builds on code changes

Development Tool Integration

• IDE Integration: Deploy directly from development environment
• Local Testing: Test deployment process locally
• Staging Environments: Pre-production testing environments
• Feature Flags: Control feature rollout independently of deployment