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

| Credential | Where to get it | Purpose | |---|---|---| | caprover.url | Your CapRover server | Base URL for API calls | | caprover.password | CapRover dashboard | Master password for API auth | | github.token | GitHub → Settings → Developer Settings → PAT | For triggering workflow_dispatch | | apps.*.caprover_app_token | App → Deployment tab → Enable App Token | Per-app deploy without master password | | apps.*.caprover_webhook_url | App → Deployment tab → Webhook URL | Trigger rebuild from configured git repo | | apps.*.github_workflow | .github/workflows/ filename | Which workflow to trigger |

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

| User says | Action | |---|---| | "deploy myapp" | Deploy default branch via best available strategy | | "deploy myapp to main" | Deploy main branch | | "deploy branch feat/ui to myapp" | GitHub dispatch with ref=feat/ui | | "trigger a deploy of myapp" | Same as deploy | | "check deploy status of myapp" | Fetch latest GitHub Actions run status | | "what apps can I deploy?" | List apps from config.json |

Setting Up a New Project for CapRover Deploy

Step 1: Choose the right workflow template

| Scenario | Template | |---|---| | Has Dockerfile, push image to ghcr.io | assets/templates/deploy-image.yml | | Node build step + tar deploy | assets/templates/deploy-tar.yml | | Staging + production environments | assets/templates/deploy-multi-env.yml |

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:

| Secret name | Value | |---|---| | CAPROVER_HOST | CapRover URL, e.g. https://captain.example.com | | CAPROVER_APP_TOKEN | From CapRover App → Deployment → Enable App Token |

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