Connect a self-hosted Git forge

Self-hosted forge support is available as an opt-in beta. The compatibility contract is verified against the supported product targets before each release.

In the beta, you connect a Gitea, Forgejo, or Gogs instance once, select its repositories when creating an App, Site, Worker, or Cron Job, and let Hostless build and deploy from your chosen branch.

Supported products and capabilities

Product	Validation target	Connection method	Hostless workflow
Gitea	1.23 and later	Personal access token (PAT)	Private clone, repository and branch discovery, files, commits, webhooks, push deployments, pull requests, review apps, PR comments, and commit statuses
Forgejo	10 and later	Personal access token (PAT)	Private clone, repository and branch discovery, files, commits, webhooks, push deployments, pull requests, review apps, PR comments, and commit statuses
Gogs	0.13 container-contract target	Access token	Private clone, repository and branch discovery, files, commits, webhooks, and push deployments only

Gitea and Forgejo provide the complete review workflow used by Hostless. Gogs does not expose stable REST APIs for pull requests, pull-request comments, or commit statuses, so Gogs connections do not support review apps or review/status feedback. Hostless reports those capabilities as unavailable and rejects unsupported operations before contacting the forge.

Gogs 0.13 does not expose its version through the stable REST API. A Gogs connection therefore shows Version unreported. Hostless validates the exact product identity and authenticated core API access instead; the container compatibility matrix separately verifies the configured Gogs release target. Hostless never invents a remote Gogs version.

The beta covers Apps, Sites, Workers, and Cron Jobs. A push to the configured branch deploys any supported resource. Pull-request events create and update App review apps only for Gitea and Forgejo.

Before you connect

Your forge must meet all of these requirements:

• Use an HTTPS URL with a certificate trusted by Hostless. Self-signed, expired, or otherwise invalid TLS certificates are not supported.
• Be reachable from the Hostless API. The URL may include an installation path, such as https://git.example.com/forge, but do not include /api/v1, credentials, a query string, or a fragment.
• Let the forge send webhooks to a publicly reachable Hostless HTTPS endpoint. A forge that is reachable only by Hostless cannot deliver push or pull-request events unless it can also reach Hostless.
• Allow HTTPS Git clone access. SSH-only repositories are not supported.

Hostless blocks loopback, link-local, metadata, unspecified, and private network addresses for forge connections by default. This prevents a connected URL from reaching services that should stay internal. A Hostless operator may enable FORGE_ALLOW_PRIVATE_NETWORKS=true only when a private forge is intentional and its network boundary is understood.

warning

Enabling private-network access changes the SSRF protection boundary for every self-hosted forge connection. Restrict who can create connections, use a dedicated egress policy, and keep the forge URL and DNS under operator control.

Configure Hostless

The beta is disabled by default. Set the feature flag and a stable credential-encryption key in the Hostless API environment before allowing users to create connections:

SELF_HOSTED_FORGES_ENABLED=true
FORGE_CREDENTIAL_ENCRYPTION_KEY=<secure-32-byte-secret>

For a deliberately private forge, an operator can additionally set:

FORGE_ALLOW_PRIVATE_NETWORKS=true

Keep FORGE_CREDENTIAL_ENCRYPTION_KEY in your deployment secret manager. Rotating or losing it can prevent Hostless from using tokens stored by existing connections. Do not put a token, webhook secret, or forge URL with embedded credentials in source control.

Create a token

Create a token for a user or service account that has access only to the repositories Hostless should deploy. Saving a connection validates the forge product, authenticated identity, and repository read access. Private cloning uses that same read access. Hostless checks webhook-write permission when you create or move a resource onto the repository, and checks status or comment permission only when a Gitea or Forgejo review workflow exercises those operations.

