【ITニュース解説】仓库能推之后：内置流水线 YAML 怎么写

システムエンジニアを目指す初心者が、ソフトウェア開発における自動化の仕組み、特に「継続的インテグレーション（CI）と継続的デリバリー（CD）」について学ぶことは、現代の開発現場で非常に重要である。CI/CDパイプラインとは、コードの変更があった際に、自動でコードのビルド、テスト、デプロイといった一連のプロセスを実行する仕組みを指す。これにより、手作業によるミスを減らし、開発サイクルを高速化できる。ここでは、特定のGitサービスであるAngusGitを使って、コードをプッシュするたびに自動でビルドやテストが実行されるようにする「パイプライン」の設定方法を詳しく見ていこう。

まず、AngusGitにおけるパイプラインは、そのサービス独自の文法を使用することに注意が必要だ。これは、例えばGitHub ActionsやGitLab CIといった他の人気のあるCI/CDツールとは互換性がない。そのため、それぞれのツールの使い方を個別に学ぶ必要がある。また、AngusGitのCI/CD機能は、チーム版や企業版でのみ提供されており、無料のコミュニティ版では利用できない点も押さえておくべきだ。パイプラインを実行するには「Runner（ランナー）」と呼ばれる、実際にタスクを実行するマシンが必要となる。Runnerが正しく設定されていないと、パイプラインのタスクがいつまでも「待機中」のまま実行されないため、事前にRunnerをAngusGitに接続しておく必要がある。Runnerの接続は、AngusGitの管理画面から「CI/CD」→「実行器」へ進み、「新規Runner」を選択して行う。この際、Runnerの名前や、AngusGitがRunnerにアクセスするためのアドレス、そして一時的な「トークン」を設定することになる。タスクをDockerコンテナ内で実行する場合は、Dockerが利用可能なRunnerを選択し、適切なタグ（例えば「linux,docker」）を付ける。直接ホストマシン上で実行する場合は、特定のDockerタグは不要で、必要なツール（例えばJDK）がそのマシンにインストールされていることを確認する。

パイプラインの設定ファイルは、基本的にコードと同じリポジトリ内に配置する。配置方法には二つのパターンがある。一つは、リポジリトリのルートディレクトリに.anguscicd.yamlという名前でファイルを置く方法で、これは一つのリポジトリにつき一つのパイプラインを設定する場合に適している。もう一つは、.anguscicd/というディレクトリを作成し、その中にci.yamlやrelease.yamlといった.yamlまたは.yml形式のファイルを複数配置する方法だ。これは、一つのリポジトリで複数のパイプライン（例えば、CI用のパイプラインとリリース用のパイプライン）を管理したい場合に便利である。ファイル名は正確に指定する必要があり、間違った名前（例えば.gitlab-ci.ymlなど）ではAngusGitに認識されない。

次に、実際に動作する最小限のパイプライン設定ファイルを見てみよう。設定ファイルはYAML形式で記述する。ファイルの冒頭には、設定ファイルのバージョンを示すversion: "1"と、パイプラインの名前を定義するname: basic-build-testといったフィールドを記述する。nameは必須項目だ。このパイプラインをいつ自動で実行するかは、triggersセクションで定義する。on: pushと記述すればコードがプッシュされたときに実行され、branches: [main, develop]のように特定のブランチを指定することで、mainやdevelopブランチへのプッシュ時のみ実行されるように制御できる。envセクションでは、パイプライン全体で利用できる環境変数を定義できる。例えばTZ: Asia/Shanghaiでタイムゾーンを設定したり、APP_NAME: AngusCICDといったアプリケーション名を定義したりできる。パイプラインの具体的な処理はpipelineセクションに記述する。このセクションには一つ以上の「Job（ジョブ）」を含める必要がある。Jobは、パイプライン内での一連の処理のまとまりを指す。例えばbuildという名前のJobを作成する場合、その下に実行環境やステップを定義する。 runnerセクションでは、そのJobを実行するRunnerの設定を行う。mode: DOCKERと指定すればDockerコンテナ内で実行され、image: node:20-alpineで利用するDockerイメージを指定する。labels: ["linux", "docker"]は、このJobが実行されるRunnerが持つべきタグを指定する。これにより、特定の機能や環境を持つRunnerにのみJobを割り当てることができる。mode: NATIVEと指定した場合は、Runnerが動作しているホストマシン上で直接コマンドが実行される。stepsセクションには、そのJobで実行される具体的なコマンドを順番にリストアップする。各ステップには必ずname（ステップの名前）とrun（実行するシェルコマンド）を指定する。例えば、name: Show environmentとして、run: | echo "TZ=$TZ"のように環境変数を表示するコマンドや、name: Unit testとしてrun: node --test apps/hello-node/src/index.test.jsのようにユニットテストを実行するコマンドを記述する。各ステップには、最大実行時間を指定するtimeoutも設定できる。AngusGitは、Jobの開始前に自動的にリポジトリのコードをワーキングディレクトリにチェックアウト（取得）してくれるため、明示的にgit cloneのようなコマンドを書く必要はない。このチェックアウトは「浅いクローン」であり、最新のコミットのみを取得し、完全な履歴はダウンロードしない。

