2019年の11月にGitHub Actionsが正式にリリースされました。 GitHub ActionsはGitHubに組み込まれたCI/CD機能でpush等のGitHub上のイベントをトリガーに任意のアクションを実行できるものです。 GitHub ActionsではDockerが使用できるので、様々な環境上でテストの実行やビルドなどができます。
CIサービスは、他にもAppVeyorやTravis CIがありますが、AppVeyorは無料のプランだと、ワーカーがプロジェクトにつき1つなので、Groongaのように複数のパッケージを作成するためにジョブが多くなるプロジェクトだと、ビルドとテストの完了に時間がかかってしまい効率的ではありませんでした。 GitHub Actionsでは、リポジトリーにつき20まで並列で実行できます。
また、Travis CIでは、ビルドした成果物を保存する場所がデフォルトで用意されていないため、正常にビルドできるかの確認やテスト実行はできますが、リリース用のパッケージを作成して置いておくということがやりにくいです。 GitHub Actionsではアクションを実行した結果、生成されたファイルを置いておく場所がデフォルトで用意されているため、GitHub Actions上でパッケージを作成し、作成したパッケージを取得してリリース用のパッケージとしてアップロードするということがやりやすいです。
上記のようなメリットがあったため、Groongaプロジェクトでは、CI/CDをTravis CIやAppveyorからGitHub Actionsへ移行しています。
いままで、GroongaやMroonga、PGroongaのパッケージは開発者の手元でビルド、署名、アップロードを実施していました。 GroongaとMroongaは毎月末にリリースがあるため、毎月末に開発者はパッケージを作る作業を実施しなければなりません。 また、この際にパッケージの作成に失敗するような問題が発覚すると、問題の修正作業にも追われることになります。
GitHub Actionsはpushトリガーでアクションを実行できるので、変更がリポジトリにpushされた段階でパッケージ作成することで、問題の早期発見に繋がり、問題を発生させた変更もすぐに特定できます。 また、GitHub Actionsでパッケージを作成すると開発者はパッケージを署名、アップロードするだけでよくなるので、毎月発生したパッケージ作成時間をなくし、その時間を別の作業に充てることができます。
GitHub Actionsを活用すると、上記のような様々なメリットが発生するので、GroongaとMroonga、PGroongaのパッケージの作成をGitHub Actionsで行うようにしました。この記事は、その過程で得た知見を共有するために記載しています。
まずは、GitHub Actionsの使い方について記載します。
使い方
GitHub ActionsのアクションはYAML形式で記述します。 YAML形式なので、GitHub上でコードとして管理できます。
ここからは、Groongaのパッケージ作成のアクションを例に説明していきます。 Groongaのパッケージ作成のアクションは、以下の場所にあります。
https://github.com/groonga/groonga/blob/master/.github/workflows/package.yml
トリガー
何のイベントをトリガーにしてアクションを実行するかを決めるには、on:を使います。
Groongaのアクションではpush毎にアクションが実行されてほしいので、on:にはpushを指定します。
on:
push:
GitHub Actionsでは、イベントが起こった対象を指定することができます。
上記のように定義すると、リポジトリーのどのブランチ、タグにpushされてもアクションが実行されます。
全てのブランチやタグが対象ではなく、特定のブランチ、タグにpushされたときだけアクションを実行したい場合は以下のようにします。
on:
push:
branches:
- branch
tags:
- tag
push等のイベントトリガーではなく、定期的に実行したいアクションがあるケースもあります。
その場合には、schedule:を使用します。
schedule:の書式はcronの書式で指定できます。ここで指定した時刻はUTCなので、UTCと時差がある日本の場合は時差を考慮に入れて設定する必要があることに注意してください。
Groongaでは以下のように設定し、毎朝9時にアクションが実行されるようにしています。
schedule:
- cron: |
0 0 * * *
onに指定できるイベントは他にもあり、以下のページにまとまっているので、必要に応じて参考にしてください。
https://help.github.com/en/actions/automating-your-workflow-with-github-actions/events-that-trigger-workflows
アクションの定義
実行するアクションはjobs:という単位で定義できます。
複数のジョブを作成してそれぞれ並列に実行することもできますし、あるジョブの完了を待ってから実行するというようにジョブ同士の依存関係を定義することもできます。
Groongaでは、現状、パッケージを作成するというアクションのみを行っていますので、以下のようにbuildというジョブを1つだけ定義しています。
jobs:
build:
ジョブの中ではいくつかのステップに分けてアクションを定義します。 GitHub Actionsのジョブはステップごとに成功、失敗を表示するので、ジョブをステップに分割しておくと、ジョブが失敗したときの原因特定が容易になります。
Groongaでは、パッケージ作成を以下のステップに分割して実行しています。
-
依存パッケージの配置
-
aptを用いたインストール
-
pip3を用いたインストール(ドキュメントビルド用に使うSphinxをインストールしています)
-
パッケージのビルドに必要なソースコードをClone
-
-
configureの生成
-
ソースアーカイブ作成用にconfigure実行
-
ソースアーカイブをビルド
-
debian/changelogの更新
-
Docker上でパッケージをビルド
-
ビルドされた成果物をGitHubへアップロード
具体的には以下のように定義しています。
name:で分割したステップに名前をつけます。
run:で実行するアクションを定義します。
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- name: Install dependencies
run: |
sudo apt update
sudo apt -V install \
autoconf-archive \
bison \
devscripts \
python3-pip \
ruby
- name: Install Sphinx
run: |
sudo pip3 install -v sphinx
- name: Clone dependencies
run: |
cd ..
git clone --depth 1 https://github.com/groonga/groonga.org.git
git clone --depth 1 https://github.com/clear-code/cutter.git
- name: Generate configure
run: |
./autogen.sh
- name: Configure for archive
run: |
./configure \
--enable-document \
--enable-mruby \
--with-cutter-source-path=../cutter \
--with-groonga-org-path=../groonga.org \
--with-ruby
- name: Build archive
run: |
make dist
- name: Update version
run: |
OLD_RELEASE=$(grep -E -o '[0-9.]+' packages/debian/changelog | \
head -n1)
OLD_RELEASE_DATE_FULL="$(grep '^ -- ' packages/debian/changelog | \
head -n1 | \
sed -E -e 's/ -- .+<[^>]+> //')"
OLD_RELEASE_DATE=$(date --date="${OLD_RELEASE_DATE_FULL}" +%Y-%m-%d)
make update-latest-release \
OLD_RELEASE=${OLD_RELEASE} \
OLD_RELEASE_DATE=${OLD_RELEASE_DATE} \
NEW_RELEASE_DATE=$(date +%Y-%m-%d)
- name: Build with docker
run: |
cd packages
rake ${{ matrix.rake_arguments }}
env:
APACHE_ARROW_REPOSITORY: ../../arrow
- uses: actions/upload-artifact@master
with:
name: packages-${{ matrix.id }}
path: ${{ matrix.repositories_path }}
どのOSでアクションを実行するかはruns-on:で指定します。Groongaではruns-on:ubuntu-latestと定義して、Ubuntuの最新版でアクションが実行されるようにしています。これ以外にも、windows-latest(Windows Serverの最新版)やmacos-latestなどがサポートされています。
実行するコマンドはruns-on:で定義したOSに応じて定義する必要があります。Ubuntuでアクションを実行する場合は、デフォルトでBashが使われるので、Bashで実行できるコマンドを使って定義しています
windows-latestを指定した場合は、デフォルトでアクションがPowerShellで実行されるので、アクションはPowerShellで実行できるコマンドで定義する必要があります。(コマンドプロンプトを使うように指定することもできます。)
アクションを実行するシェルの指定については、以下のページにも説明があるので、必要に応じて参照してください。 https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions#using-a-specific-shell
GitHub Actionsでは、よくある処理をまとめて公開共有することが可能で、それらの処理はsteps:の中で呼び出せます。
Groongaでは、リポジトリからソースコードをチェックアウトするのにactions/checkoutを、ビルドしたパッケージをアップロードするのにactions/upload-artifactを使用しています。
actions/checkoutは@以下にチェックアウトしたいタグやブランチを指定することができます。Groongaでは、masterのソースコードを使いたいので- uses: actions/checkout@masterと指定しています。
actions/checkoutやactions/upload-artifact以外にも様々な処理がactionとして以下のURLで公開されています。
https://github.com/marketplace?type=actions
複数の環境でアクションを実行する
複数の環境(複数のOSであったり、ソフトウェアの複数のバージョン)に対して同じアクションを実行したいケースがあります。 もちろん、それぞれの環境用にワークフローを定義しても良いのですが、同じアクションが複数のワークフローにあると、修正漏れが発生しやすくなってしまい、メンテナンスが煩雑になります。
同じアクションを複数の環境で実行したい場合は、matrix:という定義が使えます。
Groongaも各OS毎にパッケージを作成するため、このmatrix:を使ってDebianの各バージョン(stretchの32bit, 64bit、busterの32bit, 64bit)、CentOSの各バージョン(CentOS 6,7,8)に対して同じアクションを実行しています。
具体的には以下のように定義しています。
strategy:
matrix:
label:
- Debian GNU/Linux stretch amd64
- Debian GNU/Linux stretch i386
- Debian GNU/Linux buster amd64
- Debian GNU/Linux buster i386
- CentOS 6
- CentOS 7
- CentOS 8
include:
- label: Debian GNU/Linux stretch amd64
id: debian-stretch-amd64
rake_arguments: apt:build APT_TARGETS=debian-stretch
repositories_path: packages/apt/repositories/
- label: Debian GNU/Linux stretch i386
id: debian-stretch-i386
rake_arguments: apt:build APT_TARGETS=debian-stretch-i386
repositories_path: packages/apt/repositories/
- label: Debian GNU/Linux buster amd64
id: debian-buster-amd64
rake_arguments: apt:build APT_TARGETS=debian-buster
repositories_path: packages/apt/repositories/
- label: Debian GNU/Linux buster i386
id: debian-buster-i386
rake_arguments: apt:build APT_TARGETS=debian-buster-i386
repositories_path: packages/apt/repositories/
- label: CentOS 6
id: centos-6
rake_arguments: yum:build YUM_TARGETS=centos-6
repositories_path: packages/yum/repositories/
- label: CentOS 7
id: centos-7
rake_arguments: yum:build YUM_TARGETS=centos-7
repositories_path: packages/yum/repositories/
- label: CentOS 8
id: centos-8
rake_arguments: yum:build YUM_TARGETS=centos-8
repositories_path: packages/yum/repositories/
strategy:の中にmatrix:を定義します。matrix:の中に変数を定義してそれをsteps:の中で${{matrix.xx.xx}}の形で参照できます。
例えば、Groongaの場合各OS向けのパッケージでビルドしたパッケージの格納場所が異なるため、${{ matrix.repositories_path }}を参照して各OSごとのパッケージをアップロードできるようにしています。
${{ matrix.repositories_path }}とすると、matrix:の定義の中にあるrepositories_path:を参照するので、
- uses: actions/upload-artifact@master
with:
name: packages-${{ matrix.id }}
path: ${{ matrix.repositories_path }}
は、packages/apt/repositories/とpackages/yum/repositories/配下のファイルをアップロードしていることになります。
まとめ
Groongaのパッケージ作成に使っている内容を中心にGituHub Actionsを使ったパッケージ作成の自動化の方法について記載しました。 GitHub Actionsに興味はあるが、使っていないという方は、この記事に記載されている内容を参考にして自身のプロジェクトで使用してみてはいかがでしょうか。
