「GitHubのメインリポジトリをGitHub Actionsに統一したい」「会社がCircleCIからGitLab CIに移行する」—— CI/CDツールを乗り換えるとき、最初の壁は設定ファイルの構文の違いです。jobsの書き方、stepsのネスト、環境変数の渡し方…… 似ているようで細かく違います。 この記事では3つのCIツールの構文対応表と、乗り換え時のつまずきポイントを整理します。
1. 3ツールの設定ファイルの基本構造
まずは、GitHub Actions・CircleCI・GitLab CIで「同じ概念がどう書かれるか」を対応表で俯瞰します。 構文は違っても、やりたいこと（概念）は3ツールでほぼ共通です。
| 概念 | GitHub Actions | CircleCI | GitLab CI |
|---|---|---|---|
| 設定ファイル | .github/workflows/xxx.yml | .circleci/config.yml | .gitlab-ci.yml |
| ジョブ定義 | jobs.xxx | jobs.xxx | xxx:（トップレベル） |
| ステップ実行 | steps: - run: | steps: - run: | script: |
| トリガー | on: | workflows.xxx.jobs.xxx.filters | only: / rules: |
| 環境変数（グローバル） | env: | environment: | variables: |
| 環境変数（秘匿） | secrets | context | CI/CD Variables |
| キャッシュ | actions/cache | restore_cache / save_cache | cache: |
| Docker使用 | container: | docker: | image: |
| 並列ジョブ | strategy.matrix | parallelism | parallel: |
| アーティファクト保存 | actions/upload-artifact | store_artifacts | artifacts: |
この対応表が頭に入っていれば、移行作業の大半は「左の概念を、移行先の列の構文に置き換える」だけになります。 各ツールの細かい構文を横断的に引きたいときは、ぱんだツールズのCI/CD設定比較ツールで対応構文をその場で検索できます。
2. 主な移行パターン（コード例付き）
GitHub Actions → CircleCI の書き換え例
どちらもjobsとstepsを持つので構造は近いですが、 再利用アクションの呼び方とシークレットの渡し方が変わります。
- チェックアウト：
uses: actions/checkout@v4→ CircleCIの組み込みステップ- checkout - 並列展開：
strategy.matrix→ テスト分割ならparallelism、 変数の組み合わせならparameters+matrix - 秘匿情報：
${{ secrets.TOKEN }}→ CircleCIのcontextを割り当てて$TOKENとして参照
GitHub Actions → GitLab CI の書き換え例
こちらは構造が一番大きく変わります。ジョブがトップレベルに移動し、stepsがscriptになるのがポイントです。
- トリガー：
on: push: branches: [main]→rules: - if: $CI_COMMIT_BRANCH == "main" - ジョブとステップ：
jobs.build.steps→ トップレベルのbuild: script: - 環境変数：
env:→variables:（参照は${{ env.VAR }}→$VAR）
この変換でとくに注意したいのはインデントです。GitHub Actionsではjobs:配下にあったジョブが、 GitLab CIではトップレベルへ移るため、コピー後はインデントを1段ぶん浅くする必要があります。
3. よくあるつまずきポイント3選
(1) YAMLインデント地獄
GitLab CIはジョブがトップレベル、GitHub ActionsとCircleCIはjobs:配下という階層の違いがあります。 他ツールからコピーしたジョブをそのまま貼ると、インデントが1段ズレてパースエラーになりがちです。 YAMLはインデントが文法そのものなので、移行時はyamllintやエディタのYAML拡張で 構文を検証しながら進めるのが確実です。
(2) 環境変数の渡し方の違い
GitHub Actionsの${{ env.VAR }}と GitLab CIの$VARは記法が異なります。 GitHub Actionsはワークフロー式（${{ }}）と シェル変数（$VAR）が文脈によって使い分けられるという 二重ルールがあり、これを意識せず$VARに 一括置換すると、条件式やwith内の参照が壊れます。
(3) キャッシュキーの設計
ツールによってキャッシュの永続化の仕組みが違うため、移行後にキャッシュが効かないことがあります。 GitHub Actionsはロックファイルのハッシュをキーに含めるのが定番、CircleCIはrestore_cache/save_cacheの ペアで明示管理、GitLab CIはcache:のkeyとpathsで宣言します。 キー生成ルールが違うと旧キャッシュが復元されず、ビルド時間が逆に伸びることもあるため、 移行直後はキャッシュヒット率を必ずチェックしてください。
4. 移行手順
実際の乗り換えは、次の4ステップで進めると漏れがありません。
- 現行の設定ファイルを分析する — ジョブ・ステップ・環境変数・シークレット・キャッシュ・並列設定を洗い出し、移行対象をリスト化する
- 対応表で構文を読み替える — 本記事の対応表を見ながら、各概念を移行先の構文へ1対1で変換する（GitLab CIならジョブをトップレベルへ・インデント1段浅く）
- シークレット・環境変数を新環境に登録する — 設定ファイルには書けない秘匿情報を、移行先の管理画面（Secrets / Context / CI/CD Variables）に再登録する
- ブランチを使って動作確認する — 検証用ブランチで新設定を走らせ、ジョブの成否・キャッシュ・並列実行を確認してからデフォルトブランチへマージする
構文の読み替えで詰まったら、CI/CD設定比較ツールで「この概念は移行先でどう書くか」をその場で確認できます。すべてブラウザ内で完結するため、 社内リポジトリの設定でも安心して参照できます。
5. まとめ
- 3ツールの概念は同じ、構文だけが違う。対応表で読み替えれば移行作業の大半は機械的に進む
- GitLab CIはジョブがトップレベルでインデントが浅い・stepsがscriptになる、という構造差が最大のポイント
- 環境変数の記法（
${{ env.VAR }}vs$VAR）の違いに注意 - シークレットは設定ファイルとは別に、移行先の管理画面で再登録が必須
- キャッシュキーの設計差で移行後にキャッシュが効かなくなることがあるため、ヒット率を確認する
- 本番にいきなり反映せず、検証用ブランチで動作確認してからマージする