Saltar al contenido principal
POST
Crear una imagen
Disponible en Enterprise 28, Enterprise 30 y Enterprise 32. La petición es multipart/form-data. El contexto de build tiene dos fuentes mutuamente excluyentes: file o github_repository (la rama es opcional). Debe tener un archivo llamado exactamente Dockerfile en su raíz; se acepta una única carpeta contenedora. Los archivos .env* se eliminan del contexto y se respeta .dockerignore. El Dockerfile nunca se reescribe. Consulta Imágenes Docker personalizadas para ver las reglas. Necesita el ámbito images:write cuando se llama con una clave de API. Comprueba antes un Dockerfile con Comprobar Dockerfile.
string
requerido
El nombre de la imagen: de 1 a 50 caracteres, único entre tus imágenes.
string
Descripción opcional en texto libre, de hasta 128 caracteres. Un valor vacío significa sin descripción. Puedes cambiarla después con Actualizar imagen.
file
El contexto de build: un archivo ZIP de hasta 100 MB. No aparece cuando la fuente es GitHub.
string
Alternativa a file: el repositorio de GitHub desde el que construir, como owner/name.
  • Un repositorio de una de tus instalaciones de la GitHub App queda vinculado a la imagen: un push a la rama la reconstruye.
  • Un repositorio público fuera de tus instalaciones se construye una sola vez, sin vínculo (github es null en la respuesta). Para obtener reconstrucciones automáticas, instala la GitHub App en el repositorio y llama a Vincular imagen a GitHub.
  • Un repositorio privado o inexistente fuera de tus instalaciones falla con INSTALLATION_NOT_FOUND.
string
La rama de github_repository desde la que construir. Es opcional: si no se indica, se usa la rama por defecto del repositorio (main, master o la que establezca el repositorio). Cuando el repositorio está vinculado, esta es también la rama cuyos pushes reconstruyen la imagen. Una rama que no existe falla con INSTALLATION_NOT_FOUND.
string
El workspace que será propietario de la imagen.

Respuesta

object
La imagen. La creación es asíncrona: la respuesta es 202 Accepted con status: "building". Haz seguimiento con Obtener imagen o con los logs del build hasta que status sea success o failed.

Respuestas de error

string
El código de error que indica el motivo del fallo. Valores posibles:
  • API_KEY_SCOPE_DENIED: La clave de API no tiene el ámbito requerido (403).
  • VALIDATION_ERROR: El cuerpo multipart no superó la validación, por ejemplo un github_repository que no es owner/name (400).
  • PLAN_DOES_NOT_SUPPORT_CUSTOM_IMAGES: El plan no incluye imágenes Docker personalizadas (403).
  • MAX_IMAGES_REACHED: Se alcanzó el límite de 20 imágenes del plan; cuentan las imágenes en cualquier estado (403).
  • DOCKERFILE_NOT_FOUND: No hay ningún archivo llamado exactamente Dockerfile en la raíz del contexto (400).
  • DOCKERFILE_REFUSED: El Dockerfile tiene una instrucción rechazada; details enumera los hallazgos (400). Consulta Comprobar Dockerfile.
  • IMAGE_CONTEXT_TOO_LARGE: El contexto de build supera un límite: más de 100 MB comprimido, más de 512 MB sin comprimir, más de 50.000 entradas, o un Dockerfile mayor de 1 MB (413).
  • IMAGE_BUILDER_UNAVAILABLE: Ningún host puede construir imágenes en este momento; vuelve a intentarlo más tarde (503).
  • INSTALLATION_NOT_FOUND: El repositorio es privado o no existe, y no está entre tus instalaciones de la GitHub App; o la rama no existe (404).
  • REPO_ALREADY_LINKED: El repositorio ya está vinculado a otra imagen o aplicación (409).
  • FETCH_ZIP_ERROR: No se pudo contactar con GitHub, o GitHub limitaba las peticiones mientras se descargaba el repositorio (502). Vuelve a intentarlo en unos minutos.
  • INTERNAL_SERVER_ERROR: Fallo inesperado (500).
Última modificación el 28 de octubre de 2026