Integrations API

Connect and manage third-party integrations such as GitHub, GitLab, and Bitbucket.

Cloudflare

Cloudflare connections are scoped to a project and manage only zones available to that project's customer-owned Cloudflare credential. They are separate from Cosmoner-managed DNS and credentials are never returned by the API. See Connect Your Cloudflare Account for token permissions, record formats, and automatic app-domain DNS behavior.

Connection Status

GET /v1/projects/:projectId/integrations/cloudflare

Reports whether the project is connected, the connection type, the safe account name when available, and the autoDnsEnabled setting. oauthEnabled indicates whether this deployment offers the optional OAuth connection flow.

Auth: Required (project member)

Connect with an API Token

POST /v1/projects/:projectId/integrations/cloudflare/connect/token

Validates and securely stores a Cloudflare API token for this project. Use a scoped token with Zone → DNS → Edit and Zone → Zone → Read for the specific zones you want to manage. The token is never included in responses.

Auth: Required (project member, non-viewer)

{
  "apiToken": "your-scoped-cloudflare-api-token"
}

Connect with Cloudflare OAuth

GET /v1/projects/:projectId/integrations/cloudflare/connect/oauth

Starts the optional Cloudflare OAuth flow and redirects to Cloudflare. This is available only when OAuth is configured for the deployment; otherwise use an API token. The callback validates a short-lived, single-use state and redirects back to the supplied safe relative frontend path with ?cloudflare=connected.

Auth: Required (project member, non-viewer)

Query Parameters:

Parameter	Description
`redirect`	Relative frontend path to return to after authorization (optional).

Update Cloudflare Settings

PATCH /v1/projects/:projectId/integrations/cloudflare/settings

Changes the project's explicit automatic DNS preference. It is disabled by default. When enabled, an eligible app custom-domain change can create the required record in a matching customer zone without a confirmation prompt.

Auth: Required (project member, non-viewer)

{
  "autoDnsEnabled": true
}

Disconnect Cloudflare

DELETE /v1/projects/:projectId/integrations/cloudflare/disconnect

Removes the stored project credential. Existing Cloudflare DNS records are not deleted.

Auth: Required (project member, non-viewer)

List Zones

GET /v1/projects/:projectId/integrations/cloudflare/zones

Returns the zones available through the project's connected Cloudflare credential.

Auth: Required (project member; Cloudflare connection required)

List DNS Records

GET /v1/projects/:projectId/integrations/cloudflare/zones/:zoneId/records

Returns supported records in a zone available through the project connection.

Auth: Required (project member; Cloudflare connection required)

Create a DNS Record

POST /v1/projects/:projectId/integrations/cloudflare/zones/:zoneId/records

Creates a supported DNS record in the selected customer zone.

Auth: Required (project member, non-viewer)

{
  "type": "CNAME",
  "name": "app.example.com",
  "content": "target.example.net",
  "ttl": 1,
  "proxied": false
}

Supported types are A, AAAA, CNAME, MX, TXT, NS, SRV, and CAA. Use 1 for Cloudflare's automatic TTL. proxied applies only to A, AAAA, and CNAME; proxied records must use automatic TTL. MX records require a numeric priority. SRV and CAA use their conventional space-separated content formats described in the Cloudflare guide.

Update or Delete a DNS Record

PATCH /v1/projects/:projectId/integrations/cloudflare/zones/:zoneId/records/:recordId
DELETE /v1/projects/:projectId/integrations/cloudflare/zones/:zoneId/records/:recordId

The PATCH endpoint accepts the same record body as creation and replaces the record's supported fields. DELETE permanently removes the record from Cloudflare.

Auth: Required (project member, non-viewer)

Docker Hub

Docker Hub connections store one project-owned personal access token using envelope encryption. The token is never returned by the API and is decrypted only when a private container-image deployment spec is submitted.

Connect and inspect status

POST /v1/projects/:projectId/integrations/docker-hub/connect
GET /v1/projects/:projectId/integrations/docker-hub/status

The connect endpoint accepts username and accessToken, verifies them with Docker Hub, and replaces any credential previously connected to the project. Use a read-only PAT for deployment access.

Auth: Required (project member; non-viewer to connect)

Browse images and tags

GET /v1/projects/:projectId/integrations/docker-hub/repositories
GET /v1/projects/:projectId/integrations/docker-hub/tags?namespace=:namespace&repository=:repository

These endpoints power the container deployment image picker using the connected PAT. The deployment stores an integration reference rather than a copy of the credential.

Auth: Required (project member)

Disconnect

DELETE /v1/projects/:projectId/integrations/docker-hub/disconnect

Deletes the encrypted project credential. Existing DigitalOcean apps retain the credential DigitalOcean encrypted in their deployed spec, but new private image deployments can no longer use the integration.

