Git connections and sources

Use these endpoints to inspect Git capabilities, manage Forgejo and GitLab connections, connect your personal GitLab account, select a repository, and bind a source to a project. Routes are under /v1 and use the active organization.

Authentication and permissions

Use the authentication method allowed for each route; with a user token, also send x-organization-id (with an organization API Key, the header is not needed). 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.

OperationMinimum permission
Read providers and runtimesValid organization authentication (session or API key allowed for the route)
List connections, validate a repository, or read branchesproject.source.update on project:*
Create, replace credentials, or revoke a connectionOrganization owner session
Connect, check, or disconnect your own GitLabUser session of the owner or of a member who can create projects in the organization or in a team
Read the project source and branchesproject.read on project:<project-id>
Change project source and build settingsproject.source.update on project:<project-id>
Start the build after changing source or build settingsproject.deploy.trigger on project:<project-id>
Create an HTTP projectproject.create on organization:*

Read capabilities and runtimes

GET /v1/git/providers
GET /v1/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, forgejo, and gitlab. The gitlab item also includes oauth_available, which says whether the personal OAuth connection with gitlab.com is 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 and GitLab connections

List connections

GET /v1/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.

A personal GitLab connection, created by the OAuth flow described in Connect your personal GitLab account, also includes owner_user_id, auth_method: "oauth", account_username and, when GitLab no longer accepts the authorization, needs_reauth: true. It is listed for the person who connected it and, as an existence record only, for the organization owner. Only that person can use it to list repositories, resolve paths, and bind projects; an API Key does not use personal connections. The repositoryDiscovery capability is true on personal connections and false on GitLab token connections.

Create a connection

POST /v1/git/connections

The body requires the fields below and returns 201. Use an HTTPS URL with a trusted certificate and the explicit repository path; token connections do not offer repository discovery. 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.

FieldTypeDescription
provider_idstringforgejo or gitlab
instance_urlstringCanonical HTTPS address of the instance, such as https://gitlab.com or the address of a self-managed GitLab (up to 2048 characters)
display_namestringOrganization-selected display name (1 to 120 characters)
repository_pathstringExplicit path, such as team/application (3 to 1024 characters)
usernamestringForgejo only: account used by the credential (1 to 256 characters). Do not send it for GitLab connections
tokenstringToken used for validation, up to 8192 characters; never returned

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.

For GitLab, use a personal, group, or project access token with the api and read_repository scopes. For Zenifra to create the webhook for push deployments and merge request previews, the token needs the Maintainer role on the project. Paths with subgroups, such as group/subgroup/app, are accepted. See Deploy from GitLab.

Replace credentials

PATCH /v1/git/connections/:connectionId/credentials

The body accepts repository_path, username, and token; on GitLab connections, username is ignored. The replaced credential is not displayed. Personal GitLab connections do not accept this route and return 404 (GIT_CONNECTION_NOT_FOUND): the person reconnects through the OAuth flow. The server controls the revision and performs the owner-session authorization checks.

Revoke a connection

DELETE /v1/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. Personal GitLab connections return 404 (GIT_CONNECTION_NOT_FOUND) on this route; the person removes them with DELETE /v1/auth/gitlab/personal. Existing GitHub authorization management remains on its current OAuth routes.

Connect your personal GitLab account

Each person can connect their own gitlab.com account to the active organization. The routes below require the user session (a user token with x-organization-id); an API Key cannot use them. The owner and members who can create projects in the organization or in a team can connect.

GET /v1/auth/gitlab
GET /v1/auth/gitlab/status
DELETE /v1/auth/gitlab/personal

GET /auth/gitlab returns { authorization_url, state } and sets a cookie that binds the browser to the flow. Open authorization_url in the same browser: GitLab asks for the api and read_repository scopes and, after authorization, Zenifra returns to the Console Account page with ?gitlab_connected=1 or ?gitlab_error=<code>. The possible codes are access_denied, auth_failed, missing_code, invalid_state, permission_required, and unavailable. Without permission to connect, the route returns 403; when connecting GitLab is not available, it returns 503 (GIT_OAUTH_UNAVAILABLE).

GET /auth/gitlab/status returns the caller's connection in the active organization:

{
  "available": true,
  "connected": true,
  "connection_id": "connection-id",
  "username": "gitlab-user",
  "connected_at": "2026-11-11T12:00:00.000Z",
  "needs_reauth": false
}

With needs_reauth: true, GitLab no longer accepts the authorization (for example, because it was revoked in GitLab): builds of the projects on that connection fail until the person connects again through GET /auth/gitlab.

DELETE /auth/gitlab/personal removes the webhooks Zenifra created on the GitLab projects, revokes the access, and returns { "disconnected": true }, or false when there was no connection. Projects created with the connection stop receiving deployments; after reconnecting, bind the repository again with PUT /v1/project/:id/source.

