# Deploy via GitHub Actions

Automate agent deployments using GitHub Actions for continuous integration and delivery. Push code to trigger automatic deployments with built-in testing, validation, and rollback capabilities.

## Overview

Agentuity integrates seamlessly with GitHub Actions to provide:
- **Automatic Deployments**: Deploy on push to main
- **Preview Deployments**: Unique URLs for every pull request
- **Environment Isolation**: Separate staging and production
- **Rollback Protection**: Automatic rollback on errors
- **Secrets Management**: Secure credential handling

## Prerequisites

- GitHub repository with your agent code
- Agentuity account
- Agentuity API key or GitHub App integration

## Quick Setup

### 1. Get Agentuity API Key

```bash
# Generate deployment API key
agentuity apikey create --name github-actions --scope deploy

# Copy the key for GitHub secrets
```

### 2. Add GitHub Secrets

Go to your repository → Settings → Secrets and variables → Actions

Add these secrets:
- `AGENTUITY_API_KEY` - Your Agentuity API key
- `AGENTUITY_PROJECT_ID` - Your project ID (optional)

### 3. Create Workflow File

Create `.github/workflows/deploy.yml`:

```yaml
name: Deploy to Agentuity

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test
      
      - name: Install Agentuity CLI
        run: |
          curl -fsS https://agentuity.sh | sh
          echo "$HOME/.agentuity/bin" >> $GITHUB_PATH
      
      - name: Deploy to Agentuity
        env:
          AGENTUITY_API_KEY: ${{ secrets.AGENTUITY_API_KEY }}
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            agentuity deploy --preview
          else
            agentuity deploy --production
          fi
```

## Workflow Examples

### Production Deployment

```yaml
name: Production Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build
        run: npm run build
      
      - name: Run tests
        run: npm test
      
      - name: Deploy to Agentuity
        uses: agentuity/deploy-action@v1
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          environment: production
```

### Multi-Environment with Manual Approval

```yaml
name: Deploy Pipeline

on:
  push:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm ci
      - run: npm test
      - run: npm run lint

  deploy-staging:
    needs: test
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - uses: agentuity/deploy-action@v1
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          environment: staging

  deploy-production:
    needs: deploy-staging
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: agentuity/deploy-action@v1
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          environment: production
          wait-for-completion: true
```

### Preview Deployments for PRs

```yaml
name: PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy Preview
        uses: agentuity/deploy-action@v1
        id: deploy
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          preview: true
      
      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `🚀 Preview deployed to: ${{ steps.deploy.outputs.url }}`
            })
```

### Canary Deployment

```yaml
name: Canary Deploy

on:
  workflow_dispatch:
    inputs:
      traffic_percentage:
        description: 'Percentage of traffic for canary'
        required: true
        default: '10'

jobs:
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy Canary
        uses: agentuity/deploy-action@v1
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          canary: true
          traffic-percentage: ${{ inputs.traffic_percentage }}
      
      - name: Monitor Canary
        run: |
          # Wait and check error rates
          sleep 300
          agentuity metrics error-rate --last 5m
      
      - name: Promote or Rollback
        run: |
          ERROR_RATE=$(agentuity metrics error-rate --last 5m --json | jq -r '.rate')
          if (( $(echo "$ERROR_RATE < 0.01" | bc -l) )); then
            agentuity canary promote
          else
            agentuity canary rollback
          fi
```

## Agentuity Deploy Action

### Basic Usage

```yaml
- uses: agentuity/deploy-action@v1
  with:
    api-key: ${{ secrets.AGENTUITY_API_KEY }}
```

### All Options

```yaml
- uses: agentuity/deploy-action@v1
  id: deploy
  with:
    # Required
    api-key: ${{ secrets.AGENTUITY_API_KEY }}
    
    # Optional
    project-id: my-agent
    environment: production  # or staging, preview
    preview: false  # Set true for PR previews
    wait-for-completion: true
    timeout: 600  # seconds
    
    # Canary options
    canary: false
    traffic-percentage: 10
    
    # Build options
    working-directory: ./
    build-command: npm run build
    
    # Validation
    run-tests: true
    test-command: npm test
    
    # Deployment options
    regions: us-east-1,eu-west-1
    min-instances: 0
    max-instances: 10

outputs:
  url: ${{ steps.deploy.outputs.url }}
  deployment-id: ${{ steps.deploy.outputs.deployment-id }}
  version: ${{ steps.deploy.outputs.version }}
```

## Advanced Workflows

### Matrix Deployment (Multiple Agents)

```yaml
name: Deploy All Agents

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        agent: [chat, search, analytics]
    steps:
      - uses: actions/checkout@v4
      
      - uses: agentuity/deploy-action@v1
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          project-id: ${{ matrix.agent }}
          working-directory: ./agents/${{ matrix.agent }}
```

### Scheduled Deployments

```yaml
name: Nightly Deploy

on:
  schedule:
    - cron: '0 2 * * *'  # 2 AM daily
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: agentuity/deploy-action@v1
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          environment: staging
```

### Deployment with Notifications

