1.4.-Github Action

1.4. GitHub Actions¶

Idea principal

GitHub Actions permite automatizar tareas de un repositorio mediante workflows: ficheros YAML que indican qué evento inicia el proceso, qué trabajos debe ejecutar y en qué orden. Puede ayudar a comprobar cambios, generar documentación y desplegar aplicaciones.

En un proyecto web no basta con escribir código: también hay que integrar los cambios del equipo, comprobar que la aplicación sigue funcionando y, cuando corresponda, preparar una versión para publicarla. Si cada tarea se hace a mano, es fácil olvidar pasos o aplicarlos de forma distinta. GitHub Actions permite automatizar tareas repetibles desde el repositorio de GitHub.

En el apartado anterior has estudiado DevOps y la diferencia entre integración continua, entrega continua y despliegue continuo. Aquí aprenderás cómo se organizan las automatizaciones de GitHub Actions y cómo leer y adaptar workflows sencillos. El objetivo no es memorizar una receta, sino entender qué ocurre en cada paso y qué permisos necesita.

Este contenido contribuye al RA 6 del módulo y trabaja el CE 6.h. La tabla recoge literalmente los descriptores de la normativa del módulo profesional 0614, Despliegue de aplicaciones web:

Código	Descripción
RA 6	Elabora la documentación de la aplicación web evaluando y seleccionando herramientas de generación de documentación, control de versiones y de integración continua.
CE 6.h	Se han utilizado herramientas para la integración continua del código.

Leer los ejemplos permite comprender la herramienta, pero para demostrar que sabes utilizarla tendrás que configurar y ejecutar un workflow en la práctica asociada.

Qué deberías saber al terminar

Al acabar este tema deberías poder:

explicar qué es GitHub Actions y cómo se relaciona con CI/CD;
reconocer los eventos, workflows, jobs, runners, steps y actions;
interpretar un fichero YAML sencillo y seguir el orden de su ejecución;
describir cómo se automatizan pruebas, documentación o despliegues;
identificar permisos y riesgos básicos al incorporar acciones de terceros.

Mapa del tema

Seguiremos esta secuencia:

qué es GitHub Actions y qué problema ayuda a resolver;
cómo se organiza un workflow;
cómo ejecutar una comprobación de CI;
cómo reutilizar actions para actualizar documentación o desplegar;
qué buenas prácticas aplicar y qué errores evitar.

1. Automatizar tareas con GitHub Actions¶

GitHub Actions es una plataforma de automatización integrada en GitHub. Permite definir tareas que se ejecutan cuando ocurre un evento del repositorio, por ejemplo, al subir cambios (push), al abrir una solicitud de cambios (pull request) o al iniciar una ejecución manual. También puede programarse para ejecutarse periódicamente.

Piensa en ello como un ayudante automatizado del proyecto: el equipo define qué debe comprobarse y bajo qué condiciones; GitHub prepara un entorno de ejecución y muestra el resultado. La plataforma ejecuta las instrucciones, pero no decide si las pruebas son suficientes ni garantiza por sí sola que el software sea correcto o seguro.

Workflow

Un workflow es un flujo de trabajo automatizado descrito en un fichero YAML que se guarda en .github/workflows/ dentro del repositorio. Define cuándo se inicia y qué trabajos debe ejecutar.

En conversaciones sobre CI/CD también se llama pipeline a la secuencia de compilación, pruebas y publicación. En GitHub Actions, cada definición concreta guardada en .github/workflows/ es un workflow; puede representar una parte o la totalidad de ese pipeline.

Un mismo repositorio puede tener varios workflows: uno para las pruebas, otro para publicar la documentación y otro para preparar una versión. GitHub Actions es una herramienta que permite implantar partes del flujo CI/CD; tener Actions configurado no significa que el proyecto ya tenga integración o despliegue continuos. Eso depende de los eventos, comprobaciones, condiciones y destinos que se hayan configurado.

El recorrido general se puede representar así:

flowchart TD
  A["Evento: push, pull request o ejecución manual"] --> B["Se inicia el workflow"]
  B --> C["GitHub asigna un runner"]
  C --> D["El job ejecuta sus steps"]
  D --> E{"¿Terminan correctamente?"}
  E -->|No| F["Consultar logs y corregir el cambio"]
  F --> A
  E -->|Sí| G["Guardar un artefacto o desplegar"]

