GitHub Pages를 무료로 사용하여 프라이빗 저장소 배포하기

서문

최근 Github Pages와 Github Actions를 함께 사용하는 방법을 연구해보았는데, 개인 블로그 운영에 매우 적합하다고 생각되어 이 글을 작성하게 되었습니다.

기존에는 블로그 소스 코드를 리포지토리에 직접 올리고 Github Pages에서 제공하는 기본 Jekyll을 사용하면서 커스텀 도메인을 설정했습니다. 하지만 이 방식에는 다음과 같은 문제점들이 있었습니다:

1. 소스 코드를 숨길 수 없음. _post 디렉토리에 있는 글들은 누구나 자유롭게 복사하여 자신의 콘텐츠로 사용할 수 있습니다.
2. 수정 기록을 숨길 수 없음. 블로그에서 일부 내용을 삭제하더라도, 다른 사람들은 리포지토리 소스 코드의 히스토리를 통해 해당 파일의 변경 내역을 확인할 수 있어 모든 수정 사항이 노출됩니다.
3. Gitalk 사용 불가. 위 두 문제는 Github Pro 이상의 유료 계정으로 해결할 수 있지만(이 경우 프라이빗 리포지토리에서 Github Pages 사용이 가능), 이렇게 되면 issue에 댓글을 작성해야 하는 Gitalk과 같은 도구를 사용할 수 없게 됩니다.
4. 로컬과 온라인 빌드 결과 불일치 또는 오류 발생 시 문제 해결 불가. Github Pages에서 제공하는 Jekyll은 블랙박스 형태로 제공되기 때문에 문제를 추적할 수 없습니다.
5. 일부 커스텀/서드파티 플러그인 사용 불가. Github Pages는 일부 플러그인만 지원하기 때문에, 홈페이지뿐만 아니라 카테고리별 글도 페이지네이션할 수 있는 jekyll-paginate v2와 같은 플러그인은 사용할 수 없습니다.

위와 같은 이유로, 저는 컴파일된 소스 코드를 Github Pages의 내용으로 사용하기로 결정했으며, 원본 소스 코드는 사용하지 않기로 했습니다. 블로그 저장소에는 이미 Gitalk으로 생성된 일부 issue 댓글이 있었기 때문에, 새로운 저장소를 생성하여 원본 소스 코드를 보관하는 곳으로 설정하고 비공개로 설정했습니다. 그리고 기존 저장소는 여전히 Github Pages로 게시하는 저장소로 유지하되, 컴파일된 소스 코드만 게시하도록 했습니다. 이렇게 하면 원래의 댓글 데이터를 보존할 수 있을 뿐만 아니라, 앞서 언급한 여러 문제를 피할 수 있습니다. 제가 매번 소스 코드를 컴파일하여 Github Pages에 게시할 때 force 푸시를 사용하기 때문에 파일 수정 기록을 확인할 수 없어, 어느 정도 프라이버시를 보호하고 복제 비용을 증가시킬 수 있습니다. 아래는 이 과정에 대한 설명입니다.

전체 프로세스

기본적인 프로세스는 다음과 같습니다. 기존 저장소를 A라고 하고, 새로운 원본 소스 코드를 보관하는 비공개 저장소를 B라고 가정합니다. 새로운 푸시가 발생하면 B 저장소의 Github Actions가 트리거되고, 해당 Actions는 컴파일된 소스 코드, 즉 _site 폴더의 내용을 A 저장소로 푸시합니다. A 저장소는 이미 Github Pages로 설정되어 있고 사용자 정의 도메인이 구성되어 있기 때문에 추가적인 처리가 필요하지 않습니다.

상세 과정

Github Actions에서 몇 가지 개념을 명확히 이해해야 합니다:

계층 구조

크기 순서대로 다음과 같습니다:

1. 스크립트 자체: actions에서 실행될 ci.yml 파일 자체입니다.
2. 작업: 구성된 jobs로, jobs는 기본적으로 병렬로 실행되며 needs 키워드를 사용하여 다른 jobs에 대한 의존성을 설정할 수 있습니다.
3. 단계: steps로, jobs에서 실행되는 각 단계이며 순차적으로 실행됩니다. 각 step은 자신의 환경 컨텍스트에서 실행됩니다. 하나의 jobs에는 무제한의 steps가 있을 수 있습니다.
4. 액션: 모든 steps가 액션을 실행하는 것은 아니지만, 액션은 steps 내에서 실행되는 구체적인 명령입니다. 예를 들어 현재 디렉토리 출력, 의존성 설치 등이 있습니다.

다른 사람의 step 사용하기

Action을 사용하면 다른 사람이 작성한 step을 활용할 수 있어 직접 작성할 필요가 없습니다. 예를 들어, 브랜치를 체크아웃해야 하는 경우 다음과 같이 간단히 처리할 수 있습니다:

1
2
3
4

- uses: actions/checkout@v2
    with:
        persist-credentials: fasle # false 是用 personal token，true 是使用 GitHub token
        fetch-depth: 0

with는 관련 매개변수이며, 해당 step의 설명에서 자세한 내용을 확인할 수 있습니다.

