\section{Por qué CI/CD para LaTeX}
Trate los documentos como código
Las compilaciones automáticas detectan paquetes rotos y errores de compilación antes de que lleguen a colaboradores o revisores. Los PDF siempre están a una ejecución del pipeline.
Detecte errores antes de fusionar
Las comprobaciones del pipeline fallan si el documento no compila. Los revisores ven el LaTeX roto antes de que llegue a main.
Artefactos en cada ejecución
GitLab guarda los PDF compilados como artefactos de trabajo. Descargue la última compilación directamente desde la interfaz del pipeline.
No hace falta TeX Live local
Los colaboradores editan archivos .tex sin instalar una distribución de TeX Live de 4 GB. La compilación se realiza en la nube.
\section{Prerequisites}
Antes de empezar
- Cuenta de FormaTeX: el plan gratuito sirve (15 compilaciones al mes)
- Una clave de API de FormaTeX desde su panel
- Un repositorio de GitLab que contenga archivos .tex
Configurar la variable de CI/CD
En GitLab, vaya a Settings › CI/CD › Variables › Add variable . Establezca la clave como FORMATEX_API_KEY, pegue su clave de API como valor y active Masked para que nunca aparezca en los registros de los trabajos.
\section{Pipeline básico}
Su primer .gitlab-ci.yml
Coloque este archivo en la raíz de su repositorio. Descarga alpine:latest, instala curl y jq, compila main.tex y guarda el PDF resultante como artefacto de GitLab durante una semana.
# .gitlab-ci.yml
stages:
- build
compile-latex:
stage: build
image: alpine:latest
before_script:
- apk add --no-cache curl jq
script:
- |
curl -X POST https://api.formatex.io/api/v1/compile \
-H "X-API-Key: $FORMATEX_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"latex\": $(cat main.tex | jq -Rs .), \"engine\": \"pdflatex\"}" \
--output output.pdf
artifacts:
paths:
- output.pdf
expire_in: 1 week
only:
- main
- merge_requests\section{Pipeline avanzado}
Anclas YAML y trabajos en paralelo
Escale a varios documentos sin repetirse. Este pipeline usa un ancla YAML para definir una plantilla de compilación reutilizable y la instancia para main.tex y presentation.tex en paralelo. Después, el trabajo pages publica todos los PDF en GitLab Pages.
# .gitlab-ci.yml — advanced with matrix and error handling
stages:
- validate
- build
- publish
variables:
FORMATEX_API_URL: "https://api.formatex.io/api/v1"
.compile-template: &compile
image: alpine:latest
before_script:
- apk add --no-cache curl jq
script:
- |
RESPONSE=$(curl -s -w "\n%{http_code}" \
-X POST "$FORMATEX_API_URL/compile" \
-H "X-API-Key: $FORMATEX_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"latex\": $(cat $TEX_FILE | jq -Rs .), \"engine\": \"$ENGINE\"}")
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
if [ "$HTTP_CODE" != "200" ]; then
echo "Error: $(echo "$RESPONSE" | head -n-1)"
exit 1
fi
echo "$RESPONSE" | head -n-1 > "$OUTPUT_FILE"
artifacts:
paths:
- "*.pdf"
expire_in: 30 days
compile-main:
<<: *compile
stage: build
variables:
TEX_FILE: main.tex
ENGINE: pdflatex
OUTPUT_FILE: main.pdf
compile-presentation:
<<: *compile
stage: build
variables:
TEX_FILE: presentation.tex
ENGINE: xelatex
OUTPUT_FILE: presentation.pdf
pages:
stage: publish
script:
- mkdir -p public
- cp *.pdf public/
artifacts:
paths:
- public
only:
- main\section{GitLab Pages}
Publique PDF mediante GitLab Pages
El trabajo pages del pipeline avanzado copia todos los PDF compilados en el directorio public/ y los expone como un sitio de GitLab Pages. Los documentos compilados quedan entonces disponibles automáticamente en https://<group>.gitlab.io/<project>/ con cada push a main. Sin cargas manuales y sin configurar alojamiento.
\section{Troubleshooting}
Problemas comunes y soluciones
curl: command not found
Las imágenes de Alpine se entregan sin curl de forma predeterminada. Incluya siempre apk add --no-cache curl jq en su before_script. Si cambia a una imagen basada en Debian, use apt-get install -y curl jq en su lugar.
Clave de API no enmascarada en los registros
Asegúrese de haber creado la variable con la opción Masked activada en GitLab Settings › CI/CD › Variables. Sin enmascarar, la clave aparece en texto plano en los registros de los trabajos. Vuelva a crear la variable con Masked activada.
Archivos .tex grandes que superan el tiempo de espera
The sync endpoint has a timeout for very large documents. For files over 10 MB, switch to the async endpoint (/api/v1/compile/async) which returns a job ID. Poll /api/v1/jobs/{id} until the status is completed, then download the PDF from /api/v1/jobs/{id}/pdf.
\section{Integraciones relacionadas}
Use FormaTeX desde cualquier entorno
FormaTeX es una API HTTP sencilla. Ejemplos para copiar y pegar para cada plataforma importante.