El diagrama resume un patrón habitual, no una obligación: un workflow puede tener varios jobs, saltarse pasos con condiciones o finalizar después de ejecutar pruebas sin publicar nada.

2. Estructura de un workflow¶

Los workflows se escriben en YAML y se almacenan, por ejemplo, en .github/workflows/ci.yml. También se puede utilizar la extensión .yaml. Cada elemento tiene una función:

Elemento	Función	Ejemplo
`name`	Nombre visible del workflow.	`CI del proyecto`
`on`	Evento o eventos que lo inician.	`push`, `pull_request`, `workflow_dispatch`
`jobs`	Trabajos que ejecutará el workflow.	`test`, `build`, `deploy`
`runs-on`	Tipo de runner donde se ejecuta un job.	`ubuntu-latest`
`steps`	Pasos secuenciales de un job.	Obtener el código y ejecutar pruebas.
`uses`	Acción reutilizable que realiza una tarea.	`actions/checkout@v7`
`run`	Comando de terminal que ejecuta el runner.	`npm test`
`with`	Parámetros que se pasan a una acción.	`node-version: "24"`

Los eventos más habituales son:

Evento	Cuándo inicia el workflow	Uso típico
`push`	Cuando se suben commits a una rama.	Ejecutar pruebas tras actualizar `main`.
`pull_request`	Cuando se abre o actualiza una solicitud de cambios.	Revisar el cambio antes de integrarlo.
`workflow_dispatch`	Cuando una persona lo inicia manualmente desde GitHub.	Probar un flujo bajo demanda.
`schedule`	En las fechas y horas definidas con una expresión cron.	Ejecutar una comprobación periódica.

Se pueden filtrar eventos por ramas o rutas para evitar ejecuciones que no sean necesarias. Por defecto, los eventos programados utilizan UTC, aunque se puede especificar una zona horaria. Si el horario importa, consulta las limitaciones de la programación y confirma qué zona se ha configurado.

Jobs y steps no se ejecutan del mismo modo

Los steps de un mismo job se ejecutan en orden y comparten el entorno de ese job. Varios jobs pueden ejecutarse en paralelo; para que uno espere a otro se utiliza, por ejemplo, needs: build. Cada job tiene su propio entorno: si necesita ficheros generados por otro, hay que compartirlos, por ejemplo, mediante artefactos.

Para probar el mismo job con varias versiones de un lenguaje o sistemas operativos, se puede definir una matriz con strategy.matrix. GitHub crea una ejecución por combinación seleccionada; esto evita duplicar bloques de YAML, aunque también aumenta el número de ejecuciones.

Un runner es el entorno que ejecuta un job. Puede ser una máquina virtual alojada por GitHub —la opción habitual en los primeros ejemplos— o un equipo configurado por la organización (self-hosted runner). runs-on selecciona el tipo de runner, como ubuntu-latest, windows-latest o macos-latest.

Este ejemplo ejecuta un solo job cada vez que hay un push a main o cuando una persona lo inicia manualmente:

name: CI Demo

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  saludo:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Obtener el código del repositorio
        uses: actions/checkout@v7

      - name: Mostrar un mensaje
        run: echo "Hola, GitHub Actions"

En este ejemplo, on establece los eventos; jobs contiene el trabajo llamado saludo; runs-on selecciona Ubuntu; y los dos steps se ejecutan en orden. La acción actions/checkout descarga el contenido del repositorio en el runner. Sin ese paso, los comandos posteriores no tendrían el código del proyecto disponible en el directorio de trabajo. permissions: contents: read limita los permisos del token del job a la lectura del contenido del repositorio.

3. Ejecutar pruebas en integración continua¶

Una comprobación de integración continua (CI) puede ejecutarse con cada push y con cada solicitud de cambios. Así el equipo recibe información antes de integrar un cambio. La configuración concreta depende de las tecnologías del proyecto.

El siguiente ejemplo supone un proyecto Node.js que ya tiene un package.json, un package-lock.json y un script test definido en package.json:

name: CI de Node.js

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Obtener el código
        uses: actions/checkout@v7

      - name: Configurar Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24"
          cache: npm

      - name: Instalar dependencias
        run: npm ci

      - name: Ejecutar pruebas
        run: npm test

