Saltar al contenido

¿Qué es un artefacto en GitHub Actions?

Última actualización

Un artefacto en GitHub Actions es un archivo o carpeta que una ejecución de workflow guarda para que otros jobs posteriores, o personas, puedan utilizarlo. Los artefactos habituales son los resultados de compilación, los informes de pruebas, los archivos de cobertura y las capturas de pantalla de las pruebas end-to-end fallidas.

Cómo funciona

Para subir artefactos se usa actions/upload-artifact, y para descargarlos, actions/download-artifact. Como cada job se ejecuta en un runner nuevo, los artefactos son la forma estándar de pasar los resultados de una compilación de un job al siguiente. Además, los artefactos subidos aparecen en la página de la ejecución del workflow, donde cualquiera con acceso puede descargarlos en un archivo zip.

Los artefactos pertenecen a una única ejecución de workflow y caducan tras un periodo de retención. El valor predeterminado se configura a nivel de repositorio u organización y puede sustituirse en cada subida con retention-days.

Desde la versión 4 de las acciones de artefactos, los nombres de los artefactos deben ser únicos dentro de una ejecución. Subir dos veces con el mismo nombre falla, salvo que se establezca overwrite. Por eso, los jobs de matriz necesitan un nombre que incluya el valor de la matriz.

Ejemplo

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/
          retention-days: 7
          if-no-files-found: error

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      - run: ls dist

Añada if: always() o if: failure() al paso de subida para conservar los informes de las ejecuciones fallidas, que es cuando más los necesita.

Artefactos frente a cachés

ArtefactoCaché
FinalidadResultado de esta ejecuciónAcelerar las ejecuciones futuras
AlcanceUna ejecución de workflowCompartida entre ejecuciones y ramas mediante clave
RetenciónSe define por ejecuciónSe elimina si no se usa o si supera el límite de tamaño
InmutablePor nombre dentro de una ejecuciónPor clave de caché

Si quiere guardar node_modules para reutilizarlo la semana que viene, use una caché. Si quiere pasar un binario al job de despliegue, use un artefacto. Consulte la caché en GitHub Actions.

Errores comunes

  • Subir demasiado. Los artefactos grandes ralentizan los jobs y consumen la cuota de almacenamiento. Suba solo lo necesario.
  • Colisiones de nombres en jobs de matriz. Incluya ${{ matrix.os }} o el número de fragmento en el nombre y, después, combine los resultados con actions/upload-artifact/merge.
  • Secretos en los artefactos. Cualquiera que pueda leer la ejecución puede descargarlos. Nunca suba archivos .env ni credenciales.
  • Usar artefactos como caché. Se vuelven a subir en cada ejecución y son más lentos que una caché adecuada.
  • Olvidar la retención. Los valores predeterminados largos consumen almacenamiento sin que se note.

Preguntas frecuentes

¿Cuánto tiempo se conservan los artefactos?

Durante el periodo de retención configurado, por defecto 90 días en repositorios públicos, salvo que se cambie. Consulte la configuración de su repositorio para ver el valor actual.

¿Se pueden compartir artefactos entre workflows?

Sí, con download-artifact usando el run-id y un token, o mediante la API REST. Dentro de una misma ejecución es más sencillo.

¿Los artefactos tienen coste?

El almacenamiento que supere la cantidad incluida en su plan se factura. Consulte la página de facturación de GitHub para conocer las tarifas vigentes.