はじめに
CI/CD ジョブがプロジェクトごとにコピペされてメンテナンスが大変…
そんな経験はありませんか?
- 複数のサービスで同じジョブ定義(デプロイや通知など)を使っている
- 定義を変えたいが、いちいち全プロジェクトの
.gitlab-ci.ymlを直すのが面倒 - テンプレートとして切り出したいが、どうやってやるのかよく分からない
本記事では、GitLab CI の共通ジョブを別リポジトリにテンプレート化し、複数プロジェクトから include: で呼び出して再利用する方法をご紹介します。
想定読者
- GitLab CI を使って複数プロジェクトを運用している方
-
.gitlab-ci.ymlの共通化・メンテナンス性に悩んでいる方 - チームや組織全体で CI の品質を統一したい方
1. なぜテンプレート化するのか?
プロジェクトごとに同じ処理をコピーしていると、以下のような問題が起こります。
- 変更のたびに全プロジェクトへ修正が必要
- 記述ミスや更新漏れが発生しやすい
- CIのルール・標準がバラバラになる
一方、共通ジョブを テンプレートとして別リポジトリで管理すれば:
- ✅ 一元管理できる
- ✅ バージョン管理できる(
ref:) - ✅ 品質が揃う
2. 例:EC2 に git pull を実行するデプロイジョブ
ここでは、GitLab CI から AWS Systems Manager (SSM) を使って、EC2 インスタンス上で git pull を実行するジョブを共通テンプレート化する例を紹介します。
テンプレート構成(別リポジトリ)
gitlab-ci-templates/
├── oidc-assume-role.gitlab-ci.yml # GitLab OIDC による IAM ロール引き受け
└── ssm-git-pull.gitlab-ci.yml # SSM を使って EC2 に git pull 実行
3. テンプレート定義ファイルの中身
oidc-assume-role テンプレート
.oidc-assume-role:
image:
name: amazon/aws-cli:latest
entrypoint: [""]
id_tokens:
GITLAB_OIDC_TOKEN:
aud: https://gitlab.com
before_script:
- |
export $(printf "AWS_ACCESS_KEY_ID=%s AWS_SECRET_ACCESS_KEY=%s AWS_SESSION_TOKEN=%s" \
$(aws sts assume-role-with-web-identity \
--role-arn "${ROLE_ARN}" \
--role-session-name "GitLabRunner-${CI_PROJECT_ID}-${CI_PIPELINE_ID}" \
--web-identity-token "${GITLAB_OIDC_TOKEN}" \
--duration-seconds 3600 \
--query 'Credentials.[AccessKeyId,SecretAccessKey,SessionToken]' \
--output text))
AWSでのOIDC(Open ID Connect)の設定に関する参考記事
ssm-git-pull テンプレート
.ssm-git-pull:
extends: .oidc-assume-role
script:
- |
aws ssm send-command \
--document-name "AWS-RunShellScript" \
--instance-ids $EC2_INSTANCE_ID \
--comment "$COMMENT" \
--parameters commands=["cd $DIR_PATH && git switch $BRANCH && git pull"] \
--region $REGION \
--output text
4. 実際に使うプロジェクト側の .gitlab-ci.yml
include:
- project: your-group/ci-templates
file: gitlab-ci-templates/oidc-assume-role.gitlab-ci.yml
ref: v1.0.0
- project: your-group/ci-templates
file: gitlab-ci-templates/ssm-git-pull.gitlab-ci.yml
ref: v1.0.0
deploy-ec2:
extends: .ssm-git-pull
stage: deploy
variables:
ROLE_ARN: "arn:aws:iam::<ACCOUNT_ID>:role/<ROLE_NAME>"
REGION: "ap-northeast-1"
EC2_INSTANCE_ID: "i-xxxxxxxxxxxxxxxxx"
DIR_PATH: "/var/www/html"
BRANCH: "main"
COMMENT: "Git pull from CI"
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
5. 運用のコツ
- テンプレートを変更したら ref: を bump(例: v1.0.1)
- 本番・開発で異なる変数を使う場合は rules + variables で切替
- 共通テンプレートは専用の GitLab リポジトリで管理する
6. その他の応用例
- Slack 通知
- S3 バケットへのファイルアップロード
- Lambda 実行
- ECS / EKS デプロイ
- Datadog ログ送信
どれもテンプレート化することで CI 設計が楽になります。
まとめ
CI/CD のテンプレート化は、単なる効率化にとどまらず、品質統一・セキュリティ強化・メンテナンス性向上に直結します。
チームや組織で共通するジョブが増えてきたと感じたら、ぜひテンプレート化を検討してみてください!