Auth: Required (project member, non-viewer)

GitHub

GitHub connections are scoped to a project: each project links its own GitHub App installations, and connecting GitHub in one project never makes it available in another. A project can link several GitHub accounts or organizations, and different projects can link different ones. Installations with Packages: Read permission can also authenticate private GHCR images from the connected account in the container-image deployment wizard.

Connect GitHub

GET /v1/projects/:projectId/integrations/github/connect

Initiates the GitHub connection for the project. Redirects the user to the Cosmoner GitHub App installation page, where they choose the account and repositories to grant (read-only access to repository contents). The resulting installation is linked to this project only. The state parameter expires after 10 minutes.

Auth: Required (project member, non-viewer)

Query Parameters:

Parameter	Description
`redirect`	Relative frontend path to return to after the callback completes (optional; must be same-origin). Defaults to `/en/controlpanel`.

Response: 302 redirect to GitHub

Connection Status

GET /v1/projects/:projectId/integrations/github/status

Reports whether the project has a working GitHub connection, along with the connected account's profile. For GitHub App connections, accounts lists every GitHub account or organization linked to the project.

Auth: Required (project member)

Browse GHCR images and tags

GET /v1/projects/:projectId/integrations/github/packages
GET /v1/projects/:projectId/integrations/github/package-tags?owner=:owner&package=:package

Lists container images and tags visible to the project's linked GitHub App installations. Deployments mint a short-lived installation token when the image is submitted to the hosting provider; users do not need to enter a separate PAT.

Discovery covers images published under the name of a repository the app can access — ghcr.io/<owner>/<repository>. Images published under any other name are not listed, but their tags can still be read by passing owner and package explicitly.

Auth: Required (project member)

List Linkable Installations

GET /v1/projects/:projectId/integrations/github/linkable-installations

GitHub runs the App install flow only once per GitHub account — when the app is already installed there (for example via another project), the flow offers "Configure" instead of completing a new install. This endpoint lists installations the current user connected in other projects that can be linked to this project directly, without going through GitHub again.

Auth: Required (project member)

Response:

{
  "success": true,
  "data": [
    { "installationId": "12345678", "accountLogin": "acme-inc" }
  ]
}

Link an Existing Installation

POST /v1/projects/:projectId/integrations/github/link

Links a GitHub App installation the current user already connected in another project to this project. The installation is verified against GitHub before linking; an installation that has been uninstalled on GitHub is rejected and cleaned up.

Auth: Required (project member, non-viewer)

Body:

Field	Description
`installationId`	The installation to link (must appear in the linkable-installations list).

Installation Callback

GET /v1/integrations/github/setup

GitHub App post-install redirect. Verifies the installation and links it to the project the connect flow was started from, then redirects to the frontend with ?github=connected.

Auth: None (public, state-validated)

OAuth Callback (legacy)

GET /v1/integrations/github/callback

Callback for the legacy OAuth flow. Exchanges the authorization code for an access token, stores the connection, and redirects to the frontend with ?github=connected. Superseded by the GitHub App installation flow.

Auth: None (public, state-validated)

List Repositories

GET /v1/projects/:projectId/integrations/github/repos

Returns the repositories available to the project's connection, sorted by last updated. For GitHub App connections this is the set of repositories granted across every account or organization linked to the project (each is its own installation); use GitHub's "Configure" page for the Cosmoner app to grant more.

Auth: Required (project member; GitHub connection required)

Browse Repository Contents

