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, scope: integrations:read)

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, scope: integrations:write)

{
  "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. Once the user authorizes, the browser is returned to the requested control-panel path with ?cloudflare=connected.

Auth: Required (project member, non-viewer, scope: integrations:write)

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, scope: integrations:write)

{
  "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, scope: integrations:write)

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, scope: integrations:read)

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, scope: integrations:read)

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, scope: integrations:write)

{
  "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, scope: integrations:write)

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, scope: integrations:read; connecting requires integrations:write)

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, scope: integrations:read)

Disconnect

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

Deletes the encrypted project credential. Apps already deployed keep the credential stored with their deployed spec, but new private image deployments can no longer use the integration.

Auth: Required (project member, non-viewer, scope: integrations:write)

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. Start the flow in a browser and complete it promptly — an abandoned flow expires and has to be restarted.

Auth: Required (project member, non-viewer, scope: integrations:write)

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, scope: integrations:read)

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, scope: integrations:read)

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, scope: integrations:read)

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, scope: integrations:write)

Body:

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

Completing the install

Once the user finishes on GitHub, the browser is returned to the control panel with ?github=connected and the installation is linked to the project the connect flow started from. The return leg is a browser redirect handled by Cosmoner — there is nothing for an API client to call.

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, scope: integrations:read)

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, scope: integrations:read)

Query Parameters:

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

Look Up App Configuration File

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

Looks for an app configuration file (.cosmoner/deployment.yaml, or deployment.yaml at the repository root) in the repository and returns its parsed services, normalized for the deploy wizard. See the App Configuration Files guide for the file format.

fileDigest is a sha256 of the file's contents. It is recorded on an app created from this file, so a later read can tell whether the file itself has changed.

Secret and variable references in the file are resolved by name against your project, and the response carries the id of the matching entry — never its value. A reference with no matching entry is returned with "missing" set, so the wizard can name what is absent instead of dropping the variable.

Auth: Required (project member; GitHub connection required, scope: integrations:read)

Query Parameters:

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

Response (template found):

{
  "success": true,
  "data": {
    "found": true,
    "valid": true,
    "path": ".cosmoner/deployment.yaml",
    "name": "my-platform",
    "environment": "production",
    "fileDigest": "9f2c…",
    "services": [
      {
        "name": "api",
        "appType": "service",
        "sourceDir": "apps/api",
        "buildStrategy": "docker",
        "buildCommand": "bun run build",
        "runCommand": "bun start",
        "outputDir": null,
        "internalPort": 3000,
        "instanceSize": "shared-s",
        "instances": 2,
        "region": "ams",
        "autoDeploy": true,
        "envVars": [
          { "key": "NODE_ENV", "value": "production" },
          { "key": "STRIPE_KEY", "value": "", "secret": true },
          { "key": "DATABASE_URL", "value": "", "secret": true, "secretName": "DATABASE_URL", "projectSecretId": "clx…" },
          { "key": "API_URL", "value": "", "variableName": "PUBLIC_API_URL", "missing": "variable" }
        ]
      }
    ]
  }
}

When no file exists, data is { "found": false }. When a file 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, scope: integrations:read)

Auto-deploy

When a project connects GitHub, Cosmoner registers a webhook on the granted repositories. A push to an app's deployed branch triggers a new deployment while auto-deploy is enabled for that app, and uninstalling the Cosmoner GitHub App detaches the connection from every project that linked it. Deliveries are authenticated on arrival; there is no endpoint for you to call.

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, scope: integrations:write)

Bitbucket

Bitbucket connections are scoped to one project. OAuth access and refresh tokens are encrypted at rest.

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 and, once the user authorizes, returns the browser to the requested control-panel path.

Auth: Required (project member; non-viewer to connect, scope: integrations:read; connecting requires integrations:write)

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, app configuration file lookup, and branch picker used by the app deployment wizard.

Auth: Required (project member; Bitbucket connection required, scope: integrations:read)

Auto-deploy and disconnect

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

Cosmoner registers a webhook on the connected repositories so a push refreshes the deployment while auto-deploy is enabled. Deliveries are authenticated on arrival; there is no endpoint for you to call. The disconnect endpoint removes those webhooks before deleting the encrypted OAuth grant.

Auth: Required (project member, non-viewer, scope: integrations:write)

GitLab

GitLab connections are scoped to one project. OAuth access and rotating refresh tokens are encrypted at rest.

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. Once the user authorizes, the browser is returned to the requested control-panel path.

Auth: Required (project member; non-viewer to connect, scope: integrations:read; connecting requires integrations:write)

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, app configuration file lookup, and branch picker used by the app deployment wizard.

Auth: Required (project member; GitLab connection required, scope: integrations:read)

Auto-deploy and disconnect

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

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

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

On this page