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

Guía de Bitflow Solutions. Versión web: https://bitflow-solutions.com/guias-tecnicas/ci-cd-github-actions/

## ¿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

### Piezas de un workflow

| Clave | Para qué sirve |
|---|---|
| name | Nombre del workflow |
| on | Qué lo dispara (push, pull_request, workflow_dispatch, schedule) |
| jobs | Trabajos (en paralelo por defecto) |
| runs-on | Máquina del job |
| steps | Pasos: uses (acción) o run (comandos) |
| with / env | Parámetros / variables |
| needs / if | Dependencias / condiciones |
| secrets | Valores protegidos |
| environment | Entorno con secretos y reglas propias |
| permissions | Permisos del GITHUB_TOKEN |

### Ubicación

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

### Secretos

- Settings > Environments > produccion > secreto KUBECONFIG (archivo kubeconfig completo)
- Nunca en el YAML ni impresos en un paso

### Workflow completo (.github/workflows/ci-cd.yml)

```yaml
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
```

### Proteger main

Settings > Rules > Rulesets: exigir pull request y el check «pruebas».

## 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.