데이터 암호화

ci 파일에서 Personal Token이나 기타 민감한 데이터가 공개되는 것을 원치 않을 것입니다. 따라서 암호화 후 이름으로 참조하는 방식을 사용해야 합니다. 여기서 주의할 점은 암호화 데이터 간의 차이입니다:

1. GITHUB_TOKEN: 자신의 저장소에서 빌드나 actions 작업만 수행하는 경우, 저장소 설정에서 별도의 조치가 필요하지 않습니다. actions가 실행될 때 Github은 자동으로 GITHUB_TOKEN이라는 환경 변수를 생성하며, 현재 저장소에 코드를 푸시하는 등 인증이 필요한 곳에서 사용할 수 있습니다.
2. Personal Token: 현재 ci가 A 저장소에서 실행되지만 B 저장소에 작업을 수행해야 하는 경우, B 저장소 관리자가 생성한 Personal Token이 필요하며 일부 권한을 할당하면 됩니다.
3. 사용자 정의 암호화: 두 번째 단계에서 B 저장소에 Personal Token이 생성되었다면, A 저장소에서 이를 어떻게 사용할까요? 이때 secret(사용자 정의 암호화)를 활용해야 합니다. A 저장소 설정에서 B_REPO_TOKEN과 같은 변수 이름을 정의한 후, 앞서 얻은 Personal Token을 복사해 넣으면 secret.B_REPO_TOKEN 방식으로 참조할 수 있습니다.

구체적인 단계

위에서 이미 상세히 설명했으므로, 아래에서는 파일을 나열하고 각각을 분석하겠습니다. 필요할 때 해당 내용을 복사하여 약간 수정하면 됩니다:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

# 该 ci 的名字，可以在仓库的 Github Actions tab 看到
name: Blog Generator

# 触发时机
on:
  # 代码 push 到 master 分支的时候运行该 workflow
  # TODO：不运行 commit 信息中包含特定关键词的 push
  push:
    branches: [master]

jobs:
  # build-and-push 是 jobs 名字，随便取，可以有多个 jobs 默认并行
  build-and-push:
    runs-on: ubuntu-latest # 该 jobs 运行的环境
    steps:
      # 首先一般都是 checkout 当前的仓库代码，用官方的 actions/checkout@v2
      - uses: actions/checkout@v2
        with: # with 表示所需要的参数
          persist-credentials: fasle # false 是用 personal token，true 是使用 GitHub token
          fetch-depth: 0 # 保证能够 push 成功

      # 设置 ruby 环境，这里用的也是官方的 actions
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 2.6

      # 安装依赖
      - name: Install dependencies # 操作名字，会显示在 Github Actions 的任务输出界面，方便你 debug
        run: bundle install # 运行的命令

      # 打包静态资源
      - name: Build Pages
        run: bundle exec jekyll build

      - name: Add Message
        working-directory: ./_site # jekyll 默认 build 到 _site 目录，因此设置命令执行的目录为 ./_site
        run: | # run 后面加个 ‘|’ 然后换行可以同时执行多个命令，每行一个
          echo "www.xheldon.com" > CNAME
          echo -e "# [Xheldon's Tech blog](https://www.xheldon.com)" > README.md

      - name: Commit and Push # 将打包后的位于 _site 目录的文件 push 到 A 仓库即可
        working-directory: ./_site
        run: |
          git init
          git checkout -b master
          git add -A
          git -c user.name='github actions by ${{github.actor}}' -c user.email='NO' commit -m 'update' 
          git push "https://{%raw%}${{github.actor}}:${{secrets.X_BLOG_SITE}}{%endraw%}@github.com/Xheldon/x_blog.git" HEAD:master -f -q

여기서 마지막 단계에 대해 설명이 필요한데, X_BLOG_SITE은 제가 정의한 암호화 데이터로, 값은 설정된 Personal Token입니다. 또한 원격 저장소에 push할 때, 해당 CI가 현재 저장소만 조작한다면 저장소 이름을 하드코딩하지 않고 환경 변수를 다음과 같이 작성할 수 있습니다:

1

git push "https://{%raw%}${{github.actor}}:${{secrets.GITHUB_TOKEN}}@github.com/${{github.repository}}{%endraw%}.git" HEAD:master -f -q

즉 github.XXX를 사용하여 관련 정보를 참조할 수 있으며, 여기에서 더 많은 컨텍스트 매개변수 설명을 확인할 수 있습니다.

travis와의 차이점

이전에 Travis를 사용한 적이 있는데, 두 가지의 개념은 기본적으로 거의 비슷합니다. 가장 눈에 띄는 차이점은 Github Actions는 다른 사람이 작성한 actions를 참조할 수 있도록 허용한다는 점입니다. 이는 마치 다른 사람의 패키지를 'require’할 수 있는 것과 같아서, 해당 패키지를 유지보수할 필요 없이 바로 사용할 수 있습니다. 따라서 활용 방법이 더 다양하고 설정도 더 적으며 재사용성도 더 높습니다.

• 이전 글
  블로그 최적화 팁
• 다음 글
  「번역」ProseMirror의 협업 편집 구현