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