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
Deploymentllamadoapi-tareasy 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:
| Clave | Para qué sirve |
|---|---|
name | Nombre del workflow en la pestaña Actions. |
on | Qué lo dispara: push, pull_request, workflow_dispatch (a mano), schedule (programado)… |
jobs | Los trabajos. Por defecto se ejecutan en paralelo, cada uno en una máquina limpia. |
runs-on | La máquina (runner) del job: ubuntu-latest, windows-latest… |
steps | Los pasos del job, en orden: uses ejecuta una acción ya hecha; run, comandos. |
with · env | Parámetros de una acción · variables de entorno. |
needs · if | Dependencias entre jobs · condiciones para ejecutarlos. |
secrets | Valores protegidos (contraseñas, tokens): no se ven en los logs. |
environment | El entorno de destino, con sus propios secretos y reglas de protección. |
permissions | Qué 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
KUBECONFIGcon el contenido completo del archivo kubeconfig del clúster. - Nunca pongas un secreto en el YAML ni lo imprimas con
echoen 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.matrixy reutilizar workflows entre repositorios.