Install a Git Sync provider on a target

post
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
providerstring · enumRequired

The provider of the Git Sync installation.

Possible values:
targetone ofRequired

Resource targeted by a Git Sync installation.

or
Responses
201

Git Sync installation was created successfully

application/json

Provider-specific setup payload for a Git Sync installation.

projectDirectorystringOptional

Optional directory used when syncing a monorepo subdirectory.

commitMessageTemplatestringOptional

Optional template used when generating commit messages.

previewExternalBranchesbooleanOptional

Whether previews should be generated from branches outside the configured branch. For space installations belonging to a parent installation, this field is inherited from the parent installation and cannot be set.

prioritystring · enumOptional

Which side should be treated as the source of truth when Git Sync is configured.

Possible values:
objectstring · enumRequiredPossible values:
idstringRequired

Unique identifier of the Git Sync installation.

parentInstallationIdstringOptional

The ID of the parent Git Sync installation, if any.

targetone ofRequired

Resource targeted by a Git Sync installation.

or
statusstring · enumRequiredPossible values:
createdAtstring · date-timeRequired
createdBystringRequired

Identifier of the user who created the installation.

authorizedBystring · nullableRequired

Identifier of the user who connected the Git provider credentials. Only this user can browse repositories or change the repository and branch with them. Null when it is unknown, for credentials connected before it was recorded, until someone reconnects the provider.

updatedAtstring · date-timeRequired
post/git/installations
POST /v1/git/installations HTTP/1.1
Host: api.gitbook.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "provider": "github",
  "target": {
    "type": "space",
    "spaceId": "text",
    "siteId": "text"
  }
}
{
  "projectDirectory": "text",
  "commitMessageTemplate": "text",
  "previewExternalBranches": true,
  "agentInstructions": [
    "agents"
  ],
  "priority": "git",
  "provider": "github",
  "providerConfiguration": {
    "repositoryId": 1,
    "branch": "text"
  },
  "object": "git-sync-installation",
  "id": "text",
  "parentInstallationId": "text",
  "target": {
    "type": "space",
    "spaceId": "text",
    "siteId": "text"
  },
  "status": "unauthenticated",
  "repositoryConnection": {
    "object": "git-repository-connection",
    "id": "text",
    "provider": "github",
    "repositoryId": "text",
    "repositoryName": "text",
    "repositoryUrl": "https://example.com",
    "defaultBranch": "text",
    "authState": "pending",
    "capabilities": {
      "pullRequests": true,
      "commitStatuses": true
    },
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "repositoryRef": {
    "object": "git-repository-ref",
    "id": "text",
    "name": "text",
    "type": "branch",
    "latestObservedCommitId": "text",
    "latestImportedCommitId": "text",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "syncRoot": {
    "object": "git-sync-root",
    "id": "text",
    "installationId": "text",
    "target": {
      "type": "space",
      "spaceId": "text",
      "siteId": "text"
    },
    "defaultMergeAuthorityPolicy": "provider",
    "status": "active",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "text",
  "authorizedBy": "text",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "urls": {
    "location": "https://example.com"
  }
}

Last updated

Was this helpful?

Powered by GitBook