Skip to content
DockBoard
Browse the documentation
API

Deploying from CI

A complete GitHub Actions workflow that deploys and waits for the result, with the scopes it needs.

The most common reason to hold an API key: a push to main should redeploy the application, and the pipeline should fail if the deployment fails.

The key this needs

  • Exactly two scopes: project:apps:deploy and project:deployments:view.
  • projectIds set to the one project it deploys to.
  • If your runners have stable egress addresses, allowedIps too. A key that names its egress is worth much less when stolen.

Store the secret in your CI provider’s secret store — never in the repository. See minting a key.

A GitHub Actions step, end to end

YAML
# .github/workflows/deploy.yml
- name: Deploy to DockBoard
  env:
    DOCKBOARD_URL: https://panel.example.com
    DOCKBOARD_API_KEY: ${{ secrets.DOCKBOARD_API_KEY }}
  run: |
    dep=$(curl -fsS -X POST "$DOCKBOARD_URL/api/deployments" \
      -H "Authorization: Bearer $DOCKBOARD_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"applicationId":"'"$APP_ID"'"}' | jq -r .id)

    # Poll until it settles.
    while :; do
      status=$(curl -fsS "$DOCKBOARD_URL/api/deployments/$dep" \
        -H "Authorization: Bearer $DOCKBOARD_API_KEY" | jq -r .status)
      case "$status" in
        RUNNING) echo "deployed"; break ;;
        FAILED|CANCELLED|ROLLED_BACK) echo "deploy $status"; exit 1 ;;
        *) sleep 5 ;;
      esac
    done

Nothing here is GitHub-specific beyond the secret syntax — the same twenty lines work in GitLab CI, Woodpecker or a bare shell script.

Reading the status

StatusMeaning
PENDING BUILDING DEPLOYINGIn flight — keep polling.
RUNNINGSuccess. This is the terminal happy state — there is no separate SUCCEEDED.
FAILED CANCELLED ROLLED_BACKTerminal failure. Fail the pipeline.
Match every terminal status, not just the happy one. A loop that only breaks on RUNNING spins until the job times out when a build fails — the worst possible signal, because a timeout looks like an infrastructure problem rather than a broken commit.

What actually gets deployed

The call above deploys the application’s configured branch at HEAD, which is what you want from a push-triggered workflow.

commitSha is for rollback, not for pinning a fresh build. It is resolved against this application’s own deployment history, so a SHA it has never deployed is a 400 rather than a silent HEAD deploy.
If your goal is a running copy per pull request rather than a deploy of main, you want preview environments instead — DockBoard creates and destroys them itself, with no CI wiring at all.
Deploying from CI — DockBoard