Skip to main content
POST
Create Image
Available on Enterprise 28, Enterprise 30 and Enterprise 32. The request is multipart/form-data. The build context has two mutually exclusive sources: file, or github_repository (the branch is optional). It must have a file named exactly Dockerfile at its root; a single wrapping folder is accepted. .env* files are removed from the context and .dockerignore is respected. The Dockerfile is never rewritten. See Custom Docker images for the rules. Needs the images:write scope when called with an API key. Check a Dockerfile first with Check Dockerfile.
string
required
The image name: 1 to 50 characters, unique among your images.
string
Optional free-text description, up to 128 characters. An empty value means no description. You can change it later with Update Image.
file
The build context: a ZIP file, up to 100 MB. Absent when the source is GitHub.
string
Alternative to file: the GitHub repository to build from, as owner/name.
  • A repository in one of your GitHub App installations is linked to the image: a push to the branch rebuilds it.
  • A public repository outside your installations is built once, with no link (github is null in the response). To get automatic rebuilds, install the GitHub App on the repository and call Link Image to GitHub.
  • A private or nonexistent repository outside your installations fails with INSTALLATION_NOT_FOUND.
string
The branch of github_repository to build from. Optional: without it, the repository’s default branch is used (main, master or whatever the repository sets). When the repository is linked, this is also the branch whose pushes rebuild the image. A branch that does not exist fails with INSTALLATION_NOT_FOUND.
string
The workspace that will own the image.

Response

object
The image. Creation is asynchronous: the response is 202 Accepted with status: "building". Follow it with Get Image or the build logs until status is success or failed.

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).
  • VALIDATION_ERROR: The multipart body failed validation, for example a github_repository that is not owner/name (400).
  • PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES: The plan does not include custom Docker images (403).
  • MAX_IMAGES_REACHED: The plan’s limit of 20 images was reached; images in any state count (403).
  • DOCKERFILE_NOT_FOUND: There is no file named exactly Dockerfile at the root of the context (400).
  • DOCKERFILE_REFUSED: The Dockerfile has a refused instruction; details lists the findings (400). See Check Dockerfile.
  • IMAGE_CONTEXT_TOO_LARGE: The build context is over a limit: more than 100 MB compressed, more than 512 MB uncompressed, more than 50,000 entries, or a Dockerfile larger than 1 MB (413).
  • IMAGE_BUILDER_UNAVAILABLE: No host can build images right now; try again later (503).
  • INSTALLATION_NOT_FOUND: The repository is private or does not exist, and it is not in your GitHub App installations; or the branch does not exist (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 fetched (502). Try again in a few minutes.
  • INTERNAL_SERVER_ERROR: Unexpected failure (500).