Quarto with GitHub Actions + uv

computer-tool
quarto
uv
github
uv를 Actions에서 쓰자
Author

JS HUHH

Published

February 9, 2025

TL; DR

GitHub Actions와 uv를 활용해 GiHub Pages 자동 빌드 및 배포 환경을 구축해보자.

문제; 왜 GitHub Actions에 uv를 올리고자 하는가?

구체적인 사례에서 시작하자. 다음과 같은 툴의 집합으로 (몹시 개인적인) 대시보드를 개발하고 배포하는 작업을 고민중이다.

  • 개발 (가상) 환경; uv
  • 대시 보드 개발 툴; quarto
  • 배포 자동화 툴; GitHub Actions
  • 배포 환경; GitHub Pages

각 툴에 대한 설명은 생략하겠다. 해야 할 일은 다음과 같다.

  • 로컬 개발 환경에서는 uv, quarto, python(jupyter)을 활용해 개발한다.
  • 데이터 업데이트와 배포는 GitHub Actions를 활용해 자동화한다.
    • 이떄 개발 환경에서 uv로 설정한 가상 환경을 Actions에서 그대로 활용한다.
  • Static 페이지 배포는 GitHub Pages를 활용한다.

보통 GitHub Actions는 배포 환경이 제한되기 때문에 requirements.txt를 활용해 pip로 의존성을 확보하고는 했다. conda 등 많이 쓰는 가상 환경이 무겁거나 느린 것도 Actions에서의 활용을 꺼리게 만드는 요소이다. uv라면 어떨까? uv 정도로 가볍고 빠르고 유연한 환경이라면, 개발에서 썼던 가상환경을 그대로 쓰는 것도 가능할 듯 싶다.

GitHub Actions에서 uv 쓰기

Actions에서 간단히 uv를 활용할 수 있다. 여기에서 보듯이 다른 actions 설정과 비슷하게 쓰면 된다. 정작 헤맨 것은 Actions의 다른 단계에서 uv의 가상 환경을 활성화하는 방법이다.

uv 활성화를 위한 actions 스크립트 설정

우선 Quarto에서 Pages를 배포하는 몇가지 방법이 있다. Actions를 활용하기 위해서는 gh-pages 브랜치를 새로 만들어 배포하는 방법을 활용하면 좋다.

최초에 아래 명령어를 실행해서 gh-pages 브랜치를 만들어야 한다.

> quarto publish gh-pages

그런데 로컬에서 실행할 경우 퍼블리시하는 데 시간이 꽤 걸린다. 일정 시간이 지난 이후에도 멈추지 않을 수 있다. Github의 gh-pages의 브랜치 사정을 보면서 업로드가 더이상 되지 않는다고 보이면 그냥 멈추면 된다.

내가 활용한 Actions 스크랩트는 다음과 같다.

on:
  schedule:
    - cron: '0 */3 * * *' # 3시간 마다 00분에 실행 
  #schedule:
    # 실제 스케쥴 작업이 시작될 cron을 등록하면 됩니다.
    # 크론은 https://crontab.guru/ 여기서 확인하면 좋을 것 같습니다.
    # 아래 크론은 매 4시간 마다 실행됩니다.
    #- cron: '* */4 * * *'  
  workflow_dispatch:    
  push:
    branches: main

name: Quarto

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4
#
      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
#
      - name: Install uv
        uses: astral-sh/setup-uv@v5
#
      - name: Activate venv
        run: |
          uv venv --python 3.11
          source .venv/bin/activate
          echo "$PWD/.venv/bin" >> $GITHUB_PATH  # PATH에 가상환경 경로 추가
          echo "VIRTUAL_ENV=$PWD/.venv" >> $GITHUB_ENV # 환경 변수 설정
#    
      - name: Install dependencies
        run: uv sync --all-extras --dev
#      
      - name: publish
        uses: quarto-dev/quarto-actions/publish@v2
        with: 
          target: gh-pages
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}    
          VIRTUAL_ENV: ${{ env.VIRTUAL_ENV }}  # 환경 변수 상속      
#

스크립트의 핵심은 uv를 설치한 후 가상환경의 변수를 quarto 환경으로 넘겨주는 대목이다.

  • 34-35: 가상 환경 경로를 설정하고 이를 환경 변수로 지정한다.
  • 46: Quarto에서 publish를 실행할 때 가상 환경을 활성화한다.

Github Pages 설정

마지막으로 GitHub Pages 설정을 아래 그림처럼 해주어야 한다. Git branch에서 Pages를 배포하며 배포할 브랜치를 gh-pages로 설정한다.

 

Figure 1: GitHub Pages 설정