本ドキュメントでは、本リポジトリで使用可能なGitHub Actionsについて記載しています。
目次
昨今のソフトウェア開発では、多機能/高機能で高品質かつ短納期という無理難題な要求に応えるため、開発サイクルの一部(ビルド、テスト、リリースなど)を自動化して継続的に行うCI/CDと呼ばれる手法がよく使われています。
CI(Continuous Integration)では、コードに対して静的解析ツールの実施したり、ビルド・テストを自動化して工数を短縮しつつ品質を維持します。
CD(Continuous Delivery または Continuous Deployment)では、テストされたソフトを自動でリリース(例えばWebシステムなら本番運用環境に反映など)します。
CI/CDを実現するためのツールとしては、Jenkinsのようなオンプレミス型のツールと、GitHub Actionsのようなクラウド型のサービスがあります。
本リポジトリでは、GitHub Actionsを使って以下の処理を行うことができます。
- ドキュメント(mdファイル)の目次更新
- Dockerイメージ/ロボットプログラムのビルド
- Dockerコンテナによるシミュレーション実行
- Dockerイメージのghcr.ioへのプッシュ
GitHub Actionsとは、GitHubが提供するCI/CDサービスです。
GitHub Actionsで行う処理は、「ワークフロー」という単位で実行され、YMAL形式のファイル(.github/workflows/*.yml)に分けて記載します。
YAMLファイルでは、実行する処理をシェルスクリプトのように記述できるため自由度は高いです。
これにより、リポジトリ内の任意のスクリプトファイルを実行することも可能です。
さらに、マーケットプレイスには、便利なアクションがたくさん公開されています。
これらをプラグインのように利用することで、ワークフローの作成がとても楽になります。
ただし、Publicリポジトリでない場合、以下のページのように従量課金制になることに注意が必要です。
また、Publicリポジトリであっても、以下の使用制限があります。
GitHub Actionsの１つのワークフローファイル(.github/workflows/*.yml)は、以下の要素から成っています。
- イベント ... トリガとなるイベント (GitHubへのPushや時刻指定など)
- 環境変数定義 ... ワークフロー内で参照する環境変数定義
- ジョブ ... 1つのランナー(コンテナや仮想マシンのようなもの)で実行するステップの集まり
- ステップ ... 1つ以上のアクションからなる処理の集まり
- アクション ... 実際に実行する各コマンド。マーケットプレイスで公開されたアクションも指定可能
以下が、実際のワークフローのサンプルコードです。
# ワークフロー名(Webブラウザ上に表示される名前)
name: Workflow Name
# 実行トリガーイベントの指定
on:
# GitHubへのプッシュイベント時
push:
# トリガ対象ブランチの指定
branches: [ main ]
# ワークフロー内で利用できる環境変数を定義
env:
SAMPLE_NAME: "Alice"
# 実行する処理
jobs:
Sample-Job:
name: Job Name
runs-on: ubuntu-20.04
steps:
- name: Sample Step1
run: |
# 実行する処理を記載
echo "Hello ${{ env.SAMPLE_NAME }}"
- name: Sample Step2
run: |
# 1つのステップで実行する処理は複数記載可能
date
curl -s 'wttr.in/osaka?lang=ja&1'アクションでの出力結果はブラウザから確認できます。
例えば、サンプルコードの出力結果は以下のようになります。
GitHub Actionsの詳細については、公式ドキュメントを参照して下さい。
前述のように、本リポジトリでは、以下の処理を行うGitHub Actionsを用意しています。
- ドキュメント(mdファイル)の目次更新
- Dockerイメージ/ロボットプログラムのビルド
- Dockerコンテナによるシミュレーション実行
- Dockerイメージのghcr.io(Dockerイメージを公開するサービス)へのプッシュ
ワークフローファイルとしては、以下の2つに分けています。
.github/workflows/update_toc.yml... ドキュメントの自動更新.github/workflows/image-test.yml... 自動ビルド/テスト/ghcr.ioへのプッシュ
以降では、各ワークフローについて説明します。
Startup Guideと本ドキュメントの目次はGitHubにファイルをプッシュした際に自動で作成しています。
該当のワーフローは、.github/workflows/update_toc.ymlに記載しています。
目次の更新には、以下のアクションを利用しています。
まず最初に、Markdownファイルの目次を追加したい箇所に、以下のコードを追加して下さい。
<!-- START doctoc -->
<!-- END doctoc -->次に、.github/workflows/update_toc.ymlにファイルの以下のTARGET_PATHSに、自動作成したいファイルをカンマ区切りで追記して下さい。
steps:
- name: TOC Generator
uses: technote-space/toc-generator@v3
with:
# 目次を更新するファイル
TARGET_PATHS: STARTUP_GUIDE.md,CICD_GUIDE.md
# 目次を作成する最大階層レベル
MAX_HEADER_LEVEL: 3
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# 目次の見出し
TOC_TITLE: '**目次**'追記後、.github/workflows/update_toc.ymlをプッシュすれば、追記したファイルの目次を自動で作成するようになります。
本リポジトリでは、GitHub Actions上でDockerイメージのビルドからシミュレーションによるテストまで実行するワークフローを用意しています。
実行方法としては、Dockerイメージに影響するファイルの変更をGitHubにプッシュした場合の自動実行と、ブラウザを操作して実行する方法があります。
以下のファイル以外の修正をGitHubにプッシュすると、自動でビルドとテストを実行します。
- 'commands/**'
- '.gitignore'
- 'LICENSE'
- '**.md'
プッシュ以外に、ブラウザから以下のフォームで実行することができます。
「Dockerイメージのリリース」に「yes」を指定すれば、ghcr.ioにイメージをプッシュすることができます。
※GitHubへのプッシュによる自動実行ではイメージのリリースは行いません
ただし、Dockerイメージをプッシュするには以下の手順を事前に実施して下さい。
また、プッシュしたDockerイメージを公開するには以下の操作を行って下さい。
自動テストは、自分のロボットが3分間で1点以上取得していれば試験はパスとしています。
3分間というのは実際の実行時間ではなく、Gazeboのシミュレーション時間になります。
テスト終了後、実行したGitHub ActionsのArtifactsからログファイルをダウンロードできます。
自動テスト時に自分のロボットが取得した点数は以下の手順で確認できます。
以下のように、相手ロボット(青)と自分のロボット(赤)が取得した点数を確認することができます。
以下の場合は、相手ロボットが1点、自分のロボットが5点とっていることが分かります。
実行したGitHub ActionsのArtifactsから自動テスト実行時のログファイルをダウンロードできます。
ダウンロードしたログファイル(test_log/testディレクトリ配下)の概要は以下になります。
| ログファイル | 説明 |
|---|---|
| gazebo/* | $HOME/.gazebo/logディレクトリ配下のファイル |
| ros/* | $HOME/.ros/logディレクトリ配下のファイル |
| judge/* | burger_war_kit/judge/logsディレクトリ配下のファイル |
| screenshot/* | 試験実行時の画面キャプチャ画像 |
| sim_with_test.log | burger_war_kit/scripts/sim_with_test.shの出力ログ |
| start_script.log | burger_war_kit/scripts/start.sh or start_test.shの出力ログ |
| judge_server_result.log | 試験終了時に審判サーバから取得した情報(/warState) |
GitHub Actionsの自動テストで行っている主な処理は以下になります。
- burger-war-core/sim/roboイメージのビルド (
docker build) - burger-war-coreコンテナ起動 (
docker run) - ロボコンプロジェクトのビルド (
catkin build) - burger-war-coreのテスト (
scripts/sim_run_test.sh) - burger-war-core/sim/roboイメージのプッシュ ※手動実行で指定時のみ (
docker push)
実際の処理は.github/workflows/image-test.ymlを参照して下さい。
以下、ローカルでの実行環境のイメージです。
ローカル環境では、コンテナ起動時にホストPCの$HOME/catkin_wsディレクトリをマウントしています。
本リポジトリのファイルは、$HOME/catkin_ws/srcディレクトリ配下に配置するため、ホストPC上での変更は、起動中のコンテナにも反映されます。
それにより、burger_war_devディレクトリ配下のファイルを修正したときに、burger-war-devイメージを再ビルドしなくていいようになっています。
以下、GitHub Actionsでの実行環境のイメージです。
GitHub ActionsではGUIを表示するディスプレイがない為、Xvfbという仮想ディスプレイを使用しているという違いがあります。
burger_war_kitのソースコードついては、リポジトリから毎回チェックアウトを行います。
※burger-war-kitイメージはghcr.ioにプッシュされているlatest版を利用します
もし、catkin_ws/src/以下にburger_war_kit/burger_war_dev以外のcatkinパッケージを追加する場合は、.github/workflows/image-test.ymlに追記するようにして下さい。
具体的な手順は次節で説明します。
catkin_ws/src/以下にburger_war_kit/burger_war_dev以外のcatkinパッケージを追加する場合は、.github/workflows/image-test.ymlに以下のように追記して下さい。
※追記場所は、burger_war_kit/burger_war_devをチェックアウトしている前後に追記して下さい
# 追加ライブラリのチェックアウト
- name: Checkout Library Repository
uses: actions/checkout@v2
with:
repository: tysik/obstacle_detector
path: catkin_ws/src/obstacle_detectorrepositoryには、追加したいパッケージのGitHubリポジトリのパスを指定して下さい。
pathには、チェックアウトしたディレクトリ名を指定して下さい。
※親ディレクトリはcatkin_ws/src/から変更しないように注意して下さい
作成したロボットプログラムをビルドするコマンドは、デフォルトではcatkin buildです。
もし変更したい場合は、.github/workflows/image-test.ymlの以下のcatkin buildの部分を修正して下さい。
# ロボコンプロジェクトのビルド
- name: Build Robot Programs
run: |
docker exec -u developer -t ${{ env.IMAGE_NAME }} bash -l -c "catkin build"はじめに読んでおいたほうが良い公式ドキュメントへのリンク集です。
- GitHub Action入門
- GitHub Actions入門： GitHub Actionsの概要・構成要素など
- GitHub Actions の重要な機能： 環境変数やArtifactsの利用方法など
- GitHub Actionsのワークフロー構文： ワークフローに使うYAMLの要素
- ワークフローをトリガーするイベント： トリガイベントのリスト
- 環境変数： デフォルトの環境変数のリストなど
- ワークフロー データを成果物として保存する： Artifactsの詳細
- アクションの検索とカスタマイズ： アクションの検索/使用/カスタマイズ方法など
- 複雑なワークフローを管理する： 依存ジョブやビルドマトリックス、サービスコンテナの利用方法など
- 業務で利用する場合
- 利用規約
- GitHub Actionsの支払いについて： 利用料金など
- 使用制限、支払い、管理： 使用可能なジョブ数など
- JenkinsからGitHub Actionsへの移行： JenkinsとGitHub Actionsの比較
- ワークフローを Organization と共有する： Organizationでのワークフローやシークレットなどの共有方法
- 自分のランナーをホストする： 独自のランナーの利用方法
- GitHub Actions のセキュリティ強化： シークレットの利用方法やセキュリティ対策
自動テストにパスしたイメージをghcr.ioにプッシュするためにはログインする必要があります。
そのため、ユーザー名とパスワードの代わりにPersonal access tokenが必要になります。
事前に各自のGitHubアカウントでPersonal access tokenを作成し、それを各自のリポジトリのシークレットとして登録しておく必要があります。
以下の手順に従って、こちらのページから作成して下さい。
少なくとも以下にチェックを入れて、ページ下部にある[Generate token]をクリックして下さい。
- write:packages
- read:packages
- delete:packages
生成されたPersonal access token(下の画像の黒塗り部分)をコピーして下さい。
各リポジトリで「Settings」→「Secrets」→「New Repository secret」をクリックして下さい。
以下の画面が表示されたら、NameはGHCR_PASSWORD、Valueには先程コピーしたPersonal access tokenの値を入力して、Add secretをクリックしてシークレットを追加して下さい。
同じように、NameがGHCR_USERNAME、Valueは各自のアカウント名のシークレットを追加して下さい。
ghcr.ioにプッシュしたイメージを誰でも利用できるようにするには、イメージを公開する必要があります。
以下にburger-war-roboイメージを公開する手順を示します。
他に公開したいイメージがある場合は、同じ手順で公開して下さい。
上記手順後、以下のように「Private」の記載が消えていることを確認して下さい。