El proceso obtiene el repositorio, configura Node.js, instala las dependencias descritas en el archivo de bloqueo y ejecuta las pruebas. npm ci necesita un package-lock.json coherente con package.json; si el proyecto no lo tiene, hay que elegir y documentar otro método de instalación. npm test solo funcionará si el proyecto define ese script y tiene pruebas que ejecutar.

Si una comprobación falla, el job queda marcado como fallido y sus logs ayudan a localizar el paso que ha dado error. GitHub puede configurarse para impedir que se integre una pull request mientras no pasen las comprobaciones, pero esa regla de protección debe establecerse en el repositorio: no aparece por el mero hecho de crear el workflow.

4. Reutilizar acciones y automatizar tareas¶

Una action es un componente reutilizable que puede ejecutar una tarea concreta. GitHub ofrece el Marketplace de Actions, donde se pueden encontrar acciones creadas por GitHub, empresas y comunidades. Antes de programar una tarea desde cero, comprobar si existe una acción adecuada puede ahorrar trabajo; aun así, hay que revisar quién la mantiene, qué permisos necesita y qué código ejecuta. Las acciones pueden, por ejemplo, configurar un entorno, desplegar una aplicación o enviar una notificación.

Acción	Uso habitual
`actions/checkout`	Obtener una copia del repositorio en el runner.
`actions/setup-node`	Instalar o seleccionar una versión de Node.js.
`actions/setup-python`	Instalar o seleccionar una versión de Python.
`peaceiris/actions-gh-pages`	Publicar un sitio estático en una rama de GitHub Pages.
`stefanzweifel/git-auto-commit-action`	Crear un commit con archivos modificados durante un workflow.

La sintaxis uses: propietario/acción@referencia identifica la acción y su versión o referencia. En los siguientes ejemplos se indican versiones principales para facilitar su lectura. En un proyecto real, revisa las actualizaciones, el código y las recomendaciones de seguridad; fijar una acción a un commit completo e inmutable ofrece más garantías frente a cambios inesperados que utilizar una etiqueta que pueda moverse.

Pull requests y código no confiable

Una pull request procedente de un fork puede incluir código de personas externas. Aunque GitHub limita habitualmente los secretos y los permisos del token para estas ejecuciones, no ejecutes código no confiable con acceso a credenciales o permisos de escritura. Revisa con especial cuidado los workflows que usan pull_request_target.

4.1. Ejemplo: actualizar el README después de las pruebas¶

El repositorio de demostración 2526_DAW_u1_action contiene un script update_readme.py que ejecuta pruebas y actualiza el README.md. El siguiente workflow muestra cómo automatizar esa tarea y guardar el cambio generado mediante un commit:

name: CI con actualización del README

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  test-and-update:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Obtener el repositorio
        uses: actions/checkout@v7

      - name: Configurar Python
        uses: actions/setup-python@v7
        with:
          python-version: "3.12"

      - name: Instalar pytest
        run: python -m pip install pytest

      - name: Ejecutar las pruebas y actualizar el README
        run: python update_readme.py

      - name: Guardar el README actualizado
        uses: stefanzweifel/git-auto-commit-action@v7
        with:
          commit_message: "Actualiza el README con el estado de las pruebas"
          file_pattern: README.md

El ejemplo se ejecuta al subir cambios a main o manualmente. Configura Python, instala pytest, ejecuta el script y crea un commit solo si encuentra cambios en README.md. El token GITHUB_TOKEN lo proporciona GitHub para cada ejecución. La acción de checkout conserva por defecto las credenciales necesarias para que la acción de commit pueda enviar los cambios; el permiso contents: write es necesario para escribir en el repositorio y se concede únicamente al job que realiza el commit.

La acción no sustituye al script: este debe saber ejecutar o interpretar las pruebas y modificar el README.md. En un proyecto real, instala todas las dependencias necesarias, por ejemplo desde un archivo de requisitos. Para informes que no deban conservarse en el historial puede ser más apropiado subir un artefacto que crear un commit automático.

Escritura automática y credenciales

Concede contents: write solo cuando sea necesario y evita guardar tokens personales en el repositorio. Los eventos creados por el GITHUB_TOKEN normalmente no inician otra ejecución de workflow; si se usa un token personal u otro mecanismo, un commit automático puede volver a activar el flujo y producir ejecuciones repetidas.

4.2. Ejemplo: desplegar documentación en GitHub Pages¶