一つのJobで全ての処理を行うのではなく、複数のJobに分割して処理を進めることも可能だ。例えば、コードの静的解析（Lint）を行うJob、サービスAをビルドするJob、サービスBをビルドするJobといった形で分割できる。このような場合、Job間の依存関係や実行順序をneedsフィールドで指定する。例えば、build-service-a Jobがneeds: ["lint"]と指定されていれば、lint Jobが成功してからでないとbuild-service-aは実行されない。もしlint Jobが失敗した場合、それに依存するJobは実行されない。複数のJobは異なるRunnerで実行される可能性があり、それぞれのJobは独立した作業ディレクトリを持つ。そのため、一つのJobで生成したファイルを別のJobで直接利用することはできない。このような場合は、ビルド成果物を専用のリポジトリにアップロードし、別のJobでダウンロードするなどの工夫が必要となる。 また、複数のサービスを含むモノレポ（単一リポジトリ）構成の場合、smart.changeAnalysis: trueとmodulesフィールドを組み合わせることで、変更があったディレクトリに関連するJobだけを実行するように設定できる。例えば、apps/service-a/ディレクトリのファイルが変更された場合のみ、build-service-a Jobが実行され、変更がないbuild-service-b Jobはスキップされるといった効率的な運用が可能になる。

パイプラインの自動実行のきっかけとなる「トリガー」にはいくつかの種類がある。on: pushは、git pushコマンドでコードがリポジトリにプッシュされたときに実行される。on: pull_requestは、プルリクエストが作成されたり、そのプルリクエストのソースブランチに新しいコミットがプッシュされたりしたときに実行される。このトリガーは、特定の「ターゲットブランチ」（例えばmain）へのプルリクエストに対してのみ実行されるように設定できる。on: tagは、git pushでタグがリポジトリにプッシュされたときに実行される。そしてon: workflow_dispatchは、AngusGitのコンソールから手動でパイプラインを実行する際に使用するトリガーで、この際に任意の入力パラメータを渡すこともできる。 もしtriggersセクションを全く設定しない場合、そのパイプラインは自動では実行されず、コンソールから手動でトリガーする必要がある。一つ重要な注意点として、on: pushトリガーはgit pushにのみ反応し、AngusGitのプルリクエストページで「マージ」ボタンを押してコードをmainブランチにマージしても、このトリガーは発動しない。そのため、mainブランチにブランチ保護を設定し、プルリクエスト経由でのみマージを許可しているような場合は、マージ前のチェックにはon: pull_requestトリガーを使い、マージ後のビルドは手動で実行するか、別途on: push以外のトリガーを検討する必要がある。

ソフトウェアのリリースや内部APIの呼び出しなど、パイプラインの実行中に秘密情報（例えばAPIトークンやパスワード）が必要になる場合がある。これらの情報をYAMLファイルに直接記述することはセキュリティ上のリスクが高い。そのため、AngusGitでは「憑証（Credentials）」という機能を使って安全に管理する。まず、AngusGitのコンソールで「CI/CD」→「配置」→「凭证」タブへ移動し、「新規凭证」ボタンをクリックして新しい憑証を作成する。ここで、YAMLファイル内で参照する名前（例えばNPM_TOKEN）と、実際のトークン値を入力する。憑証は作成後に値が暗号化され、二度とプレーンテキストで表示されないため、入力間違いに注意が必要だ。憑証の「可視性」を「指定仓库」に設定し、利用するリポジトリを紐付けることで、その憑証がどのリポジトリで利用可能かを制御できる。 次に、この憑証をJob内で利用するために、該当するJobの定義にcredentialsフィールドを追加し、利用したい憑証の名前をリストアップする。例えば、credentials: ["NPM_TOKEN"]と記述する。Jobのsteps内で実行するコマンドからは、定義した憑証名が環境変数として参照できる。例えば$NPM_TOKENと記述することで、その環境変数の値を利用できる。また、envや条件式の中では${{ secrets.NPM_TOKEN }}や${{ credentials.NPM_TOKEN }}といった書き方も可能だが、これらもJobのcredentialsリストに含める必要がある。

