Connect Git providers and registries

NebulaCtrl reads your repositories through a Git connection and pulls private images with a registry credential. Both live at the organization level, under Settings > Integrations.

Before you beginCopy Anchor Link

• You need the admin or owner role. Everyone else can see the connections but not change them.
• The provider must be able to reach the control plane's public URL, because pushes arrive as webhooks at BASE_URL/api/v1/webhooks/…. For GitHub Enterprise Server, the GitHub host must reach it too.
• The control plane must be able to reach the provider over HTTPS. It refuses hosts that resolve to loopback, link-local, private or reserved addresses, so a provider on a private network cannot be connected.

Connect GitHubCopy Anchor Link

NebulaCtrl creates a private GitHub App for each connection.

1. Open Settings > Integrations. In Source control, select Connect on the GitHub row.
2. Enter a Label of 1 to 20 characters. GitHub refuses App names that start with "GitHub" or "Gist", so the label cannot either. The App is named LABEL (NebulaCtrl).
3. Leave Host blank for github.com. For GitHub Enterprise Server, enter its hostname. NebulaCtrl then uses https://HOST/api/v3 for the API.
4. To create the App under a GitHub organization instead of your account, enter Organization login (optional).
5. Select Continue on GitHub, confirm the App on GitHub and install it on the repositories you want to deploy from.

You return to Settings > Integrations and see GitHub App connected. The App asks for these permissions and events:

Events: push and pull_request. NebulaCtrl stores the App's client secret, private key and webhook secret sealed. To change which repositories the App can see, select Manage on the row, then Manage on GitHub.

If the App was created before preview environments existed, the console shows Approve the new pull request permission on GitHub to enable previews. Pushes deploy without it.

Connect GitLabCopy Anchor Link

1. In GitLab, create a personal, group or project access token with the api scope.
2. In Source control, select Connect on the GitLab row.
3. Enter the GitLab URL. Leave it empty for gitlab.com. For a self-managed instance, give its https:// address with no path.
4. Optionally enter a Label. It defaults to the host, cut to 20 characters.
5. Paste the Access token and select Connect.

NebulaCtrl calls GitLab with the token before it saves anything. A rejected token fails with token GitLab at HOST rejected this token; nothing was saved — create a token with the api scope and try again. The repositories you can pick are the projects the token's account belongs to.

Connect ForgejoCopy Anchor Link

1. In Forgejo, create a personal access token with read:repository, write:repository and read:user.
2. In Source control, select Connect on the Forgejo row.
3. Enter the Host as a hostname such as git.example.com, a Label and the Access token, then select Connect.

NebulaCtrl verifies the token against Forgejo first. A rejected token fails with token Forgejo at HOST rejected this token; nothing was saved — create a token with repository access and try again.

WebhooksCopy Anchor Link

A delivery that fails authentication gets a bare 401 with no detail. Bodies over 1 MiB are refused.

GitHub. Nothing to configure. The App's manifest sets the URL and secret.

Forgejo and GitLab. NebulaCtrl creates the webhook itself when you give a service a Git source, after checking that the token's account has access to the repository. If the token cannot create hooks, saving the source fails and the error carries the values to add by hand: the URL, a secret, content type JSON, and the events push and pull request (for GitLab, push events and merge request events). The secret appears only in that message. There is no rotate action; changing the service's repository or connection provisions a new secret.

A push starts a build when an environment tracks the pushed branch and has auto-deploy on. Tag pushes, branch deletions and branches no environment tracks are recorded as declined. Pull requests from the same repository create preview environments; pull requests from forks never do.

What NebulaCtrl reports backCopy Anchor Link

• Commit statuses on every provider, in the context nebulactrl/ENVIRONMENT, linking to the service's Deployments tab. They move from pending ("Build queued", "Building", "Deploying release N" or "Waiting for approval") to success ("Deployment is healthy") or failure with the reason.
• GitHub Deployments, GitHub only: one deployment per release, in an environment named after the NebulaCtrl environment.

NebulaCtrl posts statuses on a best-effort basis. A failed post never blocks a build or a deploy. It posts no pull request comments.

Check, repair or remove a connectionCopy Anchor Link

Select Manage on the provider's row.

• Check connection re-runs the check and lists any Missing permissions. The row shows Connected, Not installed, Check failed or Delivery failed, the last of which means the latest webhook delivery was declined.
• Remove deletes the connection and is refused with N service(s) use this connection; change their source first until no service uses it.

Deploy from a public repositoryCopy Anchor Link

A service with source Public repository needs no connection. NebulaCtrl clones the https:// URL anonymously, so the URL cannot embed credentials. It cannot watch for pushes or report statuses; start each deploy yourself.

Add a registry credentialCopy Anchor Link

A private image needs a credential for its registry.

1. In Settings > Integrations, under Registries, select Add registry.
2. Enter the Host exactly as it appears in the image reference, for example ghcr.io, the Username, and the Password or token.
3. Select Add registry.

The password is stored sealed and never shown again. There is no edit: to rotate it, select Manage > Delete registry, then add the credential again. Deleting a credential makes every service that used it pull anonymously, so new releases of private images fail to resolve.

A credential is not matched to images by host. On each image service, choose it under Registry credential. NebulaCtrl refuses a credential whose host differs from the image's host, with registryCredentialId is for HOST, not HOST. The agent turns the credential into an image pull secret in the environment's namespace for each release.

The control plane logs in to each stored registry every 15 minutes. The row shows Connected or Unreachable, and not reported until the first check runs.

Push builds to your own registryCopy Anchor Link

By default, builds push to the registry inside the cluster. To push elsewhere, select Manage on the Build registry row, enter a Registry URL, choose a Credential, and select Save build registry. Set both or neither.

VerifyCopy Anchor Link

• The provider's row reads Connected, and Manage shows last event after the first webhook.
• A push to a tracked branch queues a build. The commit shows a nebulactrl/ENVIRONMENT status.
• The registry row reads Connected within 15 minutes, and a release of a private image resolves.

Next stepsCopy Anchor Link