Resolve repositories and branches

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

POST /v1/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, such as GitLab subgroups; 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 /v1/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 /v1/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.

dockerfile_path must be a relative path inside the repository, up to 256 characters: absolute paths, . or .. as a segment, backslashes, and leading or trailing slashes are rejected with 400. The source branch follows Git branch name rules: names with spaces, .., @{, starting with - or refs/, or equal to HEAD are also rejected with 400.

context_path is the build root directory: the repository folder where install, pre-build, build, and start run. It is optional, defaults to "." (the repository root), and applies to creation, PUT /project/:id/source, and PATCH /project/:id/build-settings. The API trims surrounding whitespace, a leading ./, and a trailing /; absolute paths, .., backslashes, or values longer than 256 characters are rejected with 400. Like the other build fields, a change to context_path applies from the next build. The full rules are in Build root directory.

{
  "context_path": "apps/api"
}

The example above is a valid body for PATCH /project/:id/build-settings.

GET /v1/project/:id/source
PUT /v1/project/:id/source
PATCH /v1/project/:id/build-settings
DELETE /v1/project/:id/source
GET /v1/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. When PUT /project/:id/source changes the repository, branch, or build settings of a project that already had a source, or when PATCH /project/:id/build-settings changes the build settings, the API starts a new build and returns build_id next to data. Without project.deploy.trigger, the change is saved, no build starts, and the response includes build_required: true next to data; the next manual deploy or configured event applies the change. If the change was saved but the build could not start, the response has no build_id; start a manual deploy. 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. On GitLab sources, versionDeploy is false: use only auto_deploy and do not send version_deploy. See Deploy from Forgejo and Deploy from GitLab 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.

Errors and limits

Errors use { "status": "failed", "code": "...", "message": "..." }. A body, path parameter, or query in the wrong format is rejected earlier with 400 and only message (Invalid Git request or Invalid Git source request), without code.

StatusCodeWhen it happens
400GIT_INSTANCE_INVALID, GIT_REPOSITORY_INVALID, GIT_SOURCE_INVALID, GIT_BUILD_SETTINGS_INVALID, GIT_REFERENCE_INVALIDInvalid data for the instance, repository, source, build, or reference
401—Connection writes with an API Key: these operations require the owner session
403GIT_CREDENTIAL_OWNER_SESSION_REQUIREDA CLI or delegated credential was used to manage Git credentials
403GIT_PROVIDER_FORBIDDENThe provider denied access to the resource (a session without the owner role receives 403 with owner role required)
404GIT_CONNECTION_NOT_FOUND, GIT_REPOSITORY_NOT_FOUND, PROJECT_NOT_FOUNDConnection, repository, or project not found
409GIT_CONNECTION_REVOKED, GIT_CONNECTION_CONFLICT, GIT_CONNECTION_STALE, GIT_TRANSITION_BUSY, GIT_SOURCE_NOT_CONFIGURED, GIT_SOURCE_TRANSITION_PENDINGThe connection was changed or revoked, a Git operation is in progress, or the project has no configured source
409GIT_CONNECTION_UNAVAILABLEThe selected Git connection is not available to the organization (message The selected Git connection is unavailable.)
422GIT_CREDENTIALS_INVALIDThe credentials cannot access the selected repository
429GIT_PROVIDER_RATE_LIMITEDThe provider temporarily rate limited requests
501GIT_CAPABILITY_UNSUPPORTEDThe provider does not offer the requested capability
502, 503GIT_PROVIDER_RESPONSE_INVALID, GIT_PROVIDER_UNAVAILABLE, GIT_CONFIGURATION_UNAVAILABLE, GIT_OPERATION_UNAVAILABLEThe provider or the Git integration is temporarily unavailable
503GIT_BUILD_UNAVAILABLEWhen creating a project with config.source, the build is temporarily unavailable; try again shortly

Rate limits (counted per source IP):

OperationLimit
GET /v1/git/providers, GET /v1/git/runtime-catalog60 per minute
GET /v1/git/connections30 per minute
POST /v1/git/connections, PATCH /v1/git/connections/:connectionId/credentials, DELETE /v1/git/connections/:connectionId5 every 5 minutes
POST /v1/git/connections/:connectionId/repositories/resolve30 per minute
GET /v1/git/connections/:connectionId/repositories and .../branches60 per minute
GET /v1/project/:id/source50 per minute
PUT and DELETE /v1/project/:id/source, PATCH /v1/project/:id/build-settings10 per minute
GET /v1/project/:id/source/branches30 per minute
GET /v1/auth/gitlab10 per minute
GET /v1/auth/gitlab/status30 per minute
DELETE /v1/auth/gitlab/personal5 per minute

Next steps

Last updated on

On this page