前回のこれを、 push したら自動で gh-pages の公開までできるように設定する。

前提条件

sphinx プロジェクトのビルドには、docker を使用する
- mikoto2000/sphinx - Docker Hub
こんな感じの sphinx プロジェクトがすでにある

手順

CircleCI でビルドできるように設定

CircleCI 上でプロジェクトを選択

サインアップボタン押下。

パブリックなものしか扱わないし、とりあえずパブリックオンリーで。

GitHub の OAuth でログイン。

パスワード入力。

GitHub の Organization 選択？自分のものを選ぶ。

プロジェクト選択。今回は sphinx プロジェクト。

CircleCI のサイトは開いたまま次の作業を行う。

sphinx プロジェクトに CircleCI 設定ファイルを追加

sphinx プロジェクトに .circleci/config.yml ファイルを作成し、 CircleCI の設定を記述する。

1 ステップ目として、ビルドして、成果物を公開する設定をした。

version: 2
jobs:
  build:
    docker:
      - image: mikoto2000/sphinx
    working_directory: ~/sphinx_gh-pages/work
    steps:
      - checkout
      - run:
          name: Build html
          command: cd work; make html
      - store_artifacts:
          path: work/build/html
          destination: htmls

コミット & プッシュする。

CircleCI でのビルド

CircleCI からビルドを起動する。

Start building ボタン押下。

ビルドが成功すると、下記のように成功ビルドが表示され、Artifact が見られる。 (このスクリーンショットは事後に撮ったので、 gh-pages ブランチが見えているし失敗しているけどそこは無視して)

gh-pages ブランチへ push するための設定

鍵の作成と登録

gh-pages に push するためには、「GitHub に push しようとしているこの CircleCI が、許可されているユーザーか判定する」必要がある。

つまり、 CircleCI に秘密鍵を登録し、 GitHub に公開鍵を登録する。

push 用の鍵作成

msys2 環境で以下コマンドを実行し、鍵を作った。

$ mkdir -p ~/tmp/sshkeys
$ cd ~/tmp/sshkeys
$ # カレントディレクトリに id_rsa という名前で鍵を作る
$ # `-C` はコメントなので適切な感じに
$ ssh-keygen -t rsa -b 4096 -m pem -C circleci-sphinx_gh-pages -f ./id_rsa

CircleCI に秘密鍵を登録

BUILDS -> プロジェクト名右側の設定ボタン押下。

SSH Permissions -> Add SSH Key ボタン押下。

ホスト名と秘密鍵の文字列を入力。

こんな感じでホスト名とフィンガープリントが確認できる。

GitHub に公開鍵を登録

プロジェクトページ -> Settings -> Deploy keys -> Add deploy key と選択していく。

タイトルと、公開鍵の文字列を貼り付け。 push が必要なので、「Allow write access」のチェックを入れる。

パスワード入力。

キー追加が確認できる。

config.yml の更新

gh-pages の config.yml 作成

CircleCI の設定ファイルが無いまま gh-pages ブランチに push してしまうと、それをトリガーに「CircleCI がビルド開始 → 設定ファイルがないから Failed」という嫌な感じになってしまう。それを回避するため、 gh-pages ブランチにビルドスキップ設定をしたファイルを追加する。

.circleci/config.yml を作成し、次のように設定する。

version: 2
jobs:
  build:
    branches:
      ignore:
        - gh-pages

これを push すれば、それ以後 gh-pages に push しても CircleCI のビルドがスキップされる。

master ブランチの config.yml 更新

ワークフローを使って下記処理をしてもらえるように設定を更新する。

build フェーズ(build ジョブ)
- sphinx を使って html をビルドする
deploy フェーズ(deploy ジョブ)
- gh-pages を clone
- 「1.」の成果物を add, commit, push

add_ssh_keys に、 CircleCI に登録した Deploy key の fingerprint(今回でいうと "bd:d3:5c:3d:ff:e9:6b:4e:c3:fd:89:2e:e7:48:67:c9") を設定する。

version: 2
jobs:
  build:
    docker:
      - image: mikoto2000/sphinx
    working_directory: ~/sphinx_gh-pages/work
    steps:
      - checkout
      - run:
          name: Build html
          command: cd work; make html
      - persist_to_workspace:
          root: work/build/html
          paths:
            - ./*
  deploy:
    machine: true
    steps:
      - add_ssh_keys:
          fingerprints:
            - "bd:d3:5c:3d:ff:e9:6b:4e:c3:fd:89:2e:e7:48:67:c9"
      - attach_workspace:
          at: work/build/html
      - run:
          name: Clone gh-pages
          command: git clone -b gh-pages git@github.com:mikoto2000/sphinx_gh-pages.git
      - run:
          name: Delete exists file
          command: rm -rf sphinx_gh-pages/*
      - run:
          name: Copy build results
          command: cp -rf work/build/html/* sphinx_gh-pages
      - run:
          name: Setup git
          command: cd sphinx_gh-pages;git config --local user.name "mikoto2000"; git config --local user.email "mikoto2000@gmail.com"
      - run:
          name: Git push
          command: cd sphinx_gh-pages; git add ./; git commit -m "From `git log --oneline origin/master -n 1`"; git push
workflows:
  version: 2
  build_and_deploy:
    jobs:
      - build:
          filters:
            branches:
              only: master
      - deploy:
          requires:
            - build

成功すると、下図のように

master ブランチの build ジョブが SUCCESS
master ブランチの deploy ジョブが SUCCESS
gh-pages ブランチが SKIPPED

となる。

TODO

[ ] : config.yml などの設定ファイルのみ更新した場合、 deploy ジョブの git commit で失敗することがあるのでどうにかする。
[ ] : CircleCI の環境変数機能を使う
[ ] : ; 区切りでコマンド列挙しているのが格好悪いからどうにかする

参考資料

更新履歴

日付	更新内容
2018/5/21	新規作成
2019/2/8	2019/2/8 時点の ssh-keygen の挙動に合わせて push 用の鍵作成コマンドを修正

mikoto2000 の日記

2018年5月21日月曜日

CircleCI を利用して Sphinx プロジェクトを gh-pages に自動公開する