【ITニュース解説】导入 GitHub Actions 之后：事件、密钥和 Runner 还要对一遍

システム開発において、プログラムのテストやビルド、デプロイといった一連の作業を自動化する仕組みを「CI/CD（継続的インテグレーション・継続的デリバリー）」と呼ぶ。このCI/CDを実現するためのツールの一つに「GitHub Actions」がある。GitHub Actionsは、GitHub上でソースコードが更新されたり、特定のイベントが発生したりしたときに、自動的に決められた処理（ワークフロー）を実行してくれる便利な機能だ。

今回解説する内容は、このGitHub Actionsで作成したワークフローを、「AngusGit」という別のCI/CDツールにインポートする際の注意点と、それに伴う修正作業についてである。システムエンジニアを目指す初心者にとって、異なるCI/CDツール間で設定を移行する際にどのような「壁」があり、それをどう乗り越えるべきかを知る良い機会となるだろう。

まず、AngusGitにGitHub Actionsのワークフローを取り込む手順は比較的簡単だ。AngusGitのCI/CDメニューから「新規流水線（パイプライン）」を選択し、「GitHub Actionsをインポート」を選ぶ。そして、GitHub Actionsのワークフロー定義ファイル（YAML形式）の内容をコピー＆ペーストして「変換」ボタンを押す。これで、AngusGitが理解できる形式の「下書き」が生成される。この記事ではこの下書きを「初稿」と呼ぶ。しかし、この初稿はそのままではAngusGit上で意図した通りに動作しないことが多いため、手動での調整が必須となる。

調整が必要な主なポイントはいくつかある。 一つ目は「トリガーイベント」だ。ワークフローがどのようなきっかけで実行されるかを定義するのがトリガーイベントだが、GitHub Actionsの複雑な設定がAngusGitでは完全に再現されない場合がある。例えば、プルリクエストの特定のタイプ（types）や、プッシュされたタグの種類に関する詳細なフィルタリングは、インポート時に失われる可能性がある。そのため、pull_requestイベントに対して、どのブランチを対象とするか（branches）などを、AngusGitの形式に合わせて手動で追加したり、確認したりする必要がある。pushイベントについても、タグのフィルタリングが期待通りに変換されないことがあるため、意図した通りの条件で実行されるかを確認し、必要であれば修正しなければならない。

二つ目は「シークレット（秘密情報）」の扱いの違いだ。シークレットとは、パスワードやAPIキーなど、公開したくない重要な情報のことである。GitHub Actionsではsecrets.REPO_TOKENのように参照するが、AngusGitにインポートされるとenv.REPO_TOKENのように形式が変わることがある。さらに重要なのは、GitHub Actionsが自動で提供するGITHUB_TOKENのような組み込みのシークレットは、AngusGitには存在しない点だ。AngusGitでは、これらの秘密情報を「憑証（クレデンシャル）」として別途登録する必要がある。これはセキュリティ上非常に重要な作業で、ワークフロー内で利用するシークレットと同じ名前で、AngusGitの「CI/CD → 設定 → 憑証」メニューから手動で作成しなければならない。適切に設定しないと、プログラムのビルドやデプロイといったステップで認証エラーが発生し、処理が失敗してしまう。

三つ目は「ランナー（Runner）」、つまりワークフローを実行するコンピューター環境の設定だ。GitHub Actionsではruns-on: ubuntu-latestのように、GitHubが用意した最新のUbuntu環境を指定できた。しかし、AngusGitにインポートすると、この設定はrunner.mode: NATIVEとlabels: ubuntu-latestに変換される。これは「ubuntu-latestというラベルを持つ自前のマシンで直接実行する」という意味になる。GitHubが提供するような便利なホスト環境はAngusGitにはないため、もし自前のランナーが用意されていない場合、ワークフローはいつまで経っても実行されず、キューに積まれたままになってしまう。この問題を解決するには、AngusGitに対応した独自のランナーをセットアップするか、または実行モードをDOCKER（Dockerコンテナ内で実行）に変更し、必要なツール（JavaやMavenなど）が事前にインストールされたコンテナイメージを指定する必要がある。

四つ目は、GitHub Actionsで利用していた「Marketplace Action」や「リモートAction」の互換性だ。uses: actions/setup-java@v4のように、他のユーザーが作成した便利な機能をGitHub Actionsでは簡単に利用できる。しかし、AngusGitではこれらの外部アクションは自動的には取り込まれない。記事の例ではactions/setup-java@v4が「未マッピング」として削除されてしまっている。もしJavaのバージョン設定など、Marketplace Actionで行っていた処理が必要であれば、そのアクションが行っていたコマンドを一つ一つ手動でワークフローのrunステップに書き出す必要がある。一方で、actions/checkout@v4のように、ソースコードをリポジトリから取得するアクションは、AngusGitが自動的にワークスペースをチェックアウトしてくれるため、インポート後にスキップされる。これはAngusGitの組み込み機能として提供されているため、手動での追加は不要だ。ただし、このチェックアウトは「浅いクローン（shallow clone）」と呼ばれる、最新のコミットのみを取得する方式なので、完全な履歴に依存するgit describe --tagsのようなコマンドは期待通りに動作しない可能性がある。スクリプトを修正して、履歴に依存しない方法でバージョン情報を取得するなどの対応が求められる。

五つ目は「タイムアウト設定」と「条件文」の扱いだ。GitHub Actionsではジョブ全体にtimeout-minutes: 20のようにタイムアウトを設定できるが、AngusGitではこれがジョブレベルで直接は変換されない。そのため、各ステップにtimeout: 1200（秒単位）のように手動で設定し直す必要がある。また、特定の条件でステップを実行するif: github.ref == 'refs/heads/main'のような条件文も注意が必要だ。GitHub Actionsのコンテキスト変数（github.refなど）はAngusGitでは異なる名前（ref、branchなど）に変換されることがある。さらに、ステップレベルのifではrefのようなコンテキスト変数にアクセスできない場合があるため、if条件をジョブレベルに移動させ、if: branch == 'main'のように書き直すことが推奨される。

このように、GitHub ActionsのワークフローをAngusGitにインポートする作業は、単に貼り付けて変換するだけでは完結しない。インポートによって生成される初稿はあくまで「たたき台」であり、トリガーイベント、シークレット、ランナー、アクション、タイムアウト、条件文、そしてスクリプト内部の細かな違いに至るまで、手動で細かく調整し、AngusGitの仕様に合わせる作業が不可欠となる。これは、異なるCI/CDツール間で設定を移行する際に共通して直面する課題であり、システムエンジニアとしてこのような差異を理解し、適切に対処する能力は非常に重要だ。

この記事が、異なるCI/CDツールの世界へと足を踏み入れる初心者の方々にとって、設定移行の複雑さと、それを乗り越えるための具体的な知識の一助となれば幸いである。一つ一つの違いを理解し、焦らず修正を加えていくことで、最終的には意図した通りに自動化されたCI/CDパイプラインを構築できるようになるだろう。