CI(GitHub Actions 등)

CI(continuous integration)는 push할 때마다 서버가 PDF를 자동으로 빌드하는 방식입니다. 로컬에서 컴파일하지 않아도 항상 최신 출력을 얻을 수 있고, “내 환경에서는 된다” 문제를 일찍 발견할 수 있습니다. LaTeX에서는 GitHub Actions가 일반적인 선택입니다. 저장소를 체크아웃하고 TeX Live 환경에서 컴파일한 뒤, 만들어진 PDF를 artifact로 저장합니다.

왜 CI에서 빌드하는가

push할 때마다 문서는 깨끗하고 재현 가능한 TeX Live 환경에서 자동으로 빌드됩니다. 장점은 로컬 설정에 의존하던 버그를 일찍 잡을 수 있고, 문서가 항상 컴파일 가능한 상태로 유지되며, TeX를 설치하지 않은 공동 저자나 검토자도 최신 PDF를 받을 수 있고, 필요하면 release로 공개할 수 있다는 점입니다. 빌드 내용은 .github/workflows/ 아래의 workflow 파일(YAML)에 정의합니다.

최소 GitHub Actions workflow

다음 YAML을 .github/workflows/build.yml로 두면 동작합니다. actions/checkout이 소스를 가져오고, xu-cheng/latex-action이 컴파일하며, actions/upload-artifact가 PDF를 저장합니다. GitHub Actions의 메이저 버전은 시간이 지나며 올라가므로, 이 예시는 2026년 기준 주요 버전인 checkout v6와 upload-artifact v7을 사용합니다.

# .github/workflows/build.yml
name: Build LaTeX
on: [push]
permissions:
  contents: read
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: xu-cheng/latex-action@v4
        with:
          root_file: main.tex
      - uses: actions/upload-artifact@v7
        with:
          name: PDF
          path: main.pdf

xu-cheng/latex-action은 root_file이 필수이며 기본적으로 pdfLaTeX를 사용합니다. 엔진을 바꾸려면 latexmk_use_xelatex: true 또는 latexmk_use_lualatex: true를 지정합니다. upLaTeX + dvipdfmx처럼 더 세부적인 절차가 필요한 workflow는 .latexmkrc를 저장소에 커밋하고 action이 로컬 빌드와 같은 설정을 읽게 하면 로컬과 CI의 차이를 줄일 수 있습니다.

이 YAML은 “PDF를 만들 수 있는가”를 확인하는 최소 형태입니다. 학위논문이나 공동 연구 원고에서는 push뿐 아니라 pull_request에서도 실행해, 검토 전에 깨진 PDF가 섞이지 않게 합니다. Action의 메이저 버전은 올라가므로, 오래 쓰는 템플릿이라면 의존성 업데이트 PR을 받거나 매년 공식 README를 확인할 날짜를 정해 둡니다.

TeX Live 환경 — texlive/texlive 이미지

빌드에는 TeX Live가 필요하고, latex-action은 이를 내부에 포함합니다. 환경을 세밀하게 제어하고 싶을 때(특정 package, 일본어 등)는 Island of TeX가 제공하는 texlive/texlive Docker 이미지를 직접 사용할 수 있습니다. latest는 계속 갱신되므로, 재현성이 중요한 제출물은 날짜가 붙은 tag나 TeX Live 연도 tag에 고정하고, 일상적인 검증에는 latest를 쓰는 식으로 나누면 다루기 쉽습니다. job의 container:로 지정하고 latexmk를 직접 실행하는 형태입니다.

jobs:
  build:
    runs-on: ubuntu-latest
    container: texlive/texlive:latest
    steps:
      - uses: actions/checkout@v6
      - run: latexmk -pdf main.tex
      - uses: actions/upload-artifact@v7
        with:
          name: PDF
          path: main.pdf

CI가 실패하면 로그 읽기

CI 실패는 먼저 LaTeX 오류, 누락된 package, 잘못된 artifact 경로라는 세 갈래로 나눕니다. 로그에 ! LaTeX Error나 Undefined control sequence가 보이면 문서 쪽을 디버그합니다. File ... not found가 TeX Live package 부족을 뜻한다면 이미지나 설치 단계를 조정합니다. upload-artifact가 파일이 없다고 하면 path:와 실제 출력 파일명을 확인합니다. 로컬에서는 통과하지만 CI에서만 실패하면, 로컬에만 있는 폰트, 이미지, 생성된 .bbl 파일에 의존하는지 의심합니다.

PDF를 artifact와 release로

• actions/upload-artifact로 저장한 PDF는 workflow run 페이지에서 다운로드할 수 있습니다(실행마다 보관).
• 공개 버전을 배포하려면 PDF를 GitHub Release에 첨부할 수도 있습니다(예: tag push로 트리거).
• 일본어 문서는 texlive/texlive 컨테이너 안에서 uplatex + dvipdfmx로 설정한 latexmk로 빌드하는 것이 확실합니다.
• 빌드 설정(.latexmkrc 등)을 저장소에 포함해 로컬과 CI가 같은 단계를 따르게 합니다.
• 제출용 workflow에서는 -halt-on-error를 켜고 로그를 남겨 경고의 원인을 추적할 수 있게 합니다.