Caprover Deploy

CapRover Deploy

Overview

This skill enables deploying apps to CapRover just by asking. It supports two primary strategies:

1. GitHub workflow_dispatch — triggers an existing CI/CD workflow (build + deploy)
2. CapRover App Token / Webhook — directly triggers a CapRover build/deploy

Configuration

All credentials live in a config.json file in the skill directory (gitignored).

config.json Format

{
  "caprover": {
    "url": "https://captain.example.com",
    "password": "YOUR_MASTER_PASSWORD"
  },
  "github": {
    "token": "ghp_YOUR_GITHUB_PAT",
    "owner": "your-github-username"
  },
  "apps": {
    "myapp": {
      "caprover_app_name": "myapp",
      "github_repo": "your-username/myapp",
      "github_workflow": "deploy.yml",
      "default_branch": "main",
      "caprover_app_token": "OPTIONAL_PER_APP_TOKEN",
      "caprover_webhook_url": "OPTIONAL_WEBHOOK_URL_FROM_CAPROVER_DASHBOARD"
    }
  }
}

What each credential does

Deploy Decision Flow

When user says "deploy X" (optionally "to branch Y"):

1. Read config.json
2. Look up app by name (fuzzy match)
3. Choose strategy:
   a. If github.token + github_repo + github_workflow → use GitHub workflow_dispatch
   b. Else if caprover_webhook_url → POST to webhook URL
   c. Else if caprover_app_token → use caprover CLI
   d. Ask user for missing config
4. Execute and report result

Strategy 1: GitHub Workflow Dispatch (Recommended)

curl -X POST \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/deploy.yml/dispatches \
  -d '{"ref":"main"}'

Check run status:

curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/actions/runs?per_page=1

Strategy 2: CapRover Webhook Trigger

curl -X POST "WEBHOOK_URL_FROM_CONFIG"

The webhook URL is found in: CapRover Dashboard → Apps → [App Name] → Deployment Tab → Webhook URL

Strategy 3: CapRover App Token (CLI Deploy)

caprover deploy \
  --caproverUrl https://captain.example.com \
  --appToken "APP_TOKEN" \
  --appName "myapp" \
  --imageName "ghcr.io/owner/myapp:latest"

Conversational Triggers

Setting Up a New Project for CapRover Deploy

Step 1: Choose the right workflow template

Step 2: Create workflow file in the project

mkdir -p PROJECT/.github/workflows
cp assets/templates/deploy-image.yml PROJECT/.github/workflows/deploy.yml
# Replace __APP_NAME__ with actual CapRover app name
sed -i 's/__APP_NAME__/myapp/g' PROJECT/.github/workflows/deploy.yml

Step 3: Add captain-definition (if needed for tar-based deploy)

cp assets/templates/captain-definition.json PROJECT/captain-definition

Step 4: Configure GitHub Secrets

Add these in GitHub → Repo → Settings → Secrets and variables → Actions:

For multi-env:

• CAPROVER_APP_PROD, CAPROVER_APP_TOKEN_PROD
• CAPROVER_APP_STAGING, CAPROVER_APP_TOKEN_STAGING

Step 5: Commit and push

cd PROJECT
git add .github/workflows/deploy.yml captain-definition
git commit -m "ci: add CapRover deploy workflow"
git push

Notes

• The caprover CLI may not be installed: npm install -g caprover
• For private repos, the GitHub token needs repo + workflow scopes
• Always confirm the deploy was triggered (check API response or GitHub Actions UI)
• See assets/templates/ for workflow templates