\section{Why CI/CD for LaTeX}
Ship documents with confidence
Treat your LaTeX source like software. Automated builds catch broken packages, missing files, and compilation errors before they reach your readers.
Never ship broken PDFs
Catch compilation errors before merge. Pull request checks fail if the document doesn't compile.
Automated distribution
PDF artifacts are attached to every workflow run. Share a direct link to the latest compiled document.
No local TeX Live required
Team members contribute to LaTeX source without installing TeX Live. The API handles compilation in the cloud.
\section{Prerequisites}
Before you start
- FormaTeX account — free tier works (15 compilations/month)
- A FormaTeX API key from your dashboard
- A GitHub repository containing .tex files
\section{Step-by-step guide}
Set up in four steps
Add secret to GitHub
Store your API key as a repository secret so it's never exposed in your workflow YAML. Navigate to Repository → Settings → Secrets and variables → Actions → New secret and name it FORMATEX_API_KEY.
# Add your FormaTeX API key as a GitHub Actions secret
# Go to: Repository → Settings → Secrets and variables → Actions → New secret
# Name: FORMATEX_API_KEY
# Value: your API key from formatex.io/dashboard/api-keys
# Test locally before committing:
export FORMATEX_API_KEY="your-key-here"
curl -X POST https://api.formatex.io/api/v1/compile \
-H "X-API-Key: $FORMATEX_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"latex": "\\documentclass{article}\\begin{document}Hello\\end{document}", "engine": "pdflatex"}'Create the workflow file
Create .github/workflows/latex.yml in your repository. This minimal workflow compiles main.tex and uploads the resulting PDF as an artifact.
# .github/workflows/latex.yml
name: Compile LaTeX
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
compile:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Compile LaTeX to PDF
id: compile
uses: forma-tex/github-action@v1
with:
api-key: ${{ secrets.FORMATEX_API_KEY }}
file: main.tex
output: output.pdf
smart: true
api-url: https://api.formatex.io
- name: Upload PDF artifact
if: steps.compile.outputs.status == 'success'
uses: actions/upload-artifact@v4
with:
name: compiled-pdf
path: output.pdfPush and watch it build
Commit and push the workflow file. GitHub Actions will trigger automatically on your next push to main. Navigate to the Actions tab in your repository to see the workflow run. Once it completes, the compiled PDF appears under Artifacts.
\section{Full workflow config}
Matrix build with error handling
Scale to multiple documents with a matrix strategy. This workflow compiles thesis, presentation, and appendix in parallel, captures HTTP errors explicitly, and stores PDFs for 30 days.
# .github/workflows/latex-full.yml
name: LaTeX Build Pipeline
on:
push:
paths: ['**.tex', '**.bib']
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
document: [thesis, presentation, appendix]
steps:
- uses: actions/checkout@v4
- name: Compile ${{ matrix.document }}
id: compile
uses: forma-tex/github-action@v1
with:
api-key: ${{ secrets.FORMATEX_API_KEY }}
file: ${{ matrix.document }}.tex
output: ${{ matrix.document }}.pdf
engine: xelatex
smart: false
api-url: https://api.formatex.io
- name: Upload PDFs
uses: actions/upload-artifact@v4
with:
name: pdfs-${{ matrix.document }}
path: ${{ matrix.document }}.pdf
retention-days: 30\section{Troubleshooting}
Common issues and solutions
API key not set
Ensure FORMATEX_API_KEY is added as a repository secret, not a variable. Secrets are encrypted; variables are not. Navigate to Settings → Secrets and variables → Actions → Secrets (not Variables).
Large .tex files
For files over 10 MB, use the async compile endpoint (/api/v1/compile/async). The async endpoint returns a job ID you can poll for the result.
Missing packages
FormaTeX's sandbox includes full TeX Live 2023 — most CTAN packages are available out of the box. If a package is missing, contact support and we'll add it.
\section{Related integrations}
Use FormaTeX from any environment
FormaTeX is a plain HTTP API. Copy-paste examples for every major language and platform.