Deploy to CapRover

Deploy checked-out source, a Docker image, or a prepared tar file to CapRover using an app token.

Quick start

- uses: actions/checkout@v6

- uses: caprover/deploy-from-github@v2
  with:
    server: https://captain.example.com
    app: my-api
    token: ${{ secrets.CAPROVER_APP_TOKEN }}

This packages the files committed in the checked-out HEAD and submits the deployment to CapRover. Generate an app token from the app's Deployment tab in CapRover.

Important: This is the simplest deployment setup, but CapRover builds the Docker image on your server. Builds can consume significant CPU, memory, disk I/O, and storage during deployment. For production workloads, we strongly recommend building the image in GitHub Actions and deploying the pre-built image instead, as shown below.

App tokens and deployment data are sent to the configured server. Use HTTPS unless the server is reached through a trusted private network.

Deploy a Docker image

For production deployments, this is the recommended approach. Build and push the image with the standard Docker actions, then ask CapRover to deploy it. The image build runs on GitHub Actions instead of consuming resources on your CapRover server.

- uses: actions/checkout@v6

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

- uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: ghcr.io/YOUR_USERNAME/YOUR_APP:${{ github.sha }}

# If this image is private, configure the registry credentials in CapRover first.
# See "Private registries" below.
- uses: caprover/deploy-from-github@v2
  with:
    server: https://captain.example.com
    app: my-api
    token: ${{ secrets.CAPROVER_APP_TOKEN }}
    image: ghcr.io/YOUR_USERNAME/YOUR_APP:${{ github.sha }}

Monorepo

working-directory packages that directory's committed contents at the root of the deployment tar:

- uses: actions/checkout@v6

- uses: caprover/deploy-from-github@v2
  with:
    server: https://captain.example.com
    app: my-api
    token: ${{ secrets.CAPROVER_APP_TOKEN }}
    working-directory: apps/api

Deploy a prepared tar

Use tar-file when an earlier step produces the exact deployment archive:

- uses: actions/checkout@v6

- uses: caprover/deploy-from-github@v2
  with:
    server: https://captain.example.com
    app: my-api
    token: ${{ secrets.CAPROVER_APP_TOKEN }}
    tar-file: ./dist/deploy.tar

Inputs

Input	Required	Default	Description
server	Yes		CapRover URL, such as https://captain.example.com
app	Yes		CapRover app name
token	Yes		App token from the app's Deployment tab
image	No		Existing Docker image for CapRover to deploy
tar-file	No		Prepared tar file, resolved from the GitHub workspace
working-directory	No	.	Source directory whose committed contents should be packed

image and tar-file are mutually exclusive. working-directory applies to source deployments.

Private registries

CapRover pulls an image from the registry during deployment. Configure the registry credentials in CapRover before deploying a private image. Logging the GitHub runner into the registry only grants access to the runner.

Migration from v1

• Replace caprover/deploy-from-github@v1 with caprover/deploy-from-github@v2 when you are ready to migrate.
• The branch input has been removed. Check out the desired commit before running the action; v2 always packages checked-out HEAD.
• The default mode now packages checked-out HEAD automatically.
• To deploy an existing ./deploy.tar, provide tar-file: ./deploy.tar explicitly.
• Generated and uncommitted files are excluded from the default source deployment. Package them into a tar file and use tar-file when they are required.

App-token deployments run in detached mode. A successful action means CapRover accepted the deployment; final build and application health are handled by CapRover.