```yaml
name: Deploy with Notifications

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy
        id: deploy
        uses: agentuity/deploy-action@v1
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
      
      - name: Slack Notification
        if: success()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "✅ Agent deployed: ${{ steps.deploy.outputs.url }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
      
      - name: Slack Failure
        if: failure()
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "❌ Deployment failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}
```

## Security Best Practices

### Using OIDC Instead of API Keys

```yaml
name: Deploy with OIDC

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Configure Agentuity credentials
        uses: agentuity/configure-credentials@v1
        with:
          role-to-assume: arn:agentuity:iam::deploy-role
          role-session-name: github-actions-deploy
      
      - name: Deploy
        run: agentuity deploy
```

### Secrets Scanning

```yaml
name: Security Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Trivy security scanner
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'fs'
          scan-ref: '.'
      
      - name: Check for secrets
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
```

## Environment Configuration

### GitHub Environments

Configure in repository settings for manual approvals:

1. Go to Settings → Environments
2. Create `production` environment
3. Enable "Required reviewers"
4. Add reviewer list

```yaml
jobs:
  deploy:
    environment: production  # Requires approval
```

### Environment Variables

```yaml
env:
  AGENTUITY_PROJECT: my-agent
  NODE_ENV: production

jobs:
  deploy:
    steps:
      - name: Deploy
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: agentuity deploy
```

## Monitoring & Rollback

### Post-Deployment Verification

```yaml
- name: Verify Deployment
  run: |
    # Wait for deployment to stabilize
    sleep 30
    
    # Health check
    curl -f ${{ steps.deploy.outputs.url }}/health || exit 1
    
    # Check metrics
    ERROR_RATE=$(agentuity metrics error-rate --last 5m --json | jq -r '.rate')
    if (( $(echo "$ERROR_RATE > 0.05" | bc -l) )); then
      echo "High error rate detected"
      exit 1
    fi

- name: Rollback on Failure
  if: failure()
  run: agentuity rollback
```

### Automated Rollback

```yaml
name: Auto Rollback

on:
  workflow_dispatch:
    inputs:
      deployment-id:
        required: true

jobs:
  rollback:
    runs-on: ubuntu-latest
    steps:
      - name: Rollback Deployment
        uses: agentuity/rollback-action@v1
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          deployment-id: ${{ inputs.deployment-id }}
```

## Troubleshooting

### Deployment Fails

```yaml
- name: Debug on Failure
  if: failure()
  run: |
    echo "::group::Agentuity Logs"
    agentuity logs --tail 100
    echo "::endgroup::"
    
    echo "::group::Deployment Status"
    agentuity deploy status
    echo "::endgroup::"
```

### Timeout Issues

```yaml
- name: Deploy with Extended Timeout
  uses: agentuity/deploy-action@v1
  with:
    api-key: ${{ secrets.AGENTUITY_API_KEY }}
    timeout: 1200  # 20 minutes
    wait-for-completion: true
```

## Best Practices

1. **Use Environments**: Separate staging and production
2. **Enable Branch Protection**: Require PR reviews before deploying
3. **Test Before Deploy**: Always run tests in CI
4. **Use OIDC**: More secure than long-lived API keys
5. **Monitor Deployments**: Add health checks and metrics
6. **Automate Rollbacks**: Implement automatic rollback on errors
7. **Document Workflows**: Add comments and README

## Complete Example

```yaml
name: Complete CI/CD Pipeline

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize]

env:
  NODE_VERSION: '18'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build
      
      - name: Upload build artifacts
        uses: actions/upload-artifact@v3
        with:
          name: dist
          path: dist/

  deploy-preview:
    if: github.event_name == 'pull_request'
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/download-artifact@v3
        with:
          name: dist
          path: dist/
      
      - uses: agentuity/deploy-action@v1
        id: deploy
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          preview: true
      
      - uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `🚀 Preview: ${{ steps.deploy.outputs.url }}\n📊 [Logs](https://console.agentuity.com/deployments/${{ steps.deploy.outputs.deployment-id }})`
            })

  deploy-production:
    if: github.ref == 'refs/heads/main'
    needs: test
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/download-artifact@v3
        with:
          name: dist
          path: dist/
      
      - uses: agentuity/deploy-action@v1
        id: deploy
        with:
          api-key: ${{ secrets.AGENTUITY_API_KEY }}
          environment: production
          wait-for-completion: true
      
      - name: Verify Deployment
        run: |
          curl -f ${{ steps.deploy.outputs.url }}/health
          agentuity metrics error-rate --deployment ${{ steps.deploy.outputs.deployment-id }}
      
      - name: Notify Team
        if: success()
        run: |
          echo "✅ Deployed to production: ${{ steps.deploy.outputs.url }}"
```

## References

- [GitHub Actions Documentation](https://docs.github.com/actions)
- [Agentuity Deploy Action](https://github.com/agentuity/deploy-action)
- [OIDC with Agentuity](https://agentuity.dev/deployment/oidc)
- [Deployment Best Practices](https://agentuity.dev/deployment/best-practices)