GET /v1/projects/:projectId/integrations/github/repos/:owner/:repo/contents/*path

Lists directory contents from a GitHub repository. Entries are sorted with directories first, then alphabetically by name.

Auth: Required (project member; GitHub connection required)

Query Parameters:

Parameter	Description
`ref`	Branch or tag name (optional)

Look Up Deployment Template

GET /v1/projects/:projectId/integrations/github/repos/:owner/:repo/app-template

Looks for a deployment template (.datablock/app.yaml or .datablock/app.yml) in the repository and returns its parsed services, normalized for the deploy wizard. See the App Deployment Templates guide for the file format.

Auth: Required (project member; GitHub connection required)

Query Parameters:

Parameter	Description
`ref`	Branch or tag name (optional)

Response (template found):

{
  "success": true,
  "data": {
    "found": true,
    "valid": true,
    "path": ".datablock/app.yaml",
    "name": "my-platform",
    "services": [
      {
        "name": "api",
        "appType": "service",
        "sourceDir": "apps/api",
        "buildStrategy": "docker",
        "buildCommand": "bun run build",
        "runCommand": "bun start",
        "outputDir": null,
        "publicPort": 8080,
        "internalPort": 3000,
        "instanceSize": "apps-s-1vcpu-1gb",
        "instances": 2,
        "region": "ams",
        "autoDeploy": true,
        "envVars": [
          { "key": "NODE_ENV", "value": "production" },
          { "key": "DATABASE_URL", "value": "", "secret": true }
        ]
      }
    ]
  }
}

When no template exists, data is { "found": false }. When a template exists but fails validation, data is { "found": true, "valid": false, "path": "...", "error": "..." }.

List Branches

GET /v1/projects/:projectId/integrations/github/repos/:owner/:repo/branches

Returns branches in the repository (100 per page).

Auth: Required (project member; GitHub connection required)

Push Webhook (auto-deploy)

POST /v1/integrations/github/webhook

Receiver for GitHub events. A push to an app's deployed branch triggers a new deployment when auto-deploy is enabled; uninstalling the Cosmoner GitHub App cleanly detaches the connection from every project that linked it. Not intended to be called directly.

Auth: None (HMAC signature — X-Hub-Signature-256 — verified against the webhook secret)

Response: 202 with { "queued": <number of deployments triggered> }; other events are acknowledged with 200.

Disconnect GitHub

DELETE /v1/projects/:projectId/integrations/github/disconnect

Unlinks GitHub from the project. Installations no longer referenced by any other project are also uninstalled from the GitHub account. Other projects keep their own connections.

Auth: Required (project member, non-viewer)

Bitbucket

Bitbucket connections are scoped to one project. OAuth access and refresh tokens are encrypted at rest, and Bitbucket repositories are copied into the platform's private GitHub deployment organization before DigitalOcean builds them.

Connect and inspect status

GET /v1/projects/:projectId/integrations/bitbucket/connect
GET /v1/projects/:projectId/integrations/bitbucket/status

The connect endpoint redirects to Bitbucket OAuth. Bitbucket returns to GET /v1/integrations/bitbucket/callback, which exchanges the one-time code and returns the browser to the requested control-panel path.

Auth: Required (project member; non-viewer to connect)

Browse repositories

GET /v1/projects/:projectId/integrations/bitbucket/repos
GET /v1/projects/:projectId/integrations/bitbucket/repos/:workspace/:repo/contents/*path
GET /v1/projects/:projectId/integrations/bitbucket/repos/:workspace/:repo/app-template
GET /v1/projects/:projectId/integrations/bitbucket/repos/:workspace/:repo/branches

These endpoints provide the repository picker, directory browser, deployment template lookup, and branch picker used by the app deployment wizard.

Auth: Required (project member; Bitbucket connection required)

Push webhook and disconnect

POST /v1/integrations/bitbucket/webhook
DELETE /v1/projects/:projectId/integrations/bitbucket/disconnect

The webhook accepts signed repo:push events and refreshes matching GitHub deployment mirrors when auto-deploy is enabled. The disconnect endpoint removes project webhooks before deleting the encrypted OAuth grant.

Webhook auth: HMAC signature in X-Hub-Signature, using a repository-scoped secret

Disconnect auth: Required (project member, non-viewer)

GitLab

GitLab connections are scoped to one project. OAuth access and rotating refresh tokens are encrypted at rest, and GitLab repositories are copied into the platform's private GitHub deployment organization before DigitalOcean builds them.

Connect and inspect status

GET /v1/projects/:projectId/integrations/gitlab/connect
GET /v1/projects/:projectId/integrations/gitlab/status

The connect endpoint redirects to GitLab OAuth and requests api plus read_repository access. GitLab returns to GET /v1/integrations/gitlab/callback, which exchanges the one-time code and returns the browser to the requested control-panel path.

Auth: Required (project member; non-viewer to connect)

Browse repositories

GET /v1/projects/:projectId/integrations/gitlab/repos
GET /v1/projects/:projectId/integrations/gitlab/repos/:project/contents/*path
GET /v1/projects/:projectId/integrations/gitlab/repos/:project/app-template
GET /v1/projects/:projectId/integrations/gitlab/repos/:project/branches

:project is the URL-encoded path_with_namespace, including any nested groups. These endpoints provide the repository picker, directory browser, deployment template lookup, and branch picker used by the app deployment wizard.

Auth: Required (project member; GitLab connection required)

Push webhook and disconnect

POST /v1/integrations/gitlab/webhook
DELETE /v1/projects/:projectId/integrations/gitlab/disconnect

The webhook accepts GitLab push events and refreshes matching GitHub deployment mirrors when auto-deploy is enabled. The disconnect endpoint removes project webhooks before deleting the encrypted OAuth grant.

Webhook auth: Repository-scoped token in X-Gitlab-Token

Disconnect auth: Required (project member, non-viewer)

On this page