Capítulo 4. Trabajar con flujos de trabajo
Este trabajo se ha traducido utilizando IA. Agradecemos tus opiniones y comentarios: translation-feedback@oreilly.com
Como seguramente ya habrás deducido, los flujos de trabajo son el núcleo del uso de las Acciones de GitHub. He tratado algunos de los aspectos básicos para entender los flujos de trabajo. Pero también necesitas ser capaz de crearlos, ejecutarlos y monitorearlos fácilmente para comprobar su éxito o fracaso. Este capítulo se centrará en ese tipo de actividades.
En primer lugar, examinaré algunas de las funciones que ofrece GitHub para crear flujos de trabajo a partir de los iniciales. Luego te mostraré cómo editar flujos de trabajo en la interfaz de GitHub y cómo impulsar cambios en esa misma interfaz con operaciones como commits y pull requests. Por el camino, aprenderás a navegar por los resultados de las ejecuciones de flujos de trabajo y a monitorizar la ejecución de un flujo de trabajo.
Por último, te mostraré cómo utilizar las extensiones actualizadas GitHub Actions VS Code para crear y editar flujos de trabajo, así como para gestionar y monitorizar tus ejecuciones, desde Visual Studio Code (VS Code).
Lo primero es una guía para crear un flujo de trabajo inicial en un repositorio.
Crear el primer flujo de trabajo en un repositorio
Supón que tienes un repositorio en el que no has utilizado Acciones de GitHub y quieres empezar. ¿Cómo puedes empezar? Para empezar, veamos un ejemplo de proyecto sencillo en GitHub. La Figura 4-1 muestra un repositorio básico con un par de archivos.
Si haces clic en en la pestaña Acciones del menú superior en un repositorio sin flujos de trabajo existentes, se te presentará una página de introducción a las acciones. (Si lo deseas, también puedes llegar a esta página visitando https:<tu ruta al repositorio de github>/actions/new).
Si tienes un repositorio con un tipo concreto de código (Go, Java, etc.), el flujo de trabajo sugerido por GitHub lo tendrá en cuenta. La Figura 4-2 muestra la página de inicio de un repositorio que contiene código Go. GitHub ha sugerido acciones Go en Sugerido para este repositorio en lugar de una genérica.
Hay cuatro formas de empezar con un nuevo flujo de trabajo en un repositorio cuando no hay ninguno existente:
- Haz clic en el enlace Configura tú mismo un flujo de trabajo, justo encima de la acción Buscar flujos de trabajo.
- Pulsa el botón Configurar para el flujo de trabajo sugerido bajo el título Sugerido para este repositorio.
- Desplázate y elige uno de los otros flujos de trabajo sugeridos, y haz clic en el botón Configurar del apropiado.
- Crea un archivo de flujo de trabajo fuera de GitHub y añádelo a un subdirectorio .github/workflows en el repositorio.
Elegir cualquiera de las dos primeras opciones coloca el código de un flujo de trabajo básico en el editor de la interfaz web. Para el nombre del archivo del flujo de trabajo, empieza con una ruta que incluya .github/workflows y un campo de nombre que refleje el flujo de trabajo sugerido. Ese campo puede editarse para tener el nombre que quieras. Puedes retroceder y editar la ruta. Pero como ya se ha comentado en el Capítulo 1, los flujos de trabajo deben vivir en el subdirectorio .github/workflows dentro de un proyecto.
Mover un archivo dentro de un repositorio
Como consejo general, editar un archivo en la interfaz de GitHub y luego modificar la ruta del directorio en el área del nombre (mediante retroceso y tecleando) es una forma fácil de cambiar la ubicación y mover el archivo dentro del repositorio.
La parte derecha de la ventana muestra las Acciones Destacadas. Si tu repositorio contiene código de un tipo concreto, esta ventana mostrará un conjunto de acciones relacionadas. (Pero siempre puedes buscar otras acciones mediante el cuadro de búsqueda de esa ventana). La Figura 4-3 muestra un ejemplo de flujo de trabajo rellenado en el editor tras elegir la plantilla Flujo de trabajo simple y hacer clic en su botón Configurar.
El código completo de este flujo de trabajo inicial se muestra aquí. A continuación te explicaré lo que hace este código:
1 # This is a basic workflow to help you get started with Actions 2 3 name: CI 4 5 # Controls when the workflow will run 6 7 on: 8 # Triggers the workflow on push or pull request events for main 9 push: 10 branches: [ main ] 11 pull_request: 12 branches: [ main ] 13 14 # Allows you to run this workflow manually from the Actions tab 15 workflow_dispatch: 16 17 # A workflow run is made up of one or more jobs 18 jobs: 19 # This workflow contains a single job called "build" 20 build: 21 # The type of runner that the job will run on 22 runs-on: ubuntu-latest 23 24 # Steps are a sequence of tasks executed as part of a job 25 steps: 26 # Checks-out your repository under $GITHUB_WORKSPACE 27 - uses: actions/checkout@v3 28 29 # Runs a single command using the runners shell 30 - name: Run a one-line script 31 run: echo Hello, world! 32 33 # Runs a set of commands using the runners shell 34 - name: Run a multi-line script 35 run: | 36 echo Add other actions to build, 37 echo test, and deploy your project.
Observando el listado, puedes identificar los componentes de un flujo de trabajo de los que se habla en los Capítulos 2 y 3.
A partir de la línea 7, la sección on define cuándo se invocará este flujo de trabajo. En este caso, una solicitud push o pull a la rama principal hará que se active el flujo de trabajo. Este flujo de trabajo también incluye una cláusula workflow_dispatch en la línea 15. Una vez que el código se haya confirmado en la rama por defecto, GitHub añadirá un botón en la pantalla Acciones para darte la opción de ejecutar este flujo de trabajo manualmente. (El uso del activador workflow_dispatch se describe más adelante en este capítulo y en detalle en el Capítulo 12).
workflow_dispatch y ramas
Si un flujo de trabajo incluye la cláusula flujo_trabajo_despacho, debe existir una instancia del archivo de flujo de trabajo con la cláusula en la rama por defecto (normalmente la principal) para que el botón aparezca en la interfaz.
La sección de tareas comienza en la línea 18. Sólo hay un trabajo en este flujo de trabajo: el de construcción. Al principio del trabajo, tienes la cláusula "se ejecuta en" (línea 22), que describe el tipo de sistema en el que se ejecutará/puede ejecutar este flujo de trabajo. En este caso, es en un sistema que ejecuta la distribución Linux Ubuntu.
Luego tienes la sección pasos en la tarea de compilación (a partir de la línea 25). Como ya hemos dicho, los pasos pueden invocar acciones predefinidas o ejecutar comandos del sistema operativo a través del intérprete de comandos. En este flujo de trabajo inicial, tienes ambos tipos de pasos. En la línea 27, el primer paso utiliza la acción de GitHub checkout@v3 para comprobar el contenido de este repositorio cuando se ejecuta el flujo de trabajo. Los pasos que siguen, en las líneas 29-37, ejecutan sencillos comandos del shell que se hacen eco del texto a través de la cláusula run
.
Después de crear o editar un flujo de trabajo, es necesario confirmarlo en el repositorio. La siguiente sección te mostrará cómo puedes hacerlo sin salir de la interfaz web de GitHub.
Comprometiendo el flujo de trabajo inicial
Cuando codificas inicialmente un flujo de trabajo en el editor web de GitHub, aún no forma parte de la base de código. Igual que si estuvieras editando un nuevo archivo localmente, necesitas confirmarlo en el repositorio. Antes de hacerlo, puedes cambiar el nombre del flujo de trabajo, si quieres, editando la línea del archivo que empieza por nombre: (línea 3 en este ejemplo).
Cuando hayas terminado de editar, simplemente pulsa el botón Confirmar cambios, situado en la parte superior derecha de la pantalla del editor. La Figura 4-4 muestra el botón. En este caso, he dejado el flujo de trabajo inicial con el nombre CI, pero he renombrado el propio archivo del flujo de trabajo a basic.yml.
Editar la ruta del archivo de flujo de trabajo
Como se ha indicado anteriormente, podrías retroceder en el área de la ruta y cambiar el directorio donde se almacena el flujo de trabajo. Pero no lo hagas. Los flujos de trabajo deben estar en el directorio .github/workflows de un repositorio para funcionar con el marco de acciones.
Tras hacer clic en el botón Confirmar cambios, aparece un diálogo emergente para obtener más información sobre la confirmación(Figura 4-5). Esto incluye la descripción y la elección de si realizar el cambio mediante una simple confirmación en la rama actual o crear una nueva rama y realizar el cambio mediante una solicitud de extracción. Aquí estoy confirmando directamente en la rama actual, pero mostraré el ejemplo de la solicitud de extracción más adelante en el capítulo. En este caso, puedes añadir algunos comentarios si lo deseas, dejar el valor por defecto como Confirmar directamente en la rama <actual> y hacer clic en el botón Confirmar cambios.
Una vez realizada la confirmación, el archivo se añade a la base de código del repositorio. Ahora, si pasas a la pestaña Acciones del menú superior, el flujo de trabajo se estará ejecutando (o se habrá ejecutado). ¿Por qué? Cuando se hizo el commit a main, que cumplía los criterios especificados por el flujo de trabajo en la sección on:
# Triggers the workflow on push or pull request events but # only for the main branch push: branches: [ main ] pull request: branches: [ main ]
La Figura 4-6 muestra la primera ejecución de este flujo de trabajo.
Esta es una buena oportunidad para desglosar lo que te muestra esta pantalla y cómo navegar por ella.
Empezando por el lado izquierdo hay una lista de los flujos de trabajo asociados a este repositorio. El elemento seleccionado en esta lista filtrará qué ejecuciones del flujo de trabajo se muestran en la parte derecha. Por defecto, el elemento Todos los flujos de trabajo está seleccionado, y las ejecuciones de todos los flujos de trabajo se muestran en la lista. Si, en la lista de la izquierda, seleccionas un flujo de trabajo concreto, eso filtrará la lista de la derecha para mostrar información sólo sobre el flujo de trabajo seleccionado. (La interfaz se muestra en la Figura 4-7.)
Como sólo hay un flujo de trabajo con una única ejecución, esto no tiene mucho interés. La única pieza adicional que se muestra ahora con el flujo de trabajo específico seleccionado es el cuadro con la línea "Este flujo de trabajo tiene un activador de evento workflow_dispatch
" y el botón Ejecutar flujo de trabajo. La razón por la que veo esto ahora es porque he seleccionado este flujo de trabajo a la izquierda (en lugar de la selección Todos los flujos de trabajo ). Y este flujo de trabajo incluye el siguiente código en la sección on
del archivo del flujo de trabajo en la rama por defecto:
on: ... # Allows you to run this workflow manually from the Actions tab workflow_dispatch:
Esta es una instancia de un tipo de activador workflow_dispatch
. Muestra un botón que puede iniciar otra ejecución del flujo de trabajo manualmente. Cuando lo pulsas, se te presenta un pequeño cuadro de diálogo que te permite seleccionar una rama desde la que ejecutarlo y opciones adicionales si están definidas (ver Capítulo 8). Si se invoca, el flujo de trabajo se ejecuta y se añade otra ejecución a la lista, como se muestra en la Figura 4-8. Esta invocación directa de un flujo de trabajo puede ser útil para la creación de prototipos, la depuración y otros casos en los que no siempre quieras tener que provocar un evento en GitHub para activar la ejecución.
Si miras atentamente las descripciones de estas ejecuciones (bajo la fila con la marca de verificación en un círculo a la izquierda), puedes leer información sobre qué evento inició cada ejecución. Están ordenadas según la hora en que se ejecutaron, empezando por la última ejecución en la parte superior.
Después de una ejecución, puede que quieras volver atrás y hacer algunas ediciones en el flujo de trabajo para corregir o añadir algo. Podrías clonar el repositorio y editar el archivo localmente. O puedes volver a la sección Código del repositorio en GitHub, seleccionar un archivo y editarlo desde allí.
La interfaz de Acciones de esta página ofrece otro acceso directo para ir directamente al código del flujo de trabajo: hacer clic en el pequeño nombre de archivo YAML que hay bajo el título del flujo de trabajo, en la parte superior. La Figura 4-9 muestra el elemento del que estoy hablando. En este caso, el enlace/nombre es basic.yml.
Si haces clic en ese enlace, accederás a una vista del archivo en el editor web. En la parte superior derecha de la barra gris, encima del archivo, hay un pequeño conjunto de iconos. Busca el que parece un lápiz. Puedes hacer clic en este icono para editar el archivo directamente en el navegador(Figura 4-10).
Al hacer clic en el icono del lápiz aparece una interfaz básica de edición del archivo. Además de la posibilidad de cambiar el nombre y la ruta del archivo (mediante el cuadro de entrada con la ruta del archivo encima del código), también hay opciones para cambiar la indentación y el estilo de envoltura (parte superior derecha del área de edición), una pestaña para ver vistas previas de los cambios, y botones arriba para confirmar o cancelar los cambios. Todo esto se muestra en la Figura 4-11.
Para mostrar cómo funciona la edición, puedo hacer algunos cambios sencillos para alterar este flujo de trabajo y tener dos trabajos en lugar de uno. En primer lugar, cambiaré la descripción y el nombre del trabajo existente. Esto no es estrictamente necesario, pero encaja mejor dados los otros cambios realizados:
# This workflow contains a single job called "build" build:
a:
# This job checks out code from the repo checkout:
Más abajo, antes del primer paso run
, añadiré un par de líneas para convertir los pasos restantes en sus propios trabajos. Este requiere añadir lo siguiente:
- Un nombre para el trabajo
- Una cláusula
runs-on
para decir qué tipo de sistema utilizar para la ejecución - Una cláusula
steps
para indicar dónde comienzan los pasos para el nuevo trabajo
Estas líneas se insertan (con un comentario) a partir de la línea 28 original. Cuando hagas esto, es importante que tengas mucho cuidado para que coincida con el estilo de indentación esperado, ya que esto es YAML:
# This job does the core processing process: # The type of runner that the job will run on runs-on: ubuntu-latest steps:
La sección de trabajos del flujo de trabajo tiene ahora este aspecto:
jobs: # This job checks out code from the repo checkout: # The type of runner that the job will run on runs-on: ubuntu-latest # Steps represent a sequence of tasks that will be executed as part of the job steps: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v3 process: # The type of runner that the job will run on runs-on: ubuntu-latest steps: # Runs a single command using the runners shell - name: Run a one-line script run: echo Hello, world! # Runs a set of commands using the runners shell - name: Run a multi-line script run: | echo Add other actions to build, echo test, and deploy your project.
Puedes utilizar la pestaña Vista previa para ver cómodamente lo que ha cambiado en este archivo antes de confirmarlo. La Figura 4-13 muestra la visualización del código tras seleccionar esa pestaña.
Ahora los cambios están listos para ser confirmados. Para ello, pulsa el botón Confirmar cambios. El cuadro de diálogo que aparece es el mismo que antes. Esta vez, voy a seleccionar la opción de confirmar mediante pull request. Y le daré a la nueva rama el nombre de parche-1. La Figura 4-14 muestra el cuadro de diálogo completado.
Tras hacer clic en el botón Proponer cambios, aparece el cuadro de diálogo estándar Abrir una pull request, que se muestra en la Figura 4-15. En la barra gris superior, ya está configurado para comparar la rama patch-1 con la principal. Y puede fusionar los cambios sin conflictos. Cuando esté listo, el siguiente paso es hacer clic en el botón Crear pull request.
Una vez creada la solicitud de extracción, GitHub ejecutará cualquier comprobación predefinida asociada al repositorio y a la rama. En este caso, las comprobaciones que se ejecutan son las tareas de cualquier flujo de trabajo que se active por una solicitud de extracción en esta rama. Esto equivale a las tareas de comprobación y procesamiento que se acaban de definir en el archivo de flujo de trabajo basic.yaml. Puedes ver cómo se ejecutan mientras se procesa inicialmente la solicitud de extracción. Y también puedes verlos una vez finalizado el procesamiento inicial haciendo clic en el enlace Mostrar todas las comprobaciones, situado a la derecha de la fila Todas las comprobaciones han sido superadas. La Figura 4-16 muestra el conjunto de comprobaciones después de que se hayan ejecutado.
Si haces clic en el enlace Detalles al final de cada fila de , accederás a una pantalla para esa ejecución. En la Figura 4-17, puedes ver los trabajos del flujo de trabajo listados a la izquierda y un área a la derecha que enumera todos los pasos que debían realizarse para el trabajo con la salida de la ejecución de cada paso. Esto también incluye pasos implícitos, gestionados por GitHub, necesarios para que el trabajo se ejecute, como Configurar trabajo.
Cada paso puede ampliarse para mostrar más detalles. Y algunas líneas listadas en los pasos también pueden expandirse para mostrar la salida colapsada o detalles de la ejecución. (Habrá más que decir sobre esta pantalla cuando profundicemos en los ejecutores en el Capítulo 5 y en la depuración/resolución de problemas en el Capítulo 10).
Otra forma de llegar a los detalles
Puedes ver esta misma pantalla de detalles si seleccionas la pestaña Solicitudes de extracción en la parte superior de la pantalla del repositorio, seleccionas la solicitud de extracción abierta y, a continuación, seleccionas la pestaña Comprobaciones. (Ver Figura 4-18.)
Si vuelves a la pestaña principal Acciones, puedes encontrar detalles de todas las ejecuciones de tu flujo de trabajo. Yo sólo tengo un flujo de trabajo, pero seguiré adelante y lo seleccionaré específicamente. A la derecha, como se muestra en la Figura 4-19, puedes ver todas las ejecuciones del flujo de trabajo seleccionado.
La última ejecución de este flujo de trabajo está en la fila de la parte superior de la lista. Al hacer clic en el mensaje de confirmación Actualizar basic.yaml, la vista cambia para mostrar la lista de tareas del flujo de trabajo, junto con el tiempo que tardaron en completarse y si tuvieron éxito o no. En la Figura 4-20, el éxito se indica mediante los círculos con marcas de verificación. Si haces clic en cualquier nombre de un trabajo de esta pantalla, accederás a una vista de los detalles del paso. Es la misma vista que obtienes al hacer clic en el enlace de detalles de la sección de comprobaciones de la pantalla de solicitud de extracción.
En la parte superior derecha de la pantalla mostrada en la Figura 4-20, también puedes ver el botón Reejecutar todos los trabajos. Al lado hay un botón que se puede expandir para guiarte en la creación de una insignia de estado, así como una opción para borrar registros. ("Crear una insignia de estado" explica más sobre cómo crear una insignia de estado).
Ahora que se han completado todas las comprobaciones previas a la fusión, estás listo para fusionar el código y completar la solicitud de extracción.
Volver al Pull Request
Puedes volver fácilmente a la solicitud de extracción seleccionando Solicitudes de extracción en el menú superior (la línea que empieza por < > Código) y luego seleccionando la solicitud de extracción de la lista que se muestra. O simplemente puedes utilizar la URL de tu proyecto de GitHub que termine con pull/1 (suponiendo que sea la primera pull request de tu repositorio).
Para completar la fusión, haz clic en el botón Fusionar pull request y luego en el siguiente botón, Confirmar fusión. Verás el diálogo habitual que indica que la pull request se ha fusionado y cerrado (y puedes eliminar la rama si quieres).
En este punto, si haces clic en el menú Acciones de la parte superior, podrás ver la ejecución más reciente del flujo de trabajo generado por la solicitud de extracción(Figura 4-23) con el mensaje de confirmación generado automáticamente.
Antes de abandonar esta pantalla, hay otras funciones menores que merece la pena conocer. En la fila de cualquier ejecución, puedes seleccionar el botón ... al final para borrar una ejecución o ir directamente al archivo de flujo de trabajo(Figura 4-24).
Además, hay opciones de filtrado en la parte superior de la lista de ejecuciones. Puedes seleccionar la lista desplegable de una de ellas y filtrar para ver sólo las ejecuciones que coincidan con tu selección. La Figura 4-25 muestra el filtrado de la lista de ejecuciones por la rama parche-1 que se utilizó en la pull request que se acaba de completar.
Uso de la extensión de acciones de GitHub de VS Code
Si prefieres trabajar dentro de un IDE, existe una extensión GitHub Actions disponible para VS Code que te permite crear y editar flujos de trabajo, así como gestionar y monitorizar ejecuciones. Incluye funciones como linting y completado de código, y cuenta con el apoyo oficial de GitHub. (La extensión era originalmente un proyecto comunitario utilizado principalmente para el monitoreo).
Si estás familiarizado con VS Code, puedes instalar la extensión fácilmente mediante la búsqueda de acciones en el IDE de VS Code(Figura 4-26) o a través del enlace de la extensión Acciones de GitHub de VS Code.
A continuación, puedes seleccionar un repositorio y clonarlo en VS Code. En algún momento, se te pedirá que inicies sesión en GitHub y se te solicitará que permitas que la extensión acceda a tus repositorios de GitHub(Figura 4-27).
Tras la instalación y la autorización, tendrás una nueva vista en VS Code para las Acciones de GitHub. Si ya tienes flujos de trabajo y ejecuciones de flujos de trabajo dentro de tu repositorio, la vista te los mostrará(Figura 4-28).
Dentro de la lista de FLUJOS DE TRABAJO, al seleccionar una ejecución de flujo de trabajo por su número, aparece un icono de globo terráqueo a la derecha. Si haces clic en el icono del globo, podrás abrir la ejecución del flujo de trabajo en el navegador de la interfaz de acciones estándar. Del mismo modo, seleccionar un trabajo en la lista hace que aparezca un icono de lista a la derecha. Seleccionarlo te permite ver los registros asociados a ese trabajo(Figura 4-29).
Si estás consultando un registro , la vista EXPLORADOR ofrece una sección de ESQUEMA en la que puedes hacer clic para desplazarte a puntos concretos del registro más fácilmente(Figura 4-30).
La extensión también entiende el esquema del flujo de trabajo y puede proporcionar ayuda contextual al crear/editar archivos de flujo de trabajo. Por ejemplo, si pasas el ratón por encima de una palabra clave, puedes obtener ventanas emergentes con información útil sobre el contexto(Figura 4-31).
La extensión te notificará a los problemas de sintaxis de al crear/editar archivos de flujo de trabajo(Figura 4-32).
Otras funciones interesantes de incluyen la finalización del código de los elementos cuando puede determinar el conjunto de opciones disponibles(Figura 4-33) y la posibilidad de obtener un enlace rápido al código de una acción pasando el ratón por encima de su declaración de usos en el flujo de trabajo(Figura 4-34).
Conclusión
En este capítulo, he presentado la interfaz web de GitHub para trabajar con acciones y flujos de trabajo. La funcionalidad proporcionada te permite crear y editar fácilmente flujos de trabajo sin tener que salir del navegador. También puedes ejecutar los flujos de trabajo y ver cada ejecución a medida que sucede. Las ejecuciones anteriores se almacenan para que puedas revisarlas.
Las Acciones de GitHub proporcionan un conjunto de flujos de trabajo iniciales y de referencia para facilitar la creación de un flujo de trabajo inicial. GitHub mirará cualquier código existente en tu repositorio y, si puede, hará sugerencias para un flujo de trabajo inicial útil. Los flujos de trabajo de inicio y de referencia son un buen punto de partida cuando necesitas un flujo de trabajo para un nuevo repositorio.
Los flujos de trabajo en ejecución pueden activarse en respuesta a eventos estándar de GitHub, pero también pueden activarse manualmente si están configurados para el envío de flujos de trabajo. Tras la ejecución, GitHub registra información sobre la ejecución, y puedes profundizar en el registro de la ejecución para ver lo que ocurrió realmente y obtener los detalles, como qué comandos se realizaron finalmente en el sistema de ejecución.
La edición de los flujos de trabajo puede hacerse completamente con el navegador o mediante la integración con VS Code, si lo prefieres. Los cambios pueden confirmarse directamente en la rama actual o fusionarse mediante pull requests. Cuando se hace a través de una solicitud de extracción, los flujos de trabajo que coincidan con el evento se activarán y se ejecutarán como comprobaciones previas para validar el cambio antes de la fusión.
En el próximo capítulo nos centraremos más en los sistemas donde se ejecutan los flujos de trabajo, también conocidos como ejecutores.
Get Aprender las acciones de GitHub now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.