Si un proyecto contiene documentación en Markdown con MkDocs —o un sitio estático generado con otra herramienta—, se puede construir y publicar de forma automática. Este ejemplo utiliza peaceiris/actions-gh-pages para publicar la carpeta site/ en la rama gh-pages:

name: Publicar documentación en GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Obtener el repositorio
        uses: actions/checkout@v7

      - name: Configurar Python
        uses: actions/setup-python@v7
        with:
          python-version: "3.13"

      - name: Instalar MkDocs
        run: python -m pip install mkdocs

      - name: Construir el sitio
        run: mkdocs build

      - name: Publicar en GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: ./site

Cuando hay un push a main, el runner obtiene los archivos, prepara Python, instala MkDocs y construye el sitio en site/. Después, la acción publica esos ficheros en gh-pages con el token de GitHub. Para que la web quede visible, configura GitHub Pages en los ajustes del repositorio para que publique desde esa rama. Si el proyecto utiliza temas o plugins de MkDocs, instala también sus dependencias —por ejemplo, desde requirements.txt— y comprueba localmente la construcción antes de automatizarla.

Este método con peaceiris/actions-gh-pages es una alternativa que publica en una rama. GitHub también ofrece un flujo de publicación mediante acciones oficiales de Pages; la elección depende de la configuración del repositorio. En ambos casos hay que revisar los permisos de escritura y de publicación que requiera el flujo elegido.

5. GitHub Actions en CI/CD y primera ejecución¶

En un proyecto real de despliegue web, los workflows pueden automatizar distintas fases:

Fase	Tareas que se pueden automatizar
CI (integración continua)	Ejecutar pruebas con cada cambio; compilar; analizar la calidad del código, la seguridad o las dependencias.
CD (entrega o despliegue continuo)	Preparar una versión; publicar documentación; construir imágenes Docker y subirlas a un registro; desplegar en un servidor, un contenedor o una plataforma en la nube como AWS, Azure o GCP.

En el tema de DevOps y CI/CD se estudia la diferencia entre dejar una versión preparada para su publicación y desplegarla automáticamente en producción. GitHub Actions puede ejecutar ambos tipos de tarea, pero las condiciones de publicación, las aprobaciones y los controles dependen de cómo se configure el proyecto.

5.1. Actividad: crear y ejecutar el primer workflow¶

El siguiente ejercicio permite comprobar el recorrido completo de un workflow manual:

Crea un repositorio de prueba en GitHub que incluya un README.md.
En la rama principal, crea el directorio .github/workflows/ y guarda dentro un fichero hello.yml con este contenido:
```
name: Hola Mundo

on: workflow_dispatch

jobs:
  say-hello:
    runs-on: ubuntu-latest
    permissions: {}
    steps:
      - name: Saludar
        run: echo "Hola, GitHub Actions"
```
El evento workflow_dispatch permite iniciar el flujo manualmente. En este ejemplo no hace falta descargar el repositorio porque el único paso imprime un mensaje. permissions: {} evita conceder permisos al token del workflow, ya que este ejercicio no necesita acceder al repositorio. En un flujo que necesite leer archivos del proyecto, normalmente se añade actions/checkout y se concede contents: read.
Abre la pestaña Actions, selecciona Hola Mundo y pulsa Run workflow. Para que GitHub permita iniciarlo manualmente, el fichero debe estar disponible en la rama predeterminada del repositorio.
Abre la ejecución y consulta sus logs. Comprueba qué job y qué step se han ejecutado y localiza la salida Hola, GitHub Actions.

Entregable: una captura de pantalla que muestre el workflow ejecutado y su resultado.

6. Buenas prácticas¶

Para construir workflows comprensibles y fiables, conviene:

Dar nombres descriptivos a los workflows, jobs y steps: así es más sencillo entender el resultado en la pestaña Actions.
Ejecutar solo las comprobaciones necesarias: se pueden filtrar ramas o rutas, sin dejar fuera cambios que sí deberían verificarse.
Usar versiones revisadas de las acciones y actualizar las dependencias con criterio. Para flujos sensibles, consulta la recomendación de fijar acciones a un SHA completo.
Aplicar el principio de mínimo privilegio: configura permissions y concede solo el acceso que cada job necesita.
Proteger los secretos: guarda credenciales en los secretos del repositorio, entorno u organización; nunca las escribas directamente en YAML ni las muestres en los logs.
Revisar los logs y probar los fallos: un workflow también debe ayudar a saber qué ha salido mal, no solo a mostrar que ha terminado.
Documentar y mantener el flujo junto al código. Si cambian las dependencias o los comandos locales, revisa también el workflow.
Valorar artefactos frente a commits automáticos: guarda en el historial solo los ficheros generados que formen parte del proyecto.

