Connect a Git provider account by token. The token is checked first and sealed; it is never returned.

POST

/api/v1/git/connections

curl --request POST \
  --url https://example.com/api/v1/git/connections \
  --header 'Content-Type: application/json' \
  --data '{ "provider": "github", "name": "gitlab-acme", "baseUrl": "https://gitlab.com", "token": "example", "defaultBranch": "example" }'

Request Body^required

Media typeapplication/json

object

provider

required

github (a personal or fine-grained token; the GitHub App has its installations), gitlab, or gitea (Gitea and Forgejo).

string

Allowed values: github gitlab gitea

name

required

Unique in the organization: lowercase letters, digits and -.

string

Example

gitlab-acme

baseUrl

The provider’s URL; the provider’s public service when empty (https://api.github.com, https://gitlab.com). Required for Gitea.

string

Example

https://gitlab.com

token

required

A personal, project or group access token; write-only.

string

defaultBranch

string | null

Responses

201

Media typeapplication/json

An organization’s token connection to a Git provider. The token is never returned.

object

id

required

string

name

required

string

provider

required

github (a personal or fine-grained token; the GitHub App has its installations), gitlab, or gitea (Gitea and Forgejo).

string

Allowed values: github gitlab gitea

baseUrl

required

The provider’s API root: https://api.github.com, https://gitlab.com, a self-hosted URL.

string

authKind

required

token.

string

username

The account the token belongs to, as the provider named it at the last check.

string | null

defaultBranch

The branch new sources suggest when the repository names none.

string | null

hasToken

required

boolean

tokenHint

required

The last four characters of the token.

string

webhookUrl

Where the provider sends push events for this connection (/api/v1/webhooks/github/{id}, /api/v1/webhooks/gitlab/{id} or /api/v1/webhooks/gitea/{id}); absolute when server.public_url is set.

string | null

webhookSecret

The secret the provider’s push webhooks carry (GitHub: the webhook’s Secret, which signs the body with X-Hub-Signature-256; GitLab: the webhook’s Secret token; Gitea/Forgejo: its Secret, which signs the body). Present only in the answer of createGitConnection, never again: rotate it with POST /api/v1/git/connections/{connection}/webhook-secret.

string

createdAt

required

integer format: int64

updatedAt

required

integer format: int64

lastCheckedAt

integer | null format: int64

lastError

Why the last check failed.

string | null

Example

{
  "name": "gitlab-acme",
  "provider": "github",
  "baseUrl": "https://gitlab.com"
}

403

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

409

The name is taken

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

422

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

503

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}