Git connections and sources

Use these endpoints to inspect Git capabilities, manage a Forgejo connection, select a repository, and bind a source to a project. Routes are under /v1 and use the active organization.

Authentication and permissions

Send x-organization-id and use the authentication method allowed for each route. Successful responses use { "status": "success", "data": ... }. Provider credentials can only be created, replaced, or revoked by an organization owner session; an API key cannot replace that session. Credentials are never returned.

Read capabilities and runtimes

GET /git/providers
GET /git/runtime-catalog

GET /git/providers returns api_version and a list with id, available, and the repositoryDiscovery, pushDeploy, nativePreviews, and versionDeploy capabilities. Availability says whether new projects for that provider can currently be accepted; capabilities describe operations offered by the connection. The current catalog includes GitHub and Forgejo; a GitLab integration is not available. The endpoint requires organization authentication and does not require project.read.

GET /git/runtime-catalog returns the current Git runtime and version catalog without image fields.

Manage Forgejo connections

List connections

GET /git/connections

Only connections from the active organization are returned. A connection is projected publicly as:

{
  "id": "connection-id",
  "provider_id": "forgejo",
  "instance_url": "https://forgejo.example.test",
  "display_name": "Team Forgejo",
  "status": "active",
  "connection_revision": 1,
  "capabilities": {
    "repositoryDiscovery": false,
    "pushDeploy": true,
    "nativePreviews": false,
    "versionDeploy": true
  }
}

created_at and updated_at may appear as ISO dates. The response does not include a token, credential revision, access policy, or private connectivity details.

Create a connection

POST /git/connections

The body requires the fields below and returns 201. Use an HTTPS URL with a trusted certificate and the explicit repository path; Forgejo repository discovery is not currently available. A private instance must be reachable through the connection enabled for the organization. For event-based publishing, Forgejo must also be able to deliver HTTPS hooks to Zenifra. Do not transmit a token in a URL or command argument.

Supplying a URL does not create access to a private network, and opening the address in your browser does not confirm that Zenifra can reach it. When possible, restrict the token to the selected repository. See Forgejo 15.0 token scopes: read:repository covers validation and read operations for manual deploys; write:repository and account permission to manage hooks are required for branch, tag, and release events. The Forgejo 15.0 webhook documentation describes hooks.

Replace credentials

PATCH /git/connections/:connectionId/credentials

The body accepts repository_path, username, and token. The replaced credential is not displayed. The server controls the revision and performs the owner-session authorization checks.

Revoke a connection

DELETE /git/connections/:connectionId

When revocation is accepted, the response contains connection with the public revoked projection and cleanup_pending. cleanup_pending: true means related cleanup is still pending; it does not confirm that cleanup finished on the remote instance. A pending operation can prevent revocation and return 409; in that case, the connection remains active. Only a successful response confirms that local authorization was revoked. Existing GitHub authorization management remains on its current OAuth routes.

Resolve repositories and branches

Resolve one repository without global discovery by providing its explicit path:

POST /git/connections/:connectionId/repositories/resolve

{
  "path": "team/application"
}

The response contains { id, path, default_branch, private, web_url? }. The id is opaque: use it only with the connection that returned it. Paths can contain more than two components; provider-specific validation belongs to the provider. Explicit resolution works even when repository discovery is unavailable.

When the connection advertises repository discovery, you can also list pages:

GET /git/connections/:connectionId/repositories?cursor=<opaque-cursor>

cursor is optional and opaque. The response contains repositories and next_cursor; an unsupported capability returns a safe capability error rather than requesting broader access.

To list branches, encode the opaque repository ID as one path segment:

GET /git/connections/:connectionId/repositories/:repositoryId/branches

The data response contains objects such as { "name": "main", "commit_sha": "<commit-sha>" }.

Create and inspect a project source

In the existing HTTP project creation request, send config.source and config.build together. The example below configures release publishing. For manual publishing, omit version_deploy; to publish on branch pushes, set auto_deploy to true and omit version_deploy. Do not combine source or build with the legacy github configuration.

{
  "config": {
    "source": {
      "connection_id": "connection-id",
      "repository_id": "repository-id-from-connection",
      "branch": "main",
      "auto_deploy": false,
      "version_deploy": {
        "enabled": true,
        "event": "release",
        "tag_pattern": "v*",
        "include_prereleases": false
      }
    },
    "build": {
      "runtime": "nodejs",
      "version": "24",
      "start_command": "npm start",
      "pre_build_command": null,
      "build_command": "npm run build",
      "dockerfile_path": "Dockerfile",
      "context_path": "."
    }
  }
}

Build fields are optional. The catalog provides runtime and version defaults. Available fields are runtime, version, start_command, pre_build_command, build_command, dockerfile_path, and context_path.

GET /project/:id/source
PUT /project/:id/source
PATCH /project/:id/build-settings
DELETE /project/:id/source
GET /project/:id/source/branches

PUT /project/:id/source accepts { "source": ..., "build": ... } and returns the source projection. PATCH /project/:id/build-settings accepts a subset of build fields and returns the same projection. GET /project/:id/source/branches lists branches for the current source. DELETE /project/:id/source returns the projection with source, build, and capabilities set to null, stops future deploys for that source, and preserves the published application.

The GET and PUT projection has this shape:

{
  "source": {
    "connection_id": "connection-id",
    "repository_id": "repository-id-from-connection",
    "branch": "main",
    "auto_deploy": false,
    "version_deploy": {
      "enabled": true,
      "event": "release",
      "tag_pattern": "v*",
      "include_prereleases": false
    },
    "provider_id": "forgejo",
    "repository_path": "team/application"
  },
  "build": {
    "runtime": "nodejs",
    "version": "24",
    "start_command": "npm start",
    "dockerfile_path": "Dockerfile",
    "context_path": "."
  },
  "source_revision": 1,
  "capabilities": {
    "repositoryDiscovery": false,
    "pushDeploy": true,
    "nativePreviews": false,
    "versionDeploy": true
  }
}

When there is no source, source, build, and capabilities are null. The server updates revisions when the effective source or settings change. For publishing mode, auto_deploy: true enables publications on pushes to the branch. For tags or releases, keep auto_deploy: false and enable version_deploy; both automatic modes cannot be enabled together. The tag pattern matches the full tag name, is case-sensitive, and supports only * and ? wildcards in 1 to 255 characters. Draft releases do not publish; pre-releases are excluded by default and can be included. See Deploy from Forgejo for the modes and requirements.

The source field of a preview DTO serves another purpose: existing native previews remain compatible and must not be interpreted as this Git source.

Next steps

• Deploy from Forgejo
• Git repository builds
• Deploy and Automation CLI