Product	Token guidance
Gitea 1.23+	Create a scoped PAT with repository read and write access and user-profile read access. Repository write access is required for webhook management, deployment statuses, and pull-request comments. Limit the account's repository membership to the intended repositories.
Forgejo 10+	Create a scoped PAT with repository read and write access and user-profile read access. Where the instance offers repository restrictions for tokens, select only the repositories Hostless will deploy.
Gogs 0.13+	Generate an access token for a dedicated service account. Gogs tokens do not provide the same fine-grained scope controls, so use repository or organization membership to limit what the account can access. Status/comment write permission is not required because Hostless does not offer those workflows for Gogs.

Use a dedicated account when practical. Do not use an administrator token, and revoke the token when the connection is no longer needed.

Connect an instance

1. In Hostless, open Account Settings or Project Settings, then open Git connections.
2. Choose Gitea, Forgejo, or Gogs.
3. Enter the HTTPS base URL of the forge. Include the installation path when the forge is hosted below one, for example https://git.example.com/forge.
4. Paste the token and save the connection. Hostless validates the product, authenticated identity, and repository read access. It validates Gitea and Forgejo version floors; Gogs displays Version unreported because its stable API does not provide a remote version. Webhook, status, and comment write permissions are not claimed at this step.
5. Create or edit an App, Site, Worker, or Cron Job and select the connection, repository, and branch.

Every connection has its own identity, so one account or project can connect more than one instance of the same product. Before disconnecting, switch every dependent App, Site, Worker, and Cron Job to another source or delete it, then wait for repository-hook cleanup to finish. Hostless blocks disconnect while active dependencies remain. If hook cleanup is still pending, the connection stays pending deletion and is removed only after cleanup succeeds; retry the cleanup rather than removing forge credentials prematurely.

Webhooks, push deployments, and review apps

During resource setup, Hostless creates and verifies the repository webhook. This is when webhook-write permission is exercised. Keep the forge able to reach Hostless over public HTTPS, including through any firewall, reverse proxy, or DNS configuration. Do not rewrite or strip webhook signature headers at the proxy.

For every supported forge, a push to the configured branch starts a deployment. With Gitea and Forgejo, Hostless can also report deployment state to the commit, post the preview URL on a pull request, create or update a review app when the pull request opens or changes, and remove it when the pull request closes or merges. Gogs supports push deployments but not that review workflow. See Review apps for review-app settings and limits.

Troubleshooting during the beta

Use this guidance after the self-hosted forge beta is enabled for your account or project. The supported targets and API behavior are covered by the container contract matrix.

Connection validation fails during the beta

• Confirm the selected product and validation target: Gitea 1.23+, Forgejo 10+, or the Gogs 0.13 container-contract target. A successfully identified Gogs connection reports its remote version as unreported.
• Use the forge's browser-facing HTTPS base URL, including its path prefix if applicable. Do not use the API URL or a clone URL.
• Fix the forge certificate chain; Hostless rejects invalid or self-signed TLS.
• Check DNS from the Hostless API environment. Private, loopback, link-local, metadata, and unspecified addresses are rejected unless the operator has explicitly enabled private-network access.
• Recreate the token with the required repository and user access, and confirm the token's account can open the private repository in the forge UI.

Beta pushes do not deploy or review apps do not update

• Confirm the resource is configured for the repository and branch that received the push.
• Verify the repository webhook is present, enabled, and shows successful deliveries. The forge must be able to reach Hostless's public HTTPS webhook endpoint.
• Check that an intervening reverse proxy preserves the request body and signature headers.
• For Gitea and Forgejo review apps, confirm they are enabled in the App's Review Apps settings and that the token can create commit statuses and pull-request comments.
• Gogs does not support review apps, pull-request comments, or commit statuses. Use Gitea or Forgejo when those workflows are required.

Beta statuses or comments are missing

For Gitea or Forgejo, recheck the token's repository write access and the service account's repository role, then retry the status or comment operation. Replace the saved connection only when the token value itself changed; connection setup does not pre-validate status and comment writes. Gogs intentionally reports statuses and comments as unavailable; push deployments remain supported without them.

Out of scope

This integration does not support OAuth login to self-hosted forges, SSH-only repositories, invalid or self-signed TLS, Gitea or Forgejo Actions, repository administration, or forge products other than Gitea, Forgejo, and Gogs.