Carpathian Logo
Deployment
Automated Deployments with GitHub Actions

Automate your code deployments with Carpathian Cloud. Easily push code to your development and production spark servers.

9 min read
51 views
Automated Deployments with GitHub Actions

Carpathian's Cloud Servers support automated deployments directly from your GitHub repository using GitHub Actions. This allows you to automatically deploy code changes to your server whenever you push to specific branches, creating a seamless CI/CD workflow.

What You Need

  • A Carpathian Spark Server (running)
  • A GitHub repository with your code
  • 5 minutes to set up

Step 1: Configure Deployment on Your Server

Before you can use automated deployments, you need to configure deployment settings for your server.

  1. Navigate to your Spark Servers page in the Carpathian dashboard
  2. Locate the server you want to deploy to
  3. Click the Actions button (⚡) on the server card
  4. Select Configure Deployment from the dropdown menu
  5. Fill in the deployment settings:
    • Repository URL: Your GitHub repository (e.g., https://github.com/username/repo)
    • Branch: The branch to deploy from (e.g., main)
    • Deploy Directory: Where to deploy files on your server (e.g., /var/www/app)
    • Build Command (Optional): See framework-specific examples below
    • Restart Command (Optional): See framework-specific examples below
  6. Toggle Enable Deployment to ON
  7. Click Save Configuration

Your server is now ready for automated deployments!

Try It Out: Want to test with a sample app? Check out our example Flask deployment repository for a working example.

Need Help? Can't find your framework? Request native support and we'll add it to the documentation.

Step 2: Generate an API Key

API keys allow GitHub Actions to securely communicate with your Carpathian server without exposing your account credentials.

Creating Your API Key

  1. On the Spark Servers page, click the Actions button (⚡) on your server card
  2. Select Manage API Keys from the dropdown menu
  3. Click Generate New API Key
  4. Key Name (Optional): Give your key a descriptive name like "GitHub Actions Deploy"
  5. Permission Scope: Select Deployment (recommended for GitHub Actions)
  6. Click Generate API Key

Alternative: You can also manage all API keys from API Keys in the dashboard nav.

Save Your API Key

IMPORTANT: The full API key will only be displayed once. You cannot retrieve it later.

  1. Copy the displayed API key (format: cpk_...)
  2. Store it securely - you'll need it for GitHub Actions
  3. Click the Copy button to copy it to your clipboard

Step 3: Add API Key to GitHub Secrets

GitHub Secrets allow you to securely store sensitive information like API keys.

  1. Go to your GitHub repository
  2. Click Settings → Secrets and variables → Actions
  3. Click New repository secret
  4. Set Name to: CARPATHIAN_API_KEY
  5. Set Value to: Your API key (starting with cpk_...)
  6. Click Add secret

Step 4: Create GitHub Actions Workflow

Create a new file in your repository at .github/workflows/deploy.yml:

name: Deploy to Carpathian

on:
  push:
    branches:
      - main  # Deploy when pushing to main branch

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Trigger Carpathian Deployment
        env:
          CARPATHIAN_API_KEY: ${{ secrets.CARPATHIAN_API_KEY }}
        run: |
          curl -X POST https://carpathian.ai/api/v1/deployment/trigger \
            -H "Authorization: Bearer $CARPATHIAN_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{
              "repository": "${{ github.repository }}",
              "commit": "${{ github.sha }}",
              "branch": "${{ github.ref_name }}",
              "commit_message": "${{ github.event.head_commit.message }}",
              "author_name": "${{ github.event.head_commit.author.name }}",
              "author_email": "${{ github.event.head_commit.author.email }}",
              "webhook_url": "${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}"
            }'

      - name: Deployment Status
        run: echo "Deployment triggered successfully! Check your Carpathian dashboard for status."

Customizing the Workflow

Deploy on specific branches:

on:
  push:
    branches:
      - main
      - production
      - staging

Deploy on pull request merge:

on:
  pull_request:
    types: [closed]
    branches:
      - main

Manual deployment trigger:

on:
  workflow_dispatch:  # Allows manual trigger from GitHub UI

Step 5: Test Your Deployment

  1. Commit the workflow file to your repository:

    git add .github/workflows/deploy.yml
git commit -m "Add Carpathian deployment workflow"
git push origin main

  2. Go to your GitHub repository → Actions tab

  3. You should see your workflow running

  4. Once completed, check your Carpathian dashboard to verify the deployment

Managing API Keys

Viewing API Keys

  • Server Menu: Click the Actions (⚡) button on any server card → Manage API Keys
  • Settings Page: API Keys in the dashboard nav (view all keys across all servers)

Key Information

Each API key displays:

  • Key Name: Your custom identifier
  • Key Prefix: First characters of the key (e.g., cpk_Ab3d***)
  • Scope: Permission level (Deployment, Read Only, Server Control, Full Access)
  • Status: Active, Locked, Revoked, or Expired
  • Usage Count: Number of times the key has been used
  • Last Used: When the key was last accessed
  • Last IP: IP address of the last request

Key Actions

Unlock Key: Restore access to a locked key

  • Keys are automatically locked after 3 failed IP allowlist checks within 5 minutes
  • Use the Unlock button to restore access after investigating the security event

Revoke Key: Disable a key without deleting it

  • The key remains visible but cannot be used
  • Useful for temporarily disabling access

