Pipeline de CI/CD

KanjiIQ usa Forgejo Actions para integración y despliegue continuos. Forgejo Actions es compatible con la sintaxis YAML de GitHub Actions, ejecutándose en runners autoalojados.

Estructura de flujos de trabajo

.forgejo/workflows/
├── deploy-frontend.yml    # Build & deploy Flutter Web
├── deploy-backend.yml     # Build & deploy Dart Frog API
└── deploy-docs.yml        # Build & deploy documentation site

Cada flujo de trabajo sigue el mismo patrón:

graph TD
    A[Push to main] --> B{Path filter<br/>matches?}
    B -->|Yes| C[Checkout code]
    B -->|No| X[Skip]
    C --> D[Login to Forgejo<br/>Container Registry]
    D --> E[Docker build<br/>--no-cache]
    E --> F[Push :latest +<br/>:COMMIT_SHA]
    F --> G[kubectl set image]
    G --> H[Wait for rollout<br/>timeout: 5m]
    H --> I[Cleanup: logout]

Flujo de trabajo del frontend

name: Deploy Frontend to k3s

on:
  push:
    branches: [main]
    paths:
      - 'frontend/**'
      - 'Dockerfile.frontend'
      - 'nginx.frontend.conf'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Login to registry
        run: echo "$FORGEJO_TOKEN" | docker login $REGISTRY_URL -u $REGISTRY_USER --password-stdin

      - name: Build image
        run: |
          docker build --no-cache --pull \
            --build-arg CACHEBUST=$(date +%s) \
            -f Dockerfile.frontend \
            -t <registry>/jlpt-kanji-frontend:latest \
            -t <registry>/jlpt-kanji-frontend:$(git rev-parse --short HEAD) .

      - name: Push & deploy
        run: |
          docker push <registry>/jlpt-kanji-frontend:latest
          docker push <registry>/jlpt-kanji-frontend:$(git rev-parse --short HEAD)
          kubectl set image deployment/jlpt-kanji \
            frontend=<registry>/jlpt-kanji-frontend:$(git rev-parse --short HEAD) \
            -n jlpt-kanji
          kubectl rollout status deployment/jlpt-kanji -n jlpt-kanji --timeout=5m

Secretos

Los flujos de trabajo usan un único secreto:

Secreto	Propósito
FORGEJO_TOKEN	Autenticación para publicación en el registro de contenedores y acceso a Kubernetes

El token se configura en Forgejo en Repository Settings > Secrets.

Registro de imágenes

Todas las imágenes se almacenan en el Forgejo Container Registry:

<registry>/jlpt-kanji-frontend:latest
<registry>/jlpt-kanji-frontend:<commit-sha>
<registry>/jlpt-kanji-backend:latest
<registry>/jlpt-kanji-backend:<commit-sha>
<registry>/jlpt-kanji-docs:latest
<registry>/jlpt-kanji-docs:<commit-sha>

Verificación del despliegue

Después de kubectl set image, el flujo de trabajo espera a que se complete el despliegue:

kubectl rollout status deployment/jlpt-kanji -n jlpt-kanji --timeout=5m

Esto se bloquea hasta que:

• Todos los nuevos pods pasen las sondas de readiness, o
• El tiempo de espera expire (el flujo de trabajo falla, alertando al desarrollador)

Si un despliegue falla, Kubernetes detiene automáticamente el rollout y la versión anterior continúa sirviendo tráfico.

Reversión manual

Para revertir a una versión anterior:

# Rollback to previous revision
kubectl rollout undo deployment/jlpt-kanji -n jlpt-kanji

# Or roll back to a specific image
kubectl set image deployment/jlpt-kanji \
  frontend=<registry>/jlpt-kanji-frontend:<previous-sha> \
  -n jlpt-kanji