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": {
"id": "tpl-abc123def456",
"slug": "support-bot",
"origin": "private",
"github": { "repository": "acme/support-bot-template", "branch": "main" }
}
}
Templates
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.
PUT
/
v1
/
templates
/
{template_id}
/
github
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": {
"id": "tpl-abc123def456",
"slug": "support-bot",
"origin": "private",
"github": { "repository": "acme/support-bot-template", "branch": "main" }
}
}
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.
string
required
The template ID.
string
If the template belongs to a workspace, the workspace’s ID.
string
required
The repository, as
owner/name.string
The branch that publishes versions. Without it, the default branch of the repository.
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, now withgithub set to the linked repository.
object
The template.
Show Toggle object
Show Toggle object
object | null
The link:
repository (owner/name) and branch.string
The template ID. The other fields are the ones listed in Create a Private Template.
{
"response": {
"id": "tpl-abc123def456",
"slug": "support-bot",
"origin": "private",
"github": { "repository": "acme/support-bot-template", "branch": "main" }
}
}
Error Responses
string
The error code indicating the reason for the failure. Possible values:
API_KEY_SCOPE_DENIED: The API key does not have thetemplates:writescope (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 novertracloud.template.yamlat 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.
{
"code": "TEMPLATE_GITHUB_MANIFEST_NOT_FOUND"
}
Last modified on October 28, 2026