# Verificación de la configuración de compilación Las verificaciones de compilación (build checks) son una característica introducida en Dockerfile 1.8. Te permiten validar tu configuración de compilación y realizar una serie de verificaciones antes de ejecutar tu compilación. Piensa en ello como una forma avanzada de análisis estático (linting) para tu Dockerfile y opciones de compilación, o un modo de prueba (dry-run) para las compilaciones. Puedes encontrar la lista de verificaciones disponibles y una descripción de cada una en la [referencia de verificaciones de compilación](/reference/build-checks/). ## Cómo funcionan las verificaciones de compilación Normalmente, cuando ejecutas una compilación, Docker ejecuta los pasos de compilación en tu Dockerfile y las opciones de compilación tal como se especifican. Con las verificaciones de compilación, en lugar de ejecutar los pasos de compilación, Docker verifica el Dockerfile y las opciones que proporcionas e informa sobre cualquier problema que detecte. Las verificaciones de compilación son útiles para: - Validar tu Dockerfile y las opciones de compilación antes de ejecutar una compilación. - Asegurar que tu Dockerfile y las opciones de compilación estén actualizados con las últimas buenas prácticas. - Identificar posibles problemas o antipatrones en tu Dockerfile y opciones de compilación. > [!TIP] > > Para mejorar el análisis estático, la navegación de código y el escaneo de vulnerabilidades de tus Dockerfiles en Visual Studio Code, > consulta la extensión [Docker DX](https://marketplace.visualstudio.com/items?itemName=docker.docker). ## Compilar con verificaciones Las verificaciones de compilación son compatibles con: - Buildx versión 0.15.0 y posteriores - [docker/build-push-action](https://github.com/docker/build-push-action) versión 6.6.0 y posteriores - [docker/bake-action](https://github.com/docker/bake-action) versión 5.6.0 y posteriores Invocar una compilación ejecuta las verificaciones por defecto y muestra cualquier violación en la salida de compilación. Por ejemplo, el siguiente comando compila la imagen y ejecuta las verificaciones: ```console $ docker build . [+] Building 3.5s (11/11) FINISHED ... 1 warning found (use --debug to expand): - Lint Rule 'JSONArgsRecommended': JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 7) ``` En este ejemplo, la compilación se ejecutó con éxito, pero se informó una advertencia [JSONArgsRecommended](/reference/build-checks/json-args-recommended/), ya que las instrucciones `CMD` deben usar la sintaxis de array JSON. Con GitHub Actions, las verificaciones se muestran en la vista de diferencias (diff) de las pull requests. ```yaml name: Build and push Docker images on: push: jobs: build: runs-on: ubuntu-latest steps: - name: Build and push uses: docker/build-push-action@v7 ``` ![GitHub Actions build check annotations](/build/images/gha-check-annotations.png) ### Salida más detallada Las advertencias de verificación para un `docker build` normal muestran un mensaje conciso que contiene el nombre de la regla, el mensaje y el número de línea en el Dockerfile de donde se originó el problema. Si deseas ver información más detallada sobre las verificaciones, puedes usar la bandera (flag) `--debug`. Por ejemplo: ```console $ docker --debug build . [+] Building 3.5s (11/11) FINISHED ... 1 warning found: - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 4) JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals More info: https://docs-docker.esdocu.com/go/dockerfile/rule/json-args-recommended/ Dockerfile:4 -------------------- 2 | 3 | FROM alpine 4 | >>> CMD echo "Hello, world!" 5 | -------------------- ``` Con la bandera `--debug`, la salida incluye un enlace a la documentación para la verificación y un fragmento del Dockerfile donde se encontró el problema. ## Verificar una compilación sin compilar Para ejecutar verificaciones de compilación sin realizar la compilación real, puedes usar el comando `docker build` como lo harías normalmente, pero añadiendo la bandera `--check`. Aquí tienes un ejemplo: ```console $ docker build --check . ``` En lugar de ejecutar los pasos de compilación, este comando solo ejecuta las verificaciones e informa sobre cualquier problema que encuentre. Si hay algún problema, se informará en la salida. Por ejemplo: ```text {title="Output with --check"} [+] Building 1.5s (5/5) FINISHED => [internal] connecting to local controller => [internal] load build definition from Dockerfile => => transferring dockerfile: 253B => [internal] load metadata for docker.io/library/node:22 => [auth] library/node:pull token for registry-1.docker.io => [internal] load .dockerignore => => transferring context: 50B JSONArgsRecommended - https://docs-docker.esdocu.com/go/dockerfile/rule/json-args-recommended/ JSON arguments recommended for ENTRYPOINT/CMD to prevent unintended behavior related to OS signals Dockerfile:7 -------------------- 5 | 6 | COPY index.js . 7 | >>> CMD node index.js 8 | -------------------- ``` Esta salida con `--check` muestra el [mensaje detallado](#salida-más-detallada) de la verificación. A diferencia de una compilación normal, si se informa alguna violación al usar la bandera `--check`, el comando finaliza con un código de estado distinto de cero. ## Fallar la compilación por violaciones de verificación Las violaciones de verificación para las compilaciones se informan como advertencias, con código de salida 0, por defecto. Puedes configurar Docker para que falle la compilación cuando se informen violaciones, utilizando una directiva `check=error=true` en tu Dockerfile. Esto hará que la compilación falle con un error después de que se ejecuten las verificaciones de compilación, antes de que se ejecute la compilación real. ```dockerfile {title=Dockerfile,linenos=true,hl_lines=2} # syntax=docker/dockerfile:1 # check=error=true FROM alpine CMD echo "Hello, world!" ``` Sin la directiva `# check=error=true`, esta compilación se completaría con un código de salida 0. Sin embargo, con la directiva, la violación de la verificación de compilación da como resultado un código de salida distinto de cero: ```console $ docker build . [+] Building 1.5s (5/5) FINISHED ... 1 warning found (use --debug to expand): - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended behavior related to OS signals (line 5) Dockerfile:1 -------------------- 1 | >>> # syntax=docker/dockerfile:1 2 | # check=error=true 3 | -------------------- ERROR: lint violation found for rules: JSONArgsRecommended $ echo $? 1 ``` También puedes establecer la directiva de error en la CLI pasando el argumento de compilación `BUILDKIT_DOCKERFILE_CHECK`: ```console $ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=error=true" . ``` ## Omitir verificaciones Por defecto, todas las verificaciones se ejecutan cuando compilas una imagen. Si deseas omitir verificaciones específicas, puedes usar la directiva `check=skip` en tu Dockerfile. El parámetro `skip` acepta una lista de IDs de verificación separados por comas que deseas omitir. Por ejemplo: ```dockerfile {title=Dockerfile} # syntax=docker/dockerfile:1 # check=skip=JSONArgsRecommended,StageNameCasing FROM alpine AS BASE_STAGE CMD echo "Hello, world!" ``` Compilar este Dockerfile no genera violaciones de verificación. También puedes omitir verificaciones pasando el argumento de compilación `BUILDKIT_DOCKERFILE_CHECK` con una lista de IDs de verificación separados por comas. Por ejemplo: ```console $ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing" . ``` Para omitir todas las verificaciones, utiliza el parámetro `skip=all`: ```dockerfile {title=Dockerfile} # syntax=docker/dockerfile:1 # check=skip=all ``` ## Combinar parámetros de error y omisión para directivas de verificación Para omitir verificaciones específicas y al mismo tiempo fallar en caso de violaciones, pasa los parámetros `skip` y `error` separados por un punto y coma (`;`) a la directiva `check` en tu Dockerfile o en un argumento de compilación. Por ejemplo: ```dockerfile {title=Dockerfile} # syntax=docker/dockerfile:1 # check=skip=JSONArgsRecommended,StageNameCasing;error=true ``` ```console {title="Build argument"} $ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=skip=JSONArgsRecommended,StageNameCasing;error=true" . ``` ## Verificaciones experimentales Antes de que las verificaciones pasen a ser estables, pueden estar disponibles como verificaciones experimentales. Las verificaciones experimentales están deshabilitadas por defecto. Para ver la lista de verificaciones experimentales disponibles, consulta la [referencia de verificaciones de compilación](/reference/build-checks/). Para habilitar todas las verificaciones experimentales, establece el argumento de compilación `BUILDKIT_DOCKERFILE_CHECK` en `experimental=all`: ```console $ docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" . ``` También puedes habilitar verificaciones experimentales en tu Dockerfile usando la directiva `check`: ```dockerfile {title=Dockerfile} # syntax=docker/dockerfile:1 # check=experimental=all ``` Para habilitar selectivamente las verificaciones experimentales, puedes pasar una lista de los IDs de verificación que deseas habilitar, ya sea en la directiva `check` de tu Dockerfile o como un argumento de compilación. Por ejemplo: ```dockerfile {title=Dockerfile} # syntax=docker/dockerfile:1 # check=experimental=JSONArgsRecommended,StageNameCasing ``` Ten en cuenta que la directiva `experimental` tiene prioridad sobre la directiva `skip`, lo que significa que las verificaciones experimentales se ejecutarán independientemente de la directiva `skip` que hayas establecido. Por ejemplo, si estableces `skip=all` y habilitas las verificaciones experimentales, las verificaciones experimentales se seguirán ejecutando: ```dockerfile {title=Dockerfile} # syntax=docker/dockerfile:1 # check=skip=all;experimental=all ``` ## Lectura adicional Para obtener más información sobre el uso de verificaciones de compilación, consulta: - [Referencia de verificaciones de compilación](/reference/build-checks/) - [Validación de la configuración de compilación con GitHub Actions](/build/ci/github-actions/checks/)