Delete Key: Permanently remove a key

  • Cannot be undone
  • Use when you no longer need the key

IP Allowlist (Optional Security)

Restrict API key access to specific IP addresses or ranges:

  1. Click Details on any API key
  2. In the IP Allowlist section, add IP addresses or CIDR ranges
  3. Click Add IP to save

Examples:

  • Single IP: 192.168.1.100
  • CIDR range: 192.168.1.0/24
  • GitHub Actions IPs: 185.199.108.0/22, 140.82.112.0/20, 143.55.64.0/20

Note: If IP allowlist is configured and the request comes from a different IP, the key will be blocked. After 3 failed attempts in 5 minutes, the key is automatically locked for security.

Security Best Practices

1. Use Descriptive Key Names

Always name your keys to remember their purpose:

  • Good: "GitHub Actions - Main Repo", "Production Deploy"
  • Bad: "Key 1", "Test"

2. Use Minimal Permissions

Only grant the permissions your workflow needs:

  • For deployments: Use Deployment scope
  • For monitoring: Use Read Only scope
  • Avoid Full Access unless absolutely necessary

3. Monitor Key Usage

Regularly check:

  • Last Used timestamp - Ensure keys are being used as expected
  • Last IP address - Verify requests are coming from expected sources
  • Usage Count - Detect unusual activity patterns
  • Security Events - Review any IP blocks or lock events

4. Automatic Security Protection

Carpathian automatically protects your servers from unauthorized access:

  • Keys are automatically locked after 3 failed IP allowlist checks within 5 minutes
  • When locked, the key cannot be used until you manually unlock it
  • Check the Security Events section to see what triggered the lock
  • Use the Unlock button to restore access after investigating

5. Revoke Unused Keys

  • If a key hasn't been used in 90+ days, consider revoking or deleting it
  • Reduces potential attack surface

6. Never Commit Keys to Git

  • Always use GitHub Secrets, never hardcode API keys
  • If a key is accidentally committed, revoke it immediately

Troubleshooting

"Deployment Not Configured" Error

This means you haven't configured deployment settings on your server yet.

Solution:

  1. Go to your Spark Servers page
  2. Click Actions (⚡) on the server card
  3. Select Configure Deployment
  4. Fill in repository URL, branch, and deploy directory
  5. Toggle Enable Deployment to ON
  6. Save and try your deployment again

Deployment Not Triggering

Check API Key Status:

  1. Go to API Keys in the dashboard nav
  2. Verify the key status is Active (not Locked, Revoked, or Expired)
  3. Check if the key has the Deployment permission scope

Verify GitHub Secret:

  1. Go to GitHub repository → Settings → Secrets
  2. Ensure CARPATHIAN_API_KEY exists and contains the full key (starting with cpk_)

Check Workflow Syntax:

  1. Go to GitHub repository → Actions
  2. Click on the failed workflow run
  3. Review error messages in the workflow logs

"Invalid API Key" Error

  • The key may have been revoked, deleted, or locked
  • The key might not be copied correctly (missing characters)
  • Check the key status in your API Keys dashboard
  • Generate a new key and update GitHub Secrets if needed

"Insufficient Permissions" Error

  • Your API key doesn't have the Deployment scope
  • Create a new key with Deployment permissions

API Key Locked

  • Your key was automatically locked after 3 failed IP allowlist checks
  • This is a security feature to protect your server
  • Click Manage on the key to view Security Events
  • Review the blocked IP addresses and events
  • If the activity is legitimate, update your IP allowlist or remove IP restrictions
  • Click Unlock to restore access

Deployment Triggered but No Changes on Server

  • Check the Carpathian dashboard for deployment status and logs
  • Verify your server is running and accessible
  • Review deployment logs for errors in the build or restart commands
  • Ensure your deployment configuration paths are correct

Advanced Usage

Multiple Environments

Use different API keys for different environments:

jobs:
  deploy-staging:
    if: github.ref == 'refs/heads/staging'
    steps:
      - name: Deploy to Staging
        env:
          CARPATHIAN_API_KEY: ${{ secrets.CARPATHIAN_STAGING_KEY }}
        run: |
          curl -X POST https://carpathian.ai/api/v1/deployment/trigger ...

  deploy-production:
    if: github.ref == 'refs/heads/main'
    steps:
      - name: Deploy to Production
        env:
          CARPATHIAN_API_KEY: ${{ secrets.CARPATHIAN_PRODUCTION_KEY }}
        run: |
          curl -X POST https://carpathian.ai/api/v1/deployment/trigger ...

Deployment Notifications

Add Slack or Discord notifications:

- name: Notify on Success
  if: success()
  run: |
    curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
      -d '{"text":"Deployment to Carpathian completed successfully!"}'

- name: Notify on Failure
  if: failure()
  run: |
    curl -X POST ${{ secrets.SLACK_WEBHOOK }} \
      -d '{"text":"Deployment to Carpathian failed! Check logs."}'

Viewing Deployment Status via API

# Get deployment status
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://carpathian.ai/api/v1/deployment/status/DEPLOYMENT_ID

# Get deployment logs
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://carpathian.ai/api/v1/deployment/logs/DEPLOYMENT_ID

Start automating your deployments today and focus on building great software!