> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/developers/gitbook-api/api-reference/git/update-a-git-sync-installation-configuration.md).

# Update a Git Sync installation configuration

Updates the installation configuration, then queues a sync operation using the new settings. A `git` priority queues an import from the selected repository and branch into GitBook; a `gitbook` priority queues an export from GitBook to the repository. Site imports require a `gitbook-docs.yaml` file at the configured project directory and return a conflict without saving or queuing the sync when the file is missing. Updates to GitLab instances also return a conflict if their settings changed while the update was being prepared; reload the installation before retrying.

```json
{"openapi":"3.1.0","info":{"title":"GitBook API","version":"0.0.1-beta"},"tags":[],"servers":[{"url":"{host}/v1","variables":{"host":{"default":"https://api.gitbook.com"}}}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer"}},"parameters":{"installationId":{"name":"installationId","in":"path","required":true,"description":"Identifier of the installation","schema":{"type":"string"}}},"schemas":{"GitSyncInstallationSetup":{"description":"Provider-specific setup payload for a Git Sync installation.","allOf":[{"$ref":"#/components/schemas/GitSyncInstallationSetupCommon"},{"oneOf":[{"$ref":"#/components/schemas/GitSyncInstallationSetupGitHub"},{"$ref":"#/components/schemas/GitSyncInstallationSetupGitLab"}],"discriminator":{"propertyName":"provider"}}]},"GitSyncInstallationSetupCommon":{"type":"object","description":"Common setup fields for a Git Sync installation.","properties":{"projectDirectory":{"type":"string","description":"Optional directory used when syncing a monorepo subdirectory."},"commitMessageTemplate":{"type":"string","description":"Optional template used when generating commit messages."},"previewExternalBranches":{"type":"boolean","description":"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."},"agentInstructions":{"type":"array","description":"Agent instruction files GitBook should always export at the repository root. For space installations belonging to a parent installation, this field is inherited from the parent installation and cannot be set.","items":{"type":"string","enum":["agents","claude"]}},"priority":{"$ref":"#/components/schemas/GitSyncInstallationPriority"}}},"GitSyncInstallationPriority":{"type":"string","description":"Which side should be treated as the source of truth when Git Sync is configured.","enum":["git","gitbook"]},"GitSyncInstallationSetupGitHub":{"type":"object","description":"GitHub provider configuration for a Git Sync installation.","properties":{"provider":{"type":"string","enum":["github"]},"providerConfiguration":{"type":"object","description":"GitHub specific configuration for the Git Sync installation.","properties":{"repositoryId":{"type":"number","description":"GitHub repository identifier."},"branch":{"type":"string","pattern":"^refs/heads/.+$","description":"GitHub repository branch ref."}}}},"required":["provider","providerConfiguration"]},"GitSyncInstallationSetupGitLab":{"type":"object","description":"GitLab provider configuration for a Git Sync installation.","properties":{"provider":{"type":"string","enum":["gitlab"]},"providerConfiguration":{"type":"object","description":"GitLab specific configuration for the Git Sync installation.","properties":{"projectId":{"type":"number","description":"GitLab project identifier."},"accessToken":{"type":"string","description":"GitLab access token with appropriate scopes for repository access."},"customInstanceURL":{"oneOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Public HTTPS URL of a self-hosted GitLab instance. Supported legacy HTTP URLs may be resubmitted unchanged while migration is pending. Use null to reconnect to gitlab.com. Changing the instance URL requires an accessToken in the same request."},"branch":{"type":"string","pattern":"^refs/heads/.+$","description":"GitLab repository branch ref."}}}},"required":["provider","providerConfiguration"]},"GitSyncInstallation":{"allOf":[{"$ref":"#/components/schemas/GitSyncInstallationSetup"},{"type":"object","properties":{"object":{"type":"string","enum":["git-sync-installation"]},"id":{"type":"string","description":"Unique identifier of the Git Sync installation."},"parentInstallationId":{"type":"string","description":"The ID of the parent Git Sync installation, if any."},"target":{"$ref":"#/components/schemas/GitSyncInstallationTarget"},"status":{"$ref":"#/components/schemas/GitSyncInstallationStatus"},"repositoryConnection":{"$ref":"#/components/schemas/GitRepositoryConnection"},"repositoryRef":{"$ref":"#/components/schemas/GitRepositoryRef"},"syncRoot":{"$ref":"#/components/schemas/GitSyncRoot","description":"Effective Sync Root for this installation, inherited from its parent when present."},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"createdBy":{"type":"string","description":"Identifier of the user who created the installation."},"authorizedBy":{"description":"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.","oneOf":[{"type":"string"},{"type":"null"}]},"updatedAt":{"$ref":"#/components/schemas/Timestamp"},"urls":{"type":"object","description":"URLs associated with the installation","properties":{"location":{"type":"string","description":"URL of the installation endpoint in the API","format":"uri"}},"required":["location"]}},"required":["object","id","target","status","createdAt","createdBy","authorizedBy","updatedAt","urls"]}]},"GitSyncInstallationTarget":{"description":"Resource targeted by a Git Sync installation.","oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["space"],"description":"Type of resource targeted by the Git Sync installation."},"spaceId":{"type":"string","description":"Unique identifier of the space targeted by the Git Sync installation."},"siteId":{"type":"string","description":"Unique identifier of the site whose Git Sync installation should manage the space installation. Omit to install Git Sync directly on the space."}},"required":["type","spaceId"]},{"type":"object","properties":{"type":{"type":"string","enum":["site"],"description":"Type of resource targeted by the Git Sync installation."},"siteId":{"type":"string","description":"Unique identifier of the site targeted by the Git Sync installation."}},"required":["type","siteId"]}],"discriminator":{"propertyName":"type"}},"GitSyncInstallationStatus":{"type":"string","enum":["unauthenticated","active","pending"]},"GitRepositoryConnection":{"type":"object","properties":{"object":{"type":"string","enum":["git-repository-connection"]},"id":{"type":"string","description":"Unique identifier of the repository connection."},"provider":{"$ref":"#/components/schemas/GitSyncInstallationProvider"},"repositoryId":{"type":"string","description":"Repository identifier assigned by the provider."},"repositoryName":{"type":"string","description":"Full repository name assigned by the provider."},"repositoryUrl":{"type":"string","format":"uri","description":"URL of the repository on the provider."},"defaultBranch":{"type":"string","description":"Default branch reported by the provider."},"authState":{"type":"string","enum":["pending","active","unauthenticated"]},"capabilities":{"type":"object","description":"Provider operations available to this repository connection.","properties":{"pullRequests":{"type":"boolean","description":"Whether the connection can create and update GitHub pull requests or GitLab merge requests."},"commitStatuses":{"type":"boolean","description":"Whether the connection can publish GitBook synchronization results as provider commit statuses."}},"required":["pullRequests","commitStatuses"]},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"updatedAt":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","provider","repositoryId","repositoryName","repositoryUrl","authState","capabilities","createdAt","updatedAt"]},"GitSyncInstallationProvider":{"type":"string","description":"The provider of the Git Sync installation.","enum":["github","gitlab"]},"Timestamp":{"type":"string","format":"date-time"},"GitRepositoryRef":{"type":"object","properties":{"object":{"type":"string","enum":["git-repository-ref"]},"id":{"type":"string","description":"Unique identifier of the repository ref."},"name":{"type":"string","description":"Fully qualified provider ref name."},"type":{"type":"string","enum":["branch","tag","change-request-head"]},"latestObservedCommitId":{"type":"string"},"latestImportedCommitId":{"type":"string"},"updatedAt":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","name","type","updatedAt"]},"GitSyncRoot":{"type":"object","description":"A repository-backed review and permission boundary for GitBook content.","properties":{"object":{"type":"string","enum":["git-sync-root"]},"id":{"type":"string","description":"Unique identifier of the Sync Root."},"installationId":{"type":"string","description":"Unique identifier of the top-level installation that owns this Sync Root."},"target":{"$ref":"#/components/schemas/GitSyncInstallationTarget"},"defaultMergeAuthorityPolicy":{"type":"string","enum":["provider","gitbook"],"description":"System responsible for completing merges by default for this Sync Root."},"status":{"type":"string","enum":["active","disabled"]},"createdAt":{"$ref":"#/components/schemas/Timestamp"},"updatedAt":{"$ref":"#/components/schemas/Timestamp"}},"required":["object","id","installationId","target","defaultMergeAuthorityPolicy","status","createdAt","updatedAt"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}},"required":["code","message"]}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[401]},"message":{"type":"string"}},"required":["code","message"]}}}}}},"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"integer","format":"int32","enum":[404]},"message":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/git/installations/{installationId}":{"patch":{"operationId":"updateGitSyncInstallationById","summary":"Update a Git Sync installation configuration","description":"Updates the installation configuration, then queues a sync operation using the new settings.\nA `git` priority queues an import from the selected repository and branch into GitBook; a\n`gitbook` priority queues an export from GitBook to the repository. Site imports require a\n`gitbook-docs.yaml` file at the configured project directory and return a conflict without saving or\nqueuing the sync when the file is missing. Updates to GitLab instances also return\na conflict if their settings changed while the update was being prepared; reload the\ninstallation before retrying.\n","tags":["git"],"parameters":[{"$ref":"#/components/parameters/installationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/GitSyncInstallationSetup"},{"type":"object","properties":{"childInstallationProjectDirectories":{"type":"object","description":"Project directories keyed by child installation ID for a site installation.","additionalProperties":{"type":"string"}}}}]}}}},"responses":{"200":{"description":"Git Sync installation was updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitSyncInstallation"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"},"409":{"description":"The site Git Sync configuration is missing, or GitLab settings changed while the update was being prepared","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","details"],"properties":{"type":{"type":"string","enum":["missing_site_git_sync_config"]},"details":{"type":"object","required":["path","branch","prompt"],"properties":{"path":{"type":"string","description":"Repository-relative path where `gitbook-docs.yaml` is required."},"branch":{"type":"string","description":"Repository branch where `gitbook-docs.yaml` is required."},"prompt":{"type":"string","description":"Prompt for a coding agent to create and commit the missing file."}}}}}}}]}]}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/developers/gitbook-api/api-reference/git/update-a-git-sync-installation-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
