@deftai/directive-content 0.55.0

package/deployments/fly-io/via-github-actions.md

@@ -0,0 +1,695 @@
+# Deploy via GitHub Actions
+
+Automate Fly.io deployments using GitHub Actions for continuous integration and delivery. Deploy on every push with automated testing, secrets management, and multi-environment support.
+
+## Overview
+
+Fly.io provides official GitHub Actions for seamless CI/CD:
+- **Automatic Deployments**: Deploy on push to main
+- **PR Preview Apps**: Deploy preview environments for pull requests  
+- **Multi-Environment**: Separate staging and production
+- **Secrets Management**: Secure FLY_API_TOKEN handling
+- **Matrix Deployments**: Deploy multiple apps in parallel
+
+## Prerequisites
+
+- GitHub repository with your application code
+- Fly.io account
+- Fly.io API token
+
+## Quick Setup
+
+### 1. Generate Fly.io API Token
+
+```bash
+# Generate deploy token
+fly auth token
+
+# Copy the token for GitHub secrets
+```
+
+### 2. Add GitHub Secrets
+
+Go to repository → Settings → Secrets and variables → Actions
+
+Add:
+- `FLY_API_TOKEN` - Your Fly.io API token
+
+### 3. Create Workflow File
+
+Create `.github/workflows/fly.yml`:
+
+```yaml
+name: Deploy to Fly.io
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Deploy app
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+## Official Fly.io Actions
+
+### Setup flyctl Action
+
+```yaml
+- uses: superfly/flyctl-actions/setup-flyctl@master
+  with:
+    version: latest  # or specific version like 0.0.500
+```
+
+### Deploy Action
+
+```yaml
+- uses: superfly/flyctl-actions@master
+  with:
+    args: "deploy --remote-only"
+  env:
+    FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+## Workflow Examples
+
+### Basic Production Deployment
+
+```yaml
+name: Fly Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Deploy to production
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup flyctl
+        uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy to Fly
+        run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Deploy with Tests
+
+```yaml
+name: Test and Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+      
+      - run: npm ci
+      - run: npm test
+      - run: npm run lint
+
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Multi-Environment Deployment
+
+```yaml
+name: Deploy Pipeline
+
+on:
+  push:
+    branches:
+      - main
+      - staging
+
+jobs:
+  deploy-staging:
+    if: github.ref == 'refs/heads/staging'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - run: flyctl deploy --app my-app-staging --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+
+  deploy-production:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - run: flyctl deploy --app my-app-production --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### PR Preview Deployments
+
+```yaml
+name: PR Preview
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    
+    # Don't run on closed PRs unless we're cleaning up
+    if: github.event.action != 'closed' || github.event.pull_request.merged == true
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy PR Preview
+        if: github.event.action != 'closed'
+        run: |
+          PR_NUMBER=${{ github.event.pull_request.number }}
+          flyctl deploy \
+            --app my-app-pr-$PR_NUMBER \
+            --remote-only \
+            --auto-confirm
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+      
+      - name: Comment PR with URL
+        if: github.event.action != 'closed'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = ${{ github.event.pull_request.number }};
+            github.rest.issues.createComment({
+              issue_number: pr,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `🚀 Preview deployed: https://my-app-pr-${pr}.fly.dev`
+            });
+      
+      - name: Destroy PR Preview
+        if: github.event.action == 'closed'
+        run: |
+          PR_NUMBER=${{ github.event.pull_request.number }}
+          flyctl apps destroy my-app-pr-$PR_NUMBER --yes || true
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Matrix Deploy (Multiple Apps)
+
+```yaml
+name: Deploy All Apps
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        app:
+          - name: api
+            path: ./apps/api
+          - name: web
+            path: ./apps/web
+          - name: worker
+            path: ./apps/worker
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy ${{ matrix.app.name }}
+        run: flyctl deploy --config ${{ matrix.app.path }}/fly.toml --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Deploy with Docker Build
+
+```yaml
+name: Docker Build and Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      - name: Build and push to Fly registry
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: registry.fly.io/my-app:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy to Fly
+        run: flyctl deploy --image registry.fly.io/my-app:${{ github.sha }}
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+## Advanced Configurations
+
+### Database Migrations
+
+```yaml
+name: Deploy with Migrations
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Run database migrations
+        run: |
+          flyctl ssh console -C "npm run migrate"
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+      
+      - name: Deploy application
+        run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Canary Deployment
+
+```yaml
+name: Canary Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  canary:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy canary
+        run: flyctl deploy --strategy canary --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+      
+      - name: Wait and monitor
+        run: sleep 300  # Wait 5 minutes
+      
+      - name: Check health metrics
+        run: |
+          STATUS=$(flyctl status --json | jq -r '.health_checks[0].status')
+          if [ "$STATUS" != "passing" ]; then
+            echo "Health checks failing, rolling back"
+            flyctl releases rollback
+            exit 1
+          fi
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Multi-Region Deployment
+
+```yaml
+name: Multi-Region Deploy
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy to multiple regions
+        run: |
+          flyctl deploy --remote-only
+          flyctl regions add iad lhr syd
+          flyctl scale count 3
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Deploy with Secrets
+
+```yaml
+name: Deploy with Runtime Secrets
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Set secrets
+        run: |
+          echo "${{ secrets.ENV_FILE }}" | flyctl secrets import
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+      
+      - name: Deploy
+        run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+## Deployment Strategies
+
+### Blue-Green Deployment
+
+```yaml
+- name: Blue-Green Deploy
+  run: flyctl deploy --strategy bluegreen --remote-only
+  env:
+    FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Rolling Deployment
+
+```yaml
+# Configure in fly.toml
+[deploy]
+  strategy = "rolling"
+  max_unavailable = 1
+
+# Then deploy normally
+- run: flyctl deploy --remote-only
+```
+
+### Immediate Deployment
+
+```yaml
+# Deploy without waiting for health checks
+- run: flyctl deploy --remote-only --now
+  env:
+    FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+## Monitoring & Notifications
+
+### Slack Notifications
+
+```yaml
+name: Deploy with Notifications
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy
+        id: deploy
+        run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+      
+      - name: Notify Slack on success
+        if: success()
+        uses: slackapi/slack-github-action@v1
+        with:
+          payload: |
+            {
+              "text": "✅ Deployed to Fly.io successfully",
+              "blocks": [
+                {
+                  "type": "section",
+                  "text": {
+                    "type": "mrkdwn",
+                    "text": "✅ *Deployment Successful*\nCommit: ${{ github.sha }}\nAuthor: ${{ github.actor }}"
+                  }
+                }
+              ]
+            }
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
+      
+      - name: Notify Slack on failure
+        if: failure()
+        uses: slackapi/slack-github-action@v1
+        with:
+          payload: |
+            {
+              "text": "❌ Fly.io deployment failed"
+            }
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+### Post-Deployment Health Check
+
+```yaml
+- name: Health Check
+  run: |
+    sleep 30
+    STATUS_CODE=$(curl -s -o /dev/null -w "%{http_code}" https://my-app.fly.dev/health)
+    if [ $STATUS_CODE -ne 200 ]; then
+      echo "Health check failed with status $STATUS_CODE"
+      flyctl releases rollback
+      exit 1
+    fi
+```
+
+## Best Practices
+
+### 1. Use GitHub Environments
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: production  # Requires manual approval
+```
+
+### 2. Pin flyctl Version
+
+```yaml
+- uses: superfly/flyctl-actions/setup-flyctl@master
+  with:
+    version: 0.0.500  # Pin to specific version
+```
+
+### 3. Secure Secrets
+
+```bash
+# Use GitHub environment secrets for sensitive data
+# Never commit FLY_API_TOKEN to repository
+```
+
+### 4. Deploy on Merge Only
+
+```yaml
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  deploy:
+    if: github.event.pull_request.merged == true
+```
+
+### 5. Use Build Cache
+
+```yaml
+- uses: docker/build-push-action@v5
+  with:
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+```
+
+## Troubleshooting
+
+### Deployment Timeout
+
+```yaml
+- name: Deploy with longer timeout
+  run: flyctl deploy --remote-only --wait-timeout 900
+  env:
+    FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+### Debug Mode
+
+```yaml
+- name: Deploy with verbose logging
+  run: flyctl deploy --remote-only --verbose
+  env:
+    FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+    FLY_LOG_LEVEL: debug
+```
+
+### Authentication Issues
+
+```yaml
+- name: Verify authentication
+  run: flyctl auth whoami
+  env:
+    FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+```
+
+## Complete Example
+
+```yaml
+name: Complete CI/CD Pipeline
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize]
+
+env:
+  FLY_APP_NAME: my-app
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          cache: 'npm'
+      
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+
+  deploy-preview:
+    if: github.event_name == 'pull_request'
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy PR preview
+        run: |
+          PR_NUMBER=${{ github.event.pull_request.number }}
+          flyctl deploy \
+            --app ${{ env.FLY_APP_NAME }}-pr-$PR_NUMBER \
+            --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+
+  deploy-production:
+    if: github.ref == 'refs/heads/main'
+    needs: test
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: superfly/flyctl-actions/setup-flyctl@master
+      
+      - name: Deploy to production
+        run: flyctl deploy --remote-only
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+      
+      - name: Health check
+        run: |
+          sleep 30
+          curl -f https://${{ env.FLY_APP_NAME }}.fly.dev/health || (
+            flyctl releases rollback && exit 1
+          )
+        env:
+          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
+      
+      - name: Notify team
+        if: success()
+        run: echo "Deployed successfully to production"
+```
+
+## References
+
+- [Fly.io GitHub Actions](https://fly.io/docs/app-guides/continuous-deployment-with-github-actions/)
+- [flyctl-actions Repository](https://github.com/superfly/flyctl-actions)
+- [GitHub Actions Documentation](https://docs.github.com/actions)
+- [Deployment Strategies](https://fly.io/docs/reference/deployment/)