Pular para o conteúdo principal
POST
Criar imagem
Disponível nos planos Enterprise 28, Enterprise 30 e Enterprise 32. A requisição é multipart/form-data. O contexto de build tem duas fontes mutuamente exclusivas: file, ou github_repository (o branch é opcional). Ele precisa ter um arquivo chamado exatamente Dockerfile na sua raiz; uma pasta única que o envolva é aceita. Arquivos .env* são removidos do contexto e o .dockerignore é respeitado. O Dockerfile nunca é reescrito. Veja Imagens Docker personalizadas para as regras. Exige o escopo images:write quando chamada com uma chave de API. Verifique antes um Dockerfile com Verificar Dockerfile.
string
obrigatório
O nome da imagem: de 1 a 50 caracteres, único entre as suas imagens.
string
Descrição opcional em texto livre, de até 128 caracteres. Um valor vazio significa sem descrição. Você pode alterá-la depois com Atualizar imagem.
file
O contexto de build: um arquivo ZIP, de até 100 MB. Ausente quando a fonte é o GitHub.
string
Alternativa a file: o repositório do GitHub a partir do qual fazer o build, no formato owner/name.
  • Um repositório de uma das suas instalações do GitHub App fica vinculado à imagem: um push para o branch refaz o build dela.
  • Um repositório público fora das suas instalações é construído uma vez, sem vínculo (github é null na resposta). Para ter rebuilds automáticos, instale o GitHub App no repositório e chame Vincular imagem ao GitHub.
  • Um repositório privado ou inexistente fora das suas instalações falha com INSTALLATION_NOT_FOUND.
string
O branch de github_repository a partir do qual fazer o build. Opcional: sem ele, usa-se o branch padrão do repositório (main, master ou o que o repositório definir). Quando o repositório está vinculado, este também é o branch cujos pushes refazem o build da imagem. Um branch que não existe falha com INSTALLATION_NOT_FOUND.
string
O workspace que será dono da imagem.

Resposta

object
A imagem. A criação é assíncrona: a resposta é 202 Accepted com status: "building". Acompanhe com Obter imagem ou com os logs do build até que status seja success ou failed.

Respostas de erro

string
O código de erro que indica o motivo da falha. Valores possíveis:
  • API_KEY_SCOPE_DENIED: A chave de API não tem o escopo exigido (403).
  • VALIDATION_ERROR: O body multipart falhou na validação, por exemplo um github_repository que não está no formato owner/name (400).
  • PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES: O plano não inclui imagens Docker personalizadas (403).
  • MAX_IMAGES_REACHED: Foi atingido o limite de 20 imagens do plano; imagens em qualquer estado contam (403).
  • DOCKERFILE_NOT_FOUND: Não existe um arquivo chamado exatamente Dockerfile na raiz do contexto (400).
  • DOCKERFILE_REFUSED: O Dockerfile tem uma instrução recusada; details lista os achados (400). Veja Verificar Dockerfile.
  • IMAGE_CONTEXT_TOO_LARGE: O contexto de build passou de um limite: mais de 100 MB compactado, mais de 512 MB descompactado, mais de 50.000 entradas, ou um Dockerfile maior que 1 MB (413).
  • IMAGE_BUILDER_UNAVAILABLE: Nenhum host pode fazer build de imagens agora; tente novamente mais tarde (503).
  • INSTALLATION_NOT_FOUND: O repositório é privado ou não existe, e não está nas suas instalações do GitHub App; ou o branch não existe (404).
  • REPO_ALREADY_LINKED: O repositório já está vinculado a outra imagem ou aplicação (409).
  • FETCH_ZIP_ERROR: Não foi possível acessar o GitHub, ou ele estava limitando requisições enquanto o repositório era buscado (502). Tente novamente em alguns minutos.
  • INTERNAL_SERVER_ERROR: Falha inesperada (500).
Última modificação em 28 de outubro de 2026