Git API

List git connections

Connections to GitHub, GitLab, Gitea, Forgejo and Bitbucket. Credentials and secrets are never returned.

Connect GitLab, Gitea, Forgejo or Bitbucket

Token connections are verified against the provider first (422 credentials_invalid). OAuth connections start pending and return an authorizeUrl to open in the browser; register oauth.redirectUri as the OAuth application's redirect URI. The response carries the webhook secret once; GitLab, Gitea and Forgejo webhooks are registered automatically when a service is linked, a Bitbucket webhook is created by hand (URL webhookUrl, this secret). Requires the admin scope.

Get a git connection

Rename a git connection or replace its credentials

Requires the admin scope. Secrets are write-only.

Remove a git connection

Refused with 409 connection_in_use while services use it, unless force is set (it unlinks them). Webhooks NebulaCtrl registered are removed; a GitHub App stays installed at GitHub. Requires the admin scope.

List a repository's branches

Webhook delivery log of a connection

The last 200 deliveries (14 days), newest first: event, outcome (processed, ignored, rejected, replayed, error), what they started. Headers are redacted. Requires the admin scope.

Start (or restart) the OAuth authorization of a connection

Returns the provider URL to open in the browser.

Look up a GitHub App's installation again

For an App installed without returning to NebulaCtrl: finds the installation through the GitHub API and verifies the connection.

List the repositories a connection can access

The repository picker. 422 no_repo_api for Bitbucket (enter owner/name instead). Requires projects:write.

Test a git connection

Calls the provider with the stored credentials and records the outcome in status.

Issue a new webhook secret (Bitbucket)

Only for providers whose webhook is created by hand (Bitbucket). The new secret is returned once; update the webhook at the provider.

Start creating a GitHub App

Creates a pending GitHub connection and returns a manifest: submit it as the form field manifest with a POST to postUrl (the browser does this; GitHub asks the user to confirm). GitHub then redirects back to NebulaCtrl, which stores the App and sends the user to install it. The App gets read access to code and metadata and write access to pull requests and commit statuses, and subscribes to push and pull_request events. Needs NEBULACTRL_PUBLIC_URL (422 public_url_required). Requires the admin scope.

Get a git service's SSH deploy key and pinned host keys

The public key and fingerprint, the provider's "add deploy key" link when the host is a known public instance, and each pinned host key (with the refused key when the host's key changed). The private key is never returned. 422 not_git_source.

Accept the SSH host key the git host presents now

Replaces the pinned host key of the service's git host after you reviewed the fingerprint of the refused key. 409 host_key_changed when the server presents yet another key, 502 host_unreachable when it cannot be reached. Needs projects:write.

Generate, upload or rotate the SSH deploy key

Without privateKey an Ed25519 key pair is generated; the public key goes on the repository as a deploy key. With privateKey your own unencrypted key is stored (write-only). An existing key is replaced only with rotate: true; otherwise 409 ssh_key_exists. Needs projects:write. Takes effect on the next deployment; nothing is staged.

Remove the SSH deploy key and the pinned host keys

Needs projects:write. A service whose git URL is an SSH URL cannot be deployed until a key is set again.

Test the SSH connection to the repository

Fetches the configured branch over SSH with the deploy key. The first connection pins the host key; a changed key is refused and recorded. Always 200: ok and code (no_key, not_ssh_url, host_key_changed, git_unreachable) say what happened. Needs projects:write.