> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vertracloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Link a Private Template to GitHub

> Links a private template to a GitHub repository with the manifest at its root, so each push to the branch publishes a version.

This call links a private template to a GitHub repository and answers with the template. The repository must have `vertracloud.template.yaml` at the root of the branch and be in one of your GitHub App installations; it cannot be linked to another owner's template. Every push to the branch then publishes one version, with the commit message as the changelog and the `README.md` of the root as the documentation. The code of a service comes from the folder in its `source.path`, or from the repository without the manifest.

A push does not raise the version by itself: raise the `version` of the manifest in the commit. A push that cannot become a version is skipped (the manifest has an older version, is invalid, or the code holds a secret). Fix it and push again. Pushes to other branches are ignored.

Needs the `templates:write` scope when called with an API key. Only the owner of the template can link it, because the link uses the owner's GitHub App installations; in a workspace, a member gets `403`.

**template\_id** `string` *required*

The template ID.

**workspace\_id** `string`

If the template belongs to a workspace, the workspace's ID.

**repository** `string` *required*

The repository, as `owner/name`.

**branch** `string`

The branch that publishes versions. Without it, the default branch of the repository.

```bash cURL theme={null}
curl -X PUT https://api.vertracloud.app/v1/templates/tpl-abc123def456/github \
  -H "Authorization: Bearer $VERTRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "repository": "acme/support-bot-template", "branch": "main" }'
```

### Response

The template object of [Create a Private Template](https://docs.vertracloud.app/api-reference/endpoint/templates/create.md), now with `github` set to the linked repository.

**response** `object`

The template.

**Toggle object**

**github** `object | null`

The link: `repository` (`owner/name`) and `branch`.

**id** `string`

The template ID. The other fields are the ones listed in [Create a Private Template](https://docs.vertracloud.app/api-reference/endpoint/templates/create.md).

```json Response theme={null}
{
  "response": {
    "id": "tpl-abc123def456",
    "slug": "support-bot",
    "origin": "private",
    "github": { "repository": "acme/support-bot-template", "branch": "main" }
  }
}
```

### Error Responses

**code** `string`

The error code indicating the reason for the failure. Possible values:

* `API_KEY_SCOPE_DENIED`: The API key does not have the `templates:write` scope (`403`).
* `TEMPLATE_NOT_FOUND`: The template does not exist or is not yours (`404`).
* `INSTALLATION_NOT_FOUND`: The repository or the branch is not in your GitHub App installations (`404`).
* `TEMPLATE_GITHUB_MANIFEST_NOT_FOUND`: There is no `vertracloud.template.yaml` at the root of the branch.
* `REPO_ALREADY_LINKED`: The repository is already linked to another owner's template, an image or an application (`409`).
* `WORKSPACE_OWNER_ONLY`: Only the workspace owner links its templates.

```json Error Response theme={null}
{
  "code": "TEMPLATE_GITHUB_MANIFEST_NOT_FOUND"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.