Skip to main content
PUT
Link Image to GitHub
The repository must be in one of your GitHub App installations. A public repository outside them can be built once with Create Image, 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.
string
required
The image ID.
string
If the image belongs to a workspace, the workspace’s ID.
string
required
The repository, as owner/name.
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

object
The image.

Error Responses

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).