YAMLファイルを記述したら、AngusGitでパイプラインを有効にする必要がある。最も簡単な方法は、記述した.anguscicd.yamlファイルを含むコミットを、リポジトリのデフォルトブランチにプッシュすることだ。AngusGitはこれを自動的に認識し、パイプラインを構築してくれる。もう一つの方法は、AngusGitコンソールから手動でパイプラインを作成することだ。「新規流水线」→「空白创建」を選択し、パイプライン名やリポジトリを選択した後、YAML設定を直接貼り付けて保存する。この方法で作成されたパイプラインの設定はAngusGitのプラットフォーム上にのみ保存され、リポジトリのファイルには反映されない。もし後でリポジトリにも同じパスのYAMLファイルが配置された場合、実行時にはトリガーされたブランチにあるファイルが優先される。

パイプラインの設定中にエラーが発生することもある。AngusGitは設定ファイルの検証が厳格で、認識できないフィールドがあればエラーを報告する。よくある間違いとして、GitLab CIやGitHub Actionsの構文（例: stages, variables, jobs）をAngusGitで使ってしまうケースが挙げられる。AngusGitではJobはpipelineの下に配置し、グローバル変数はトップレベルのenv、Jobの順序はneedsで定義する。また、各ステップにnameが必須であるため、これを忘れるとエラーになる。imageの設定はJobの直下ではなくrunner.imageの下に書く必要がある。Jobがいつまでも実行されずに「排隊（キュー）」状態のままになる場合は、Runnerが正しく設定されていないか、Jobが要求するmodeやlabelsと一致するRunnerがオンラインでない可能性がある。憑証関連のエラーは、憑証名の間違い、可視性設定の誤り、または憑証の有効期限切れが原因となることが多い。また、GitLab CIで使われる$CI_COMMIT_SHAのような事前定義変数を使おうとしても、AngusGitでは機能しない。AngusGitでは、GIT_REPO_URL、GIT_BRANCH、GIT_COMMIT_SHAといったAngusGit独自の変数が自動的に提供されるので、これらを利用する必要がある。

よくある疑問として、「パイプラインを実際に実行せずに、設定の検証だけを行いたい」というものがあるが、AngusGitにはそのような「試行実行モード」は提供されていない。安全に設定をテストするには、まずechoコマンドのような単純なステップだけを含むパイプラインを作成し、Runnerが正常にタスクを受け取って実行できることを確認してから、段階的に実際の処理を追加していくのが良い方法だ。複数のJob間でファイルを共有したい場合、Jobはそれぞれ独立した作業ディレクトリを持つため、直接ファイルを渡すことはできない。一般的な解決策としては、ビルドJobで生成された成果物を専用の「成果物リポジトリ」やストレージにアップロードし、次のデプロイJobでそこからダウンロードして利用する方法が挙げられる。もしビルドとデプロイが一連の連続したステップであれば、それらを一つのJob内でまとめて実行することで、ファイル共有の問題を回避できる。また、依存関係のダウンロードに時間がかかり、パイプラインの実行が遅くなるという問題に対しては、「キャッシュ」機能を利用できる。Jobの設定にcacheフィールドを追加し、key（キャッシュを識別するキー）とpaths（キャッシュしたいディレクトリ、例えばnode_modules）を指定することで、次回の実行時に同じキーのキャッシュがあれば、そのディレクトリが自動的に復元され、依存関係の再ダウンロードを省略できる。

まとめると、AngusGitで自動ビルドやテストのパイプラインを設定するには、.anguscicd.yamlファイルを作成し、version: "1"、name、triggers、そしてpipelineの下にJobを記述することが基本となる。各Jobはrunnerで実行環境（Dockerコンテナかホストマシンか）を指定し、stepsで実行するコマンドを順序立ててリストアップする。各ステップには必ずnameを付ける必要がある。コードのチェックアウトはAngusGitが自動で行う。複数のJobを順序立てて実行したい場合はneedsフィールドを利用し、セキュリティ上の理由でAPIトークンなどの秘密情報を使いたい場合は、AngusGitのコンソールで「憑証」を作成し、Jobのcredentialsフィールドでそれを参照することで、安全に利用できる。最後に、on: pushトリガーはgit pushにのみ反応し、プルリクエストのマージ操作では発動しないという点を覚えておくと、トラブルを未然に防げるだろう。これらの基本的な知識を習得し、実践することで、システムエンジニアを目指す初心者はCI/CDパイプラインの構築と運用に関する重要なスキルを身につけることができる。