Una guía práctica para construir flujos de trabajo GitHub más inteligentes

Tengo una larga experiencia con los flujos de trabajo de GitHub, pero no hasta el punto de que pueda afirmar que soy un experto. Sin embargo, recientemente desarrollé un nuevo flujo de trabajo, y me impulsó a escribir este post. ¿Qué son los flujos de trabajo de GitHub? Un flujo de trabajo es un proceso automatizado configurable que ejecutará una o más tareas. Los flujos de trabajo se definen por un archivo YAML que se registra en su repositorio y se ejecutan cuando se desencadena por un evento en su repositorio, o se pueden desencadenar manualmente o en un horario definido. Los flujos de trabajo se definen en el directorio .github/workflows en un repositorio. Un repositorio puede tener múltiples flujos de trabajo, cada uno de los cuales puede realizar un conjunto diferente de tareas, como: Construcción y pruebas de solicitudes de arrastre Despliegue su aplicación cada vez que se crea una versión Añadir una etiqueta cada vez que se abre un nuevo tema Sobre los flujos de trabajo Un flujo de trabajo es un proceso automatizado configurable que ejecutará una o más tareas. Los flujos de trabajo se definen por un archivo YAML que se registra en su repositorio y se ejecutan cuando se desencadena por un evento en su repositorio, o se pueden desencadenar manualmente o en un horario definido. Los flujos de trabajo están definidos en la Un repositorio puede tener múltiples flujos de trabajo, cada uno de los cuales puede realizar un conjunto diferente de tareas, como: .github/workflows Construcción y pruebas de solicitudes de arrastre Despliegue su aplicación cada vez que se crea una versión Añadir una etiqueta cada vez que se abre un nuevo tema Sobre los flujos de trabajo Como tal, un flujo de trabajo es comparable a un trabajo de Jenkins, implementado en YAML en lugar de XML. , en contraste con una configuración de trabajo de Jenkins heredada. No parece mucho, pero permite el uso de enfoques de gestión de código fuente, incluyendo la versión y el rollback. Hace años, trabajé para un cliente cuyo equipo de DevOps implementó un enfoque basado en muñecas para reconstruir los trabajos de Jenkins para que la configuración de muñecas pudiera almacenarse en Git. stored inside the code repository Tenga en cuenta que GitHub estaba bastante tarde para la fiesta. Antes de implementar flujos de trabajo, usé un servicio de terceros llamado Me cambié principalmente porque Travis se pagó y secundariamente porque los flujos de trabajo son parte nativa de GitHub. Travis que Tipo : • Se llaman Las acciones de GitHub son completamente diferentes. Use the correct semantics Flujos de trabajo de GitHub Acciones de GitHub Los flujos de trabajo de GitHub están compuestos por que se componen de Pasos de referencia Comandos, y un par de parámetros opcionales, incluyendo un nombre. Trabajos Pasos Corriendo jobs: metrics: runs-on: my-image #1 steps: - name: Install dependencies via Poetry #2 run: poetry install #3 Imagen OCI en la que se ejecuta el flujo de trabajo Nombre de paso Paso de mando GitHub Acciones son componentes reutilizables que ofrecen alternativas a repetir el mismo comando una y otra vez. Una acción es un conjunto predefinido y reutilizable de tareas o código que realiza tareas específicas dentro de un flujo de trabajo, reduciendo la cantidad de código repetitivo que escribe en sus archivos de flujo de trabajo. Descarga de tu repositorio Git desde GitHub Configurar la cadena de herramientas correcta para su entorno de construcción Configurar la autenticación para su proveedor de nube Puede escribir sus propias acciones, o puede encontrar acciones para usar en sus flujos de trabajo en el mercado de GitHub. Por ejemplo, en lugar de ejecutar el checkout de git, puede usar la acción de checkout. GitHub Acción Una acción es un conjunto predefinido y reutilizable de tareas o código que realiza tareas específicas dentro de un flujo de trabajo, reduciendo la cantidad de código repetitivo que escribe en sus archivos de flujo de trabajo. Descarga de tu repositorio Git desde GitHub Configurar la cadena de herramientas correcta para su entorno de construcción Configurar la autenticación para su proveedor de nube Puede escribir sus propias acciones, o puede encontrar acciones para usar en sus flujos de trabajo en el mercado de GitHub. Por ejemplo, en lugar de ejecutar el checkout de git, puede usar la acción de checkout. - - - GitHub Acción jobs: metrics: runs-on: my-image steps: - uses: actions/checkout@v5 #1 with: #2 fetch-depth: 0 submodules: recursive Referencia a la acción de GitHub Parámetros de acción Soy un gran fan de no reinventar la rueda.GitHub Actions juega un gran papel en eso. Tipo : cuando sea posible. Prefer GitHub Actions over ad-hoc commands Elegir la acción correcta Los hosts de GitHub Marketplace Las acciones se listan por categorías. Puedes filtrar por tipo de creador y ordenar por popularidad. Muchas acciones Al elegir una acción, debe ejercer el mismo cuidado que al traer a cualquier otra adicción.Aquí hay un par de criterios para ayudarle: Vendor: prefer verified creators License type: Open Source vs. closed source. With the former, check the exact terms; the Apache v2 license is very different from the GPL one. Pricing for commercial actions Check the source code repository of actions that display it and check the following information: ** Inception date ** Activity, including the repartition of commits per committer, the number of open issues, the mean time for fixing issues, etc. ** Documentation (reference material, tutorials, how-to guides, and explanations) Community, if any Support Tipo : Be as careful in choosing a GitHub Action as in choosing any other dependency. Conozca sus acciones Como el consejo anterior, este se deriva de uno más genérico: hablo de experiencia. estaba desarrollando un flujo de trabajo para empaquetar una aplicación Java. Estaba utilizando el flujo de trabajo, y el trabajo tenía que descargar las dependencias en cada ejecución. jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-java@v4 #1 with: distribution: temurin java-version: 21 - uses: actions/cache@v4 #2 with: path: ~/.m2/repository #3 key: ${{ platform }}-maven--${{ hashFiles('**/pom.xml') }} #4 restore-keys: | ${{ runner.os }}-maven- #4 Instalación de JDK Configurar un cache. El cache es genérico y puede almacenar archivos a través de ejes. Cache el repositorio local de Maven Dependencias de caché. La clave utiliza el sistema operativo del corredor, que no cambia, y el hash del POM. Por lo tanto, el paso crea un nuevo caché cada vez que el POM cambia. Sin embargo, al leer la documentación, me di cuenta de que podría lograr lo mismo de una manera mucho más sencilla: La acción tiene una funcionalidad integrada para el caché y la restauración de dependencias. Utiliza el kit de herramientas/cache bajo capó para el caché de dependencias pero requiere menos configuraciones de configuración. Los gestores de paquetes compatibles son gradle, maven y sbt. El formato de la clave de caché utilizada es setup-java-${plattform }}-${ packageManager }}-${ fileHash }}, donde el hash se basa en los siguientes archivos: MAVEN: * / POM.xml Dependencias de paquetes de caché La acción tiene una funcionalidad integrada para el caché y la restauración de dependencias. Utiliza el kit de herramientas/cache bajo capó para el caché de dependencias pero requiere menos configuraciones de configuración. Los gestores de paquetes compatibles son gradle, maven y sbt. El formato de la clave de caché utilizada es setup-java-${plattform }}-${ packageManager }}-${ fileHash }}, donde el hash se basa en los siguientes archivos: MAVEN: * / POM.xml Dependencias de paquetes de caché Por lo tanto, he reemplazado el fragmento anterior por el siguiente: jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - uses: actions/setup-java@v4 with: distribution: temurin java-version: 21 cache: maven #1 Este es el Tipo : Pasar una hora en la documentación puede ayudarle a ahorrar días de esfuerzo. Thoroughly read the documentation of actions. Pin su versión de dependencia Esta sección también toma consejos genéricos y los aplica a la versión de los flujos de trabajo de GitHub. Puede que hayas notado el en los fragmentos anteriores. En el momento de esta escritura, señala que A medida que pasa el tiempo, apunta a la última versión, con versiones de diferentes bibliotecas. Puede causar un fallo durante la ejecución del flujo de trabajo, o peor, cambiar la salida de maneras que no notaría hasta que sea demasiado tarde. [Todas las imágenes disponibles] runs-on: ubuntu-latest ubuntu-24.04 https://github.com/actions/runner-images La versión de Actions funciona de manera diferente, ya que apunta a la referencia de un repo de GitHub: una etiqueta o un SHA de comisión. Mientras que la imagen OCI está en manos de GitHub, la acción es responsabilidad de su proveedor. Esto significa que cualquier persona con derechos de comisión podría cambiar el contenido de una etiqueta subyacente. Pin a un compromiso. must jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903 #1 Pin a un compromiso específico 💡 Consejo: Tome la seguridad en serio y pin actions to a specific commit. Utilice el resumen del trabajo Cada uno de sus pasos de flujo de trabajo probablemente saca un montón de registros. En un flujo de trabajo regular, la cantidad total de líneas de registro puede ser bastante enorme. Algunos de ellos pueden ser útiles, algunos de ellos pueden no ser, pero porque solo hay una salida estándar y error estándar, todo termina en el mismo lugar. , el número de pruebas que se ejecutan o el porcentaje de cobertura de código, en caso de que no envíe estos datos a otra parte. GitHub hace que sea sencillo agregar los datos que desee en el resumen del trabajo. El E.G. Puede usar resúmenes de tareas para mostrar y agrupar contenido único, como resúmenes de resultados de pruebas, para que alguien que ve el resultado de una ejecución de flujo de trabajo no tenga que ir a los registros para ver información importante relacionada con la ejecución, como fallas. Los resúmenes de trabajo soportan Markdown con sabor de GitHub, y puede agregar el contenido de Markdown por un paso al archivo de entorno GITHUB_STEP_SUMMARY. GITHUB_STEP_SUMMARY es único para cada paso en un trabajo. Añadir un resumen de trabajo Puede usar resúmenes de tareas para mostrar y agrupar contenido único, como resúmenes de resultados de pruebas, para que alguien que ve el resultado de una ejecución de flujo de trabajo no tenga que ir a los registros para ver información importante relacionada con la ejecución, como fallas. Los resúmenes de trabajo soportan Markdown con sabor de GitHub, y puede agregar el contenido de Markdown por un paso al archivo de entorno GITHUB_STEP_SUMMARY. GITHUB_STEP_SUMMARY es único para cada paso en un trabajo. Añadir un resumen de trabajo Aquí está a Más sobre Apache Arrow: muestras - name: Show inputs run: | echo "upload_artifacts: ${{ inputs.upload_artifacts }}" >> $GITHUB_STEP_SUMMARY echo "schedule: ${{ github.event.schedule }}" >> $GITHUB_STEP_SUMMARY echo "ref: ${{ github.ref }}" >> $GITHUB_STEP_SUMMARY El es : Resultado Tipo : Mejorar la experiencia de los desarrolladores. Use GitHub job summary Comprender el ciclo de vida de los flujos de trabajo Los flujos de trabajo ejecutan los pasos de forma secuencial. Un paso fallido cancela todos los pasos restantes y el flujo de trabajo termina en un En el ejemplo anterior, significa que no obtendremos ningún resumen de pruebas en absoluto si alguno de los pasos posteriores falla. Condiciones . Failure if Puede utilizar las siguientes funciones de verificación de estado como expresiones en si condicionales. Se aplica una verificación de estado predeterminada de éxito() a menos que incluya una de estas funciones. - Funciones de verificación de estado Puede utilizar las siguientes funciones de verificación de estado como expresiones en Condiciones: Verificación del estado de defecto se aplica a menos que incluya una de estas funciones. if success() - Funciones de verificación de estado GitHub utiliza por defecto, pero las opciones incluyen , de , y . success() always() cancelled() failure() - name: Show inputs if: ${{ always() }} #1 run: | echo "upload_artifacts: ${{ inputs.upload_artifacts }}" >> $GITHUB_STEP_SUMMARY echo "schedule: ${{ github.event.schedule }}" >> $GITHUB_STEP_SUMMARY echo "ref: ${{ github.ref }}" >> $GITHUB_STEP_SUMMARY Siempre ejecute el paso, independientemente de si los pasos anteriores fueron exitosos o no. Imagínese la siguiente secuencia: - name: Step that may fail run: whatever - name: Execute unit tests run: ./mvnw -B test #1 - name: Test Summary if: ${{ always() }} uses: test-summary/action@31493c7 #2 Las pruebas de unidad que se ejecutan también generan informes JUnit Utilice los informes JUnit generados para escribir un resumen de pasos Si el primer paso falla, el resumen se ejecuta independientemente de si se ejecutaron las pruebas. Si no lo hicieran, fracasaría. Para evitar esto, debemos refinar la condición más adelante para que el paso de resumen solo se ejecute si el paso de prueba de la unidad lo hizo. - name: Step that may fail run: whatever - name: Execute unit tests id: test #1 run: ./mvnw -B test - name: Test Summary if: ${{ always() && steps.test.conclusion == 'success'}} #2 uses: test-summary/action@31493c7 Configurar la ID del paso Corre sólo si el paso de prueba se ejecuta con éxito Es sólo un ejemplo simple, pero ofrece opciones interesantes. Tipo : Utilízalo a tu ventaja. Know workflows' lifecycle Prueba local Muchas organizaciones aplican estrictas reglas de GitHub.La más extendida es que no se puede empujar a : cada compromiso debe pasar por una solicitud de retiro. Si bien tiene sentido para los proyectos establecidos, evita que los proyectos comiencen a repetirse rápidamente mientras se mantiene el historial de los compromisos. En el contexto de desarrollar flujos de trabajo de GitHub, es definitivamente crippling. master Llega el proyecto de ley: “Piensa globalmente, actúa localmente” Executa tus acciones de GitHub localmente! ¿Por qué quieres hacer esto? Dos razones: - Rather than having to commit/push every time you want to test out the changes you are making to your files (or for any changes to embedded GitHub actions), you can use act to run the actions locally. The environment variables and filesystem are all configured to match what GitHub provides. Fast Feedback .github/workflows/ - I love make. However, I also hate repeating myself. With , you can use the GitHub Actions defined in your to replace your ! Local Task Runner act .github/workflows/ Makefile - Introducción a la acción “Piensa globalmente, actúa localmente” Executa tus acciones de GitHub localmente! ¿Por qué quieres hacer esto? Dos razones: Feedback rápido - En lugar de tener que comprometerse / empujar cada vez que desee probar los cambios que está haciendo en sus .github / flujos de trabajo / archivos (o para cualquier cambio en las acciones de GitHub incorporadas), puede usar act para ejecutar las acciones localmente. las variables del entorno y el sistema de archivos están configurados para coincidir con lo que ofrece GitHub. Local Task Runner - me encanta hacer. Sin embargo, también odio repetirme. Con acción, puedes usar las acciones de GitHub definidas en tu .github/workflows/ para reemplazar tu Makefile! - Introducción a la acción tiene una integración CLI de GitHub que desencadena el flujo de trabajo de acuerdo con el evento correcto. act gh act push Aquí está la salida cuando las imágenes y las acciones ya se han descargado: INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' [workflow.yml/test] ⭐ Run Set up job [workflow.yml/test] 🚀 Start image=catthehacker/ubuntu:act-22.04 [workflow.yml/test] 🐳 docker pull image=catthehacker/ubuntu:act-22.04 platform= username= forcePull=true [workflow.yml/test] 🐳 docker create image=catthehacker/ubuntu:act-22.04 platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" [workflow.yml/test] 🐳 docker run image=catthehacker/ubuntu:act-22.04 platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host" [workflow.yml/test] 🐳 docker exec cmd=[node --no-warnings -e console.log(process.execPath)] user= workdir= [workflow.yml/test] ✅ Success - Set up job [workflow.yml/test] ☁ git clone 'https://github.com/actions/setup-java' # ref=v4 [workflow.yml/test] ⭐ Run Main actions/checkout@v4 [workflow.yml/test] 🐳 docker cp src=/Users/nico/projects/act-sample/. dst=/Users/nico/projects/act-sample [workflow.yml/test] ✅ Success - Main actions/checkout@v4 [9.211777902s] [workflow.yml/test] ⭐ Run Main Setup JDK [workflow.yml/test] 🐳 docker cp src=/home/nico/.cache/act/actions-setup-java@v4/ dst=/var/run/act/actions/actions-setup-java@v4/ [workflow.yml/test] 🐳 docker exec cmd=[/opt/acttoolcache/node/18.20.8/x64/bin/node /var/run/act/actions/actions-setup-java@v4/dist/setup/index.js] user= workdir= [workflow.yml/test] ❓ ::group::Installed distributions | Resolved Java 21.0.8+9.0.LTS from tool-cache | Setting Java 21.0.8+9.0.LTS as the default | Creating toolchains.xml for JDK version 21 from temurin | Writing to /root/.m2/toolchains.xml | | Java configuration: | Distribution: temurin | Version: 21.0.8+9.0.LTS | Path: /opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64 | [workflow.yml/test] ❓ ::endgroup:: [workflow.yml/test] ❓ add-matcher /run/act/actions/actions-setup-java@v4/.github/java.json | Creating settings.xml with server-id: github | Writing to /root/.m2/settings.xml [workflow.yml/test] ⚙ *** | Cache Size: ~50 MB (52710428 B) | [command]/usr/bin/tar -xf /tmp/c8ef4803-85c1-4867-ac2d-442dbce79755/cache.tzst -P -C /Users/nico/projects/act-sample --use-compress-program unzstd | Cache restored successfully | Cache restored from key: setup-java-linux-x64-maven-ef0e54e9035c18b60db7ea0af5e2f0c4cc5445dd6a2a2a672b91e14f14e7e4c2 [workflow.yml/test] ✅ Success - Main Setup JDK [2.514565962s] [workflow.yml/test] ⚙ ::set-env:: JAVA_HOME=/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64 [workflow.yml/test] ⚙ ::set-env:: JAVA_HOME_21_X64=/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64 [workflow.yml/test] ⚙ ::set-output:: distribution=Temurin-Hotspot [workflow.yml/test] ⚙ ::set-output:: path=/opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64 [workflow.yml/test] ⚙ ::set-output:: version=21.0.8+9.0.LTS [workflow.yml/test] ⚙ ::set-output:: cache-hit=false [workflow.yml/test] ⚙ ::add-path:: /opt/hostedtoolcache/Java_Temurin-Hotspot_jdk/21.0.8-9.0.LTS/x64/bin [workflow.yml/test] ⭐ Run Main Run "fast" tests [workflow.yml/test] 🐳 docker exec cmd=[bash -e /var/run/act/workflow/2] user= workdir= | [INFO] Scanning for projects... | [INFO] | [INFO] ---- ----- | [INFO] Building act-sample 1.0-SNAPSHOT | [INFO] from pom.xml | [INFO] ------------------------[ jar ]------------------------- | [INFO] | [INFO] --- resources:3.3.1:resources (default-resources) @ act-sample --- | [INFO] Copying 1 resource from src/main/resources to target/classes | [INFO] | [INFO] --- compiler:3.14.0:compile (default-compile) @ act-sample --- | [INFO] Recompiling the module because of changed source code. | [INFO] Compiling 5 source files with javac [debug target 21] to target/classes | [INFO] | [INFO] --- resources:3.3.1:testResources (default-testResources) @ act-sample --- | [INFO] Copying 2 resources from src/test/resources to target/test-classes | [INFO] | [INFO] --- compiler:3.14.0:testCompile (default-testCompile) @ act-sample --- | [INFO] Recompiling the module because of changed dependency. | [INFO] Compiling 1 source file with javac [debug target 21] to target/test-classes | [INFO] | [INFO] --- surefire:3.2.5:test (default-test) @ act-sample --- | [INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider | [INFO] | [INFO] ------------------------------------------ | [INFO] T E S T S | [INFO] ------------------------------------------ | [INFO] Running ch.frankel.blog.ActSampleTest | [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.120 s -- in ch.frankel.blog.ActSampleTest | [INFO] | [INFO] Results: | [INFO] | [INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0 | [INFO] | [INFO] ------------------------------------------------------ | [INFO] BUILD SUCCESS | [INFO] ------------------------------------------------------ | [INFO] Total time: 3.318 s | [INFO] Finished at: 2025-08-22T10:26:29Z | [INFO] ------------------------------------------------------ [workflow.yml/test] ✅ Success - Main Run "fast" tests [20.920776212s] [workflow.yml/test] ⭐ Run Post Setup JDK [workflow.yml/test] 🐳 docker exec cmd=[/opt/acttoolcache/node/18.20.8/x64/bin/node /var/run/act/actions/actions-setup-java@v4/dist/cleanup/index.js] user= workdir= | [command]/usr/bin/tar --posix -cf cache.tzst --exclude cache.tzst -P -C /Users/nico/projects/act-sample --files-from manifest.txt --use-compress-program zstdmt | Cache Size: ~50 MB (52701753 B) | Cache saved successfully | Cache saved with the key: setup-java-Linux-x64-maven-ef0e54e9035c18b60db7ea0af5e2f0c4cc5445dd6a2a2a672b91e14f14e7e4c2 [workflow.yml/test] ✅ Success - Post Setup JDK [1.01412383s] [workflow.yml/test] ⭐ Run Complete job [workflow.yml/test] Cleaning up container for job test [workflow.yml/test] ✅ Success - Complete job [workflow.yml/test] 🏁 Job succeeded Podría escribir un par de artículos sobre Te dejo para leer la documentación. act Tipo : Reduce el tiempo del ciclo de feedback. Test your workflows locally Resumen Usar la semántica correcta, diferenciar entre flujos de trabajo y acciones. Prefiero las acciones de GitHub sobre los comandos ad hoc. Sea tan cuidadoso al elegir una Acción de GitHub como al elegir cualquier otra dependencia. Lee cuidadosamente la documentación de cada acción que utilice. Pin acciones a un compromiso específico. Utilice el resumen de trabajo de GitHub para mejorar la experiencia del desarrollador. Conocer el ciclo de vida de los flujos de trabajo. Pruebe sus flujos de trabajo localmente. To go further: Sobre los flujos de trabajo GitHub Acción GitHub Mercado de Acción Imágenes de Runner Añadir un resumen de trabajo Funciones de verificación de estado Introducción al Acto