Self-hosted Git providers

Clowld Space connects to a self-hosted Git provider per workspace: Forgejo, Gitea, or GitLab. Once connected, any pull request (GitLab: merge request) whose branch name or title contains an issue identifier (for example CS-123), or whose body names one after a closing keyword (Closes CS-123), is auto-linked to that issue and appears under Pull requests in the issue sidebar. When no linked PR is open or draft and a merged PR used a closing keyword, the issue moves to the workspace’s chosen status (Done by default). CI for the head commit shows as a checks bar on the card.

These providers run alongside GitHub: a workspace can use any combination.

In Settings → Code, After PRs merge, move the issue to chooses Done (the default), a started or done status, including custom statuses, or Don’t change. Blocked is excluded. Both providers use the same setting.

Prerequisites (server)

Turn the integration on for this deployment. It is off by default, so the section stays hidden until you set:

CLOWLD_VCS_INTEGRATION_ENABLED=true

The official self-hosted docker compose file (docker-compose.selfhost.yml) sets this for you.

Then set a base64-encoded 32-byte key so the server can encrypt stored credentials. Without it, the connect form is disabled.

openssl rand -base64 32

CLOWLD_VCS_SECRET_KEY=<base64 32-byte key>

Both are required: the switch decides whether the feature is offered, and the key encrypts the stored token and webhook secret. Connect, webhook, and rotate all require both.

Set CLOWLD_PUBLIC_URL to the server's public base URL so Clowld Space can show a ready-to-paste webhook URL. Without it, the UI shows only the webhook path and you prepend your own origin.

Connect a workspace

1. Create an access token in your provider with read access to the repositories you want mirrored:
   • Forgejo / Gitea: Settings → Applications.
   • GitLab: a personal (or group/project) access token with the read_api scope.
2. In Clowld Space, open Settings → Code, then click Connect in the Self-hosted Git row.
3. Choose the provider, enter the instance URL (for example https://forgejo.example.com) and the access token, then Connect. Clowld Space validates the token against the instance before saving.
4. Copy the webhook URL and webhook secret shown after connecting.

Instance with a private CA

If Connect reports that the provider's certificate "is signed by a certificate authority this server does not trust", the instance's HTTPS certificate comes from an internal CA (or is self-signed) that the Clowld Space server does not trust. A server operator adds that CA to the backend's trust store: with Helm, set backend.extraCACerts.configMap; with Docker Compose, mount the CA and set SSL_CERT_DIR. See Private CA certificates for the steps.

Clowld Space has no option to skip certificate verification, because the connect request carries your access token. If the message says the certificate does not match the host name, or failed verification (for example, it has expired), fix the certificate itself; trusting the CA does not help.

Register the webhook

On the repository (or organisation/group, to cover every repo):

Forgejo / Gitea — Settings → Webhooks → Add Webhook → Forgejo/Gitea:

• Target URL: the webhook URL from the previous step.
• HTTP method POST, content type application/json.
• Secret: the webhook secret (used to verify the X-Gitea-Signature HMAC).
• Trigger events: select Pull Request, and Commit Status to mirror CI.

GitLab — Settings → Webhooks:

• URL: the webhook URL.
• Secret token: the webhook secret (sent as X-Gitlab-Token and compared verbatim).
• Triggers: enable Merge request events, and Pipeline events to mirror CI.

Clowld Space authenticates every delivery against the stored secret, so a webhook without the matching secret is rejected.

What gets mirrored

• Pull / merge requests — open, closed, merged, and draft state, author, branch, and (where the provider supplies them) diff stats.
• Issue links — an identifier in the title or branch links the PR to the issue, as does an identifier after a closing keyword in the body; a bare mention in the body links nothing. Once no linked PR is open or draft — across GitHub and self-hosted providers — and a merged PR used a closing keyword (Closes/Fixes/Resolves CS-123), the issue moves to the workspace’s chosen status (Done by default), under the same workspace setting and rules as GitHub.
• CI — Forgejo/Gitea commit statuses and GitLab pipelines aggregate into a passed/failed/pending checks bar for the head commit.

Agents opening pull requests

Creating PRs needs no provider configuration in Clowld Space. Agents check out repositories in the runtime and push branches and open PRs using the runtime host's own Git credentials. To let agents work against a provider, ensure the daemon host can authenticate to it — for example an SSH deploy key, or a token in the host's Git credential helper — and add the repository URL as usual. Repository checkout works with any Git URL, so no provider-specific wiring is required.