Todas las guías
  1. Inicio
  2. Guías técnicas
  3. DevOps

DevOpsNivel básico

Estructura básica de un CI/CD con GitHub Actions

6 min de lectura

Todas las guías

Estructura básica de un CI/CD con GitHub Actions

La estructura básica de un pipeline de CI/CD con GitHub Actions: pruebas automáticas en cada cambio, una imagen Docker publicada en el registro de GitHub y un despliegue a un entorno protegido. Usamos como ejemplo la API de la guía de FastAPI, y el workflow completo está en el README.md de la izquierda.

¿Qué vas a aprender?

  • Las piezas de un workflow de GitHub Actions y dónde va el archivo.
  • Integración continua: ejecutar las pruebas en cada push y en cada pull request.
  • Construir una imagen Docker y publicarla en GitHub Container Registry.
  • Despliegue continuo a un entorno protegido, con sus secretos.
  • Proteger la rama principal para que nada se integre sin pasar las pruebas.

Requisitos previos

  • Un repositorio en GitHub donde tengas permisos de administración.
  • Un proyecto con pruebas y un Dockerfile. Usamos el de la guía Cómo crear una API REST con FastAPI en Windows.
  • Para el despliegue: un clúster de Kubernetes con un Deployment llamado api-tareas y su kubeconfig (ver la guía de administración de Kubernetes). Si aún no lo tienes, puedes hacer los pasos 1 a 4.
  • Saber hacer commit y push con git.

Paso a paso

1. Entiende las piezas de un workflow

Un workflow es un archivo YAML que describe qué hacer cuando ocurre algo en el repositorio. Sus piezas principales:

ClavePara qué sirve
nameNombre del workflow en la pestaña Actions.
onQué lo dispara: push, pull_request, workflow_dispatch (a mano), schedule (programado)…
jobsLos trabajos. Por defecto se ejecutan en paralelo, cada uno en una máquina limpia.
runs-onLa máquina (runner) del job: ubuntu-latest, windows-latest…
stepsLos pasos del job, en orden: uses ejecuta una acción ya hecha; run, comandos.
with · envParámetros de una acción · variables de entorno.
needs · ifDependencias entre jobs · condiciones para ejecutarlos.
secretsValores protegidos (contraseñas, tokens): no se ven en los logs.
environmentEl entorno de destino, con sus propios secretos y reglas de protección.
permissionsQué puede hacer el token automático GITHUB_TOKEN.

2. Crea el archivo del workflow

Los workflows viven en la carpeta .github/workflows/ del repositorio. Crea allí ci-cd.yml:

api-tareas/
├── .github/
│   └── workflows/
│       └── ci-cd.yml
├── main.py
├── test_main.py
├── requirements.txt
└── Dockerfile

Empieza con lo mínimo para comprobar que funciona. Haz commit y push, y mira la ejecución en la pestaña Actions del repositorio:

name: CI

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

jobs:
  pruebas:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hola desde GitHub Actions"

3. Añade la integración continua

Sustituye el job de prueba por uno que prepare Python (con caché de dependencias), instale lo necesario y ejecute las pruebas. Al ir en pull_request, cada propuesta de cambio queda validada antes de integrarla:

jobs:
  pruebas:
    runs-on: ubuntu-latest
    steps:
      - name: Descargar el código
        uses: actions/checkout@v4

      - name: Preparar Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - name: Instalar dependencias
        run: pip install -r requirements.txt pytest

      - name: Ejecutar las pruebas
        run: pytest

4. Construye y publica la imagen

Un segundo job, que solo arranca si las pruebas pasan (needs) y solo en los push a main (if), construye la imagen y la publica en GitHub Container Registry (ghcr.io). Se autentica con el GITHUB_TOKEN automático, al que damos permiso para escribir paquetes. La imagen se etiqueta con el commit (github.sha), así siempre sabes qué código hay desplegado.

  imagen:
    needs: pruebas
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - name: Iniciar sesión en GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Construir y publicar la imagen
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: ${{ env.IMAGEN }}:${{ github.sha }}

5. Guarda los secretos

En el repositorio, ve a Settings → Secrets and variables → Actions. Los secretos de un entorno concreto se crean en Settings → Environments, dentro del entorno, y solo los ven los jobs que lo usan.

  • Crea el entorno produccion.
  • Dentro, crea el secreto KUBECONFIG con el contenido completo del archivo kubeconfig del clúster.
  • Nunca pongas un secreto en el YAML ni lo imprimas con echo en un paso: GitHub lo oculta en los logs, pero no en archivos ni artefactos.

6. Despliega al entorno protegido

El tercer job usa el entorno produccion: recoge su secreto, configura kubectl, actualiza la imagen del Deployment y espera a que el despliegue termine bien:

  desplegar:
    needs: imagen
    runs-on: ubuntu-latest
    environment: produccion
    steps:
      - name: Configurar kubectl
        run: |
          mkdir -p ~/.kube
          echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config

      - name: Desplegar la nueva imagen
        run: |
          kubectl set image deployment/api-tareas api=${{ env.IMAGEN }}:${{ github.sha }}
          kubectl rollout status deployment/api-tareas --timeout=120s

En Settings → Environments → produccion puedes limitar qué ramas pueden desplegar (solo main) y, en planes de pago o repositorios públicos, exigir la aprobación de una persona antes de cada despliegue.

7. Revisa el workflow completo

