> ## 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 Image to GitHub

> Links an image to a GitHub repository, so a push to its branch rebuilds the image.

The repository must be in one of your GitHub App installations. A public repository outside them can be built once with [Create Image](https://docs.vertracloud.app/api-reference/endpoint/images/create.md), but it can only be linked after you install the GitHub App on it. A push to the linked branch rebuilds the image exactly like a manual rebuild, with the repository at that branch as the build context. Pushes are skipped while a build of the image is already running. Rebuilds from GitHub never restart applications.

Only the image's owner can link it. In a workspace, a member gets `403` even with permission to manage the workspace's apps, because the link uses the owner's GitHub App installations.

Needs the `images:write` scope when called with an API key.

**image\_id** `string` *required*

The image ID.

**workspace\_id** `string`

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

**repository** `string` *required*

The repository, as `owner/name`.

**branch** `string`

The branch that triggers the rebuild. Optional: without it, the repository's default branch is used (`main`, `master` or whatever the repository sets).

### Response

**response** `object`

The image.

**Toggle object**

**id** `string`

The image ID.

**name** `string`

The image name.

**description** `string | null`

The image description (free text, up to 128 characters), or `null` when it has none.

**owner** `string`

`account` for your own images, `system` for images provided by the platform (these cannot be changed or deleted).

**status** `string`

State of the latest build: `building`, `success` or `failed`. A failed rebuild does not change the current version: apps keep running the last good one.

**error** `string | null`

Readable reason of the latest failed build, or `null`.

**digest** `string | null`

Digest (`sha256:...`) of the current version, or `null` while no build has succeeded.

**uncompressed\_bytes** `integer | null`

Size of the current version, uncompressed, in bytes.

**layer\_count** `integer | null`

Number of layers of the current version.

**apps** `object[]`

The applications created from this image. Each has `id`, `name`, `version_id` (the image version it runs, or `null`) and `outdated` (`true` when the image has a newer version; the app moves to it on the next restart or deploy you ask for).

**github** `object | null`

The linked GitHub repository and branch (`repository` as `owner/name`, `branch`), or `null` when the image is not linked.

**current\_version\_id** `string | null`

The current version of the image, or `null` while no build has succeeded.

**created\_at** `string`

When the image was created.

**updated\_at** `string`

When the image was last updated.

```json Response theme={null}
{
  "response": {
    "id": "img-abc123def456",
    "name": "my-api",
    "description": null,
    "owner": "account",
    "status": "success",
    "error": null,
    "digest": "sha256:3f1c0a9d5b7e2c4a8d6f1b0e9c3a7d5f2b4e6a8c0d1f3b5a7c9e2d4f6a8b0c1e",
    "uncompressed_bytes": 187432960,
    "layer_count": 9,
    "apps": [
      {
        "id": "app-abc123def456",
        "name": "my-api-prod",
        "version_id": "imgv-111aaa222bbb",
        "outdated": false
      }
    ],
    "github": { "repository": "acme/my-api", "branch": "main" },
    "current_version_id": "imgv-111aaa222bbb",
    "created_at": "2026-10-23T14:02:00Z",
    "updated_at": "2026-10-23T14:09:00Z"
  }
}
```

### 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 required scope (`403`).
* `ACCESS_DENIED`: You are not the owner of the image, or it is a platform image (`403`).
* `IMAGE_NOT_FOUND`: The image does not exist or you cannot access it (`404`).
* `VALIDATION_ERROR`: The body failed validation, for example a `repository` that is not `owner/name` (`400`).
* `INSTALLATION_NOT_FOUND`: The repository is not in one of your GitHub App installations (`404`).
* `REPO_ALREADY_LINKED`: The repository is already linked to another image or application (`409`).
* `FETCH_ZIP_ERROR`: GitHub could not be reached or was limiting requests while the repository was checked (`502`). Try again in a few minutes.
* `PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES`: The plan does not include custom Docker images (`403`).
* `INTERNAL_SERVER_ERROR`: Unexpected failure (`500`).

```json Error Response theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "Repository must be owner/name",
  "path": "repository"
}
```


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