7. Errores frecuentes¶

Error frecuente	Por qué ocurre	Cómo evitarlo
Guardar el YAML fuera de `.github/workflows/`.	GitHub no detecta el fichero como un workflow del repositorio.	Comprueba la ruta y la extensión `.yml` o `.yaml`.
Confundir workflow, job, step y action.	Todos forman parte de la ejecución, pero representan niveles distintos.	Identifica el evento, los trabajos, sus pasos y las acciones reutilizables.
Ejecutar `npm ci` sin un `package-lock.json` válido.	El comando necesita el archivo de bloqueo para instalar de forma reproducible.	Versiona el archivo de bloqueo y comprueba que corresponde a `package.json`.
Suponer que `npm test` u otro comando existe en cualquier proyecto.	Los comandos dependen de la configuración y los scripts del proyecto.	Verifica localmente el comando y las dependencias antes de incluirlo.
Usar una acción del Marketplace sin revisar quién la mantiene.	Se confía en que cualquier acción publicada es segura o adecuada.	Revisa su origen, código, versión, permisos e incidencias conocidas.
Dar permisos o secretos a código recibido en una pull request de un fork.	Se supone que todo código que llega al repositorio es de confianza.	Mantén los permisos mínimos y evita exponer secretos; revisa especialmente `pull_request_target`.
Guardar un token en el YAML o conceder permisos de escritura a todos los jobs.	Se prioriza que la automatización funcione sin limitar el acceso.	Utiliza `GITHUB_TOKEN`, configura permisos mínimos y reserva `contents: write` para el job que lo necesite.
Dar por hecho que el sitio se publica al ejecutar `mkdocs build`.	Construir genera los archivos, pero no los publica por sí solo.	Añade y configura una tarea de publicación y comprueba los ajustes de GitHub Pages.
Añadir un commit automático sin valorar sus efectos.	Se puede llenar el historial de cambios generados o iniciar otros flujos.	Limita los archivos afectados, revisa la necesidad del commit y comprueba qué eventos genera el token utilizado.

8. Resumen¶

En este tema has aprendido que:

GitHub Actions ejecuta automatizaciones definidas como ficheros YAML en .github/workflows/;
los eventos inician un workflow, que contiene jobs y steps ejecutados en runners;
uses llama a una acción reutilizable, run ejecuta un comando y with configura parámetros de una acción;
un flujo de CI puede comprobar automáticamente código y pruebas, y otros workflows pueden generar documentación o desplegar una web;
usar acciones y tokens requiere revisar su origen, sus permisos y los archivos que van a modificar.

Idea clave

Un workflow no es magia: es una configuración ejecutable que conecta un evento con tareas concretas. Comprender cada paso y limitar sus permisos permite automatizar el proyecto sin perder el control sobre lo que hace.

9. Para seguir practicando¶

Realiza la práctica de documentación y GitHub Actions: analiza el workflow base, ejecútalo con pruebas correctas y fallidas y explica qué evento lo inicia.
Adapta el ejemplo de Node.js a un proyecto propio; añade una prueba que falle, observa los logs y corrige el error.
Compara los ejemplos de actualización del README.md y publicación en GitHub Pages. Indica qué permisos necesita cada uno y qué archivos escribe.
Revisa el repositorio de demostración de GitHub Actions y relaciona el script update_readme.py con los pasos del workflow.

Bibliografía y fuentes¶

Red Hat: ¿Qué es CI/CD? Guía para principiantes.
GitHub Docs: Documentación de GitHub Actions y entender GitHub Actions.
GitHub Docs: Sintaxis de los workflows y refuerzo de seguridad para GitHub Actions.
GitHub Marketplace de Actions.
Documentación de las acciones usadas: actions/checkout, actions/setup-node, actions/setup-python, peaceiris/actions-gh-pages y stefanzweifel/git-auto-commit-action.
GitHub Actions Cheat Sheet.
Repositorio de demostración: 2526_DAW_u1_action.