Todo junto, con permisos mínimos por defecto, cancelación de ejecuciones repetidas y la opción de lanzarlo a mano (workflow_dispatch). Lo tienes también en el README.md de la izquierda:

name: CI/CD

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

# Mínimos permisos por defecto; cada job pide lo que necesita
permissions:
  contents: read

# Si llega un push nuevo a la misma rama, se cancela la ejecución anterior
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

env:
  IMAGEN: ghcr.io/empresa/api-tareas   # siempre en minúsculas

jobs:
  pruebas:
    runs-on: ubuntu-latest
    steps:
      - name: Descargar el código
        uses: actions/checkout@v4

      - name: Preparar Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
          cache: pip

      - name: Instalar dependencias
        run: pip install -r requirements.txt pytest

      - name: Ejecutar las pruebas
        run: pytest

  imagen:
    needs: pruebas
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - name: Iniciar sesión en GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Construir y publicar la imagen
        uses: docker/build-push-action@v6
        with:
          push: true
          tags: ${{ env.IMAGEN }}:${{ github.sha }}

  desplegar:
    needs: imagen
    runs-on: ubuntu-latest
    environment: produccion
    steps:
      - name: Configurar kubectl
        run: |
          mkdir -p ~/.kube
          echo "${{ secrets.KUBECONFIG }}" > ~/.kube/config

      - name: Desplegar la nueva imagen
        run: |
          kubectl set image deployment/api-tareas api=${{ env.IMAGEN }}:${{ github.sha }}
          kubectl rollout status deployment/api-tareas --timeout=120s

8. Protege la rama principal

En Settings → Rules → Rulesets (o Branches, en repositorios antiguos), crea una regla para main que exija pull request y que el check pruebas haya pasado. Así nadie integra código que rompa las pruebas, tampoco por error.

9. Sigue cada ejecución

En la pestaña Actions ves cada ejecución con sus jobs y el log de cada paso. Si algo falla, abre el paso en rojo; si fue algo puntual, Re-run failed jobs vuelve a lanzar solo lo que falló.

Errores habituales

El workflow no se ejecuta

El archivo tiene que estar en .github/workflows/ y en la rama del evento. Para workflow_dispatch (botón Run workflow), el archivo debe estar ya en la rama principal.

Error de sintaxis en el YAML

Casi siempre es la sangría: YAML usa espacios, nunca tabuladores, y cada nivel debe estar alineado. La pestaña Actions marca la línea del error.

«denied: permission_denied» al publicar en ghcr.io

Falta packages: write en permissions del job, o el paquete ya existe y no está vinculado al repositorio. Revisa los permisos del paquete en Packages → Package settings.

«repository name must be lowercase»

Los nombres de imagen en un registro de contenedores van en minúsculas. Si usas ${{ github.repository }} y el usuario u organización tiene mayúsculas, escribe el nombre a mano en minúsculas.

Los secretos llegan vacíos en un pull request

Por seguridad, los pull requests que vienen de un fork no reciben secretos. Por eso el job de imagen y el de despliegue solo corren en push.

No aparece la opción de revisores obligatorios

La aprobación manual de entornos (Required reviewers) solo está disponible en repositorios públicos o con planes de pago. Con el plan gratuito y un repositorio privado, limita el entorno a la rama main o lanza el despliegue a mano con workflow_dispatch.

kubectl no conecta con el clúster

El secreto KUBECONFIG debe contener el archivo completo, con sus saltos de línea. Comprueba también que el clúster acepta conexiones desde los runners de GitHub (IP públicas) o usa un runner propio dentro de tu red.

Siguientes pasos

  • Añadir análisis estático y de seguridad del código (por ejemplo, SonarCloud o CodeQL) como un job más.
  • Activar Dependabot para mantener actualizadas las dependencias y las versiones de las acciones.
  • Sustituir el secreto del kubeconfig por OIDC: GitHub obtiene credenciales temporales de Azure, AWS o Google Cloud sin guardar contraseñas.
  • Probar en varias versiones a la vez con strategy.matrix y reutilizar workflows entre repositorios.

Compartir

Más guías sobre

Ver todas las guías

Otras guías técnicas

Ver todas las guías

APIsIntermedio

Estructura básica de una API en IBM API Connect 10

Cómo se estructura una API en IBM API Connect 10: contrato OpenAPI con x-ibm-configuration, Client ID y Client Secret, producto con planes y límites, y validación y publicación con el CLI apic.

Leer la guía 7 min de lectura

IntegraciónIntermedio

Comandos básicos de administración de TIBCO ActiveSpaces 5.2

Los comandos del día a día en TIBCO ActiveSpaces 5.2: servicio de realm sobre servidores FTL, tibdg, definición del grid, tablas, arranque de procesos, estado, escalado con copysets, checkpoints y logs.

Leer la guía 8 min de lectura

DesarrolloBásico

Buenas prácticas de desarrollo en Java con Spring Boot

Las prácticas que más se notan en un servicio Spring Boot: estructura, inyección por constructor, DTOs, validación, errores, configuración, transacciones, logs, comentarios, pruebas y calidad automatizada.

Leer la guía 8 min de lectura

Contacto

Construye hoy tu próxima ventaja competitiva

Hablemos sobre cómo podemos ayudarte. Te respondemos con una propuesta técnica clara, sin compromiso.

Solicita información

Los campos marcados con son obligatorios.