رفتن به محتوا

Claude Code با GitLab CI/CD

چرا Claude Code را با GitLab به کار ببریم؟

Section titled “چرا Claude Code را با GitLab به کار ببریم؟”
  • ساختِ آنیِ MR: آنچه را نیاز داری توصیف کن، و Claude یک MR کامل با تغییرات و توضیحات پیشنهاد می‌دهد
  • پیاده‌سازیِ خودکار: issueها را با یک دستور یا منشن به کدِ کارآمد تبدیل کن
  • آگاه از پروژه: Claude از دستورالعمل‌های CLAUDE.md و الگوهای موجودِ کدت پیروی می‌کند
  • راه‌اندازیِ ساده: یک job به .gitlab-ci.yml و یک متغیرِ ماسک‌شده‌ی CI/CD اضافه کن
  • آماده برای سازمان‌ها: Claude API، Amazon Bedrock یا Google Vertex AI را انتخاب کن تا نیازهای اقامتِ داده و تدارکات را برآورده کنی
  • به‌صورت پیش‌فرض امن: روی GitLab runnerهای خودت با محافظتِ شاخه و تأییدیه‌هایت اجرا می‌شود

Claude Code از GitLab CI/CD استفاده می‌کند تا کارهای هوش مصنوعی را در job‌های ایزوله اجرا کند و نتایج را از طریق MR به مخزن بازگرداند:

  1. هماهنگیِ رویدادمحور: GitLab به تریگرهای انتخابیِ تو گوش می‌دهد (مثلاً کامنتی که در یک issue، MR یا رشته‌ی بازبینی به @claude منشن می‌زند). job کانتکست را از رشته و مخزن جمع می‌کند، از آن ورودی پرامپت می‌سازد و Claude Code را اجرا می‌کند.

  2. انتزاعِ ارائه‌دهنده (provider): ارائه‌دهنده‌ای را که با محیطت می‌خواند به کار ببر:

    • Claude API (SaaS)
    • Amazon Bedrock (دسترسیِ مبتنی بر IAM، گزینه‌های چند-منطقه‌ای)
    • Google Vertex AI (بومیِ GCP، Workload Identity Federation)
  3. اجرای sandbox‌شده: هر تعامل در یک کانتینر با قواعدِ سخت‌گیرانه‌ی شبکه و فایل‌سیستم اجرا می‌شود. Claude Code دسترسی‌های محدودشده به فضای کاری را اعمال می‌کند تا نوشتن را مهار کند. هر تغییر از مسیرِ یک MR می‌گذرد تا بازبین‌ها diff را ببینند و تأییدیه‌ها همچنان اعمال شوند.

اندپوینت‌های منطقه‌ای را انتخاب کن تا تأخیر را کم کنی و نیازهای حاکمیتِ داده را برآورده کنی، در حالی که از توافق‌های ابریِ موجودت استفاده می‌کنی.

Claude چه کاری می‌تواند بکند؟

Section titled “Claude چه کاری می‌تواند بکند؟”

Claude Code ورک‌فلوهای قدرتمندِ CI/CD را ممکن می‌کند که نحوه‌ی کارت با کد را دگرگون می‌کنند:

  • ساخت و به‌روزرسانیِ MR از روی توضیحاتِ issue یا کامنت‌ها
  • تحلیلِ افتِ کارایی (performance regression) و پیشنهادِ بهینه‌سازی
  • پیاده‌سازیِ قابلیت‌ها مستقیماً در یک شاخه، سپس باز کردنِ یک MR
  • رفعِ باگ‌ها و regressionهایی که با تست‌ها یا کامنت‌ها شناسایی شده‌اند
  • پاسخ به کامنت‌های پیگیری برای تکرار روی تغییراتِ درخواست‌شده

سریع‌ترین راهِ شروع این است که یک job مینیمال به .gitlab-ci.yml اضافه کنی و کلید API‌ات را به‌عنوان یک متغیرِ ماسک‌شده تنظیم کنی.

  1. یک متغیرِ ماسک‌شده‌ی CI/CD اضافه کن

    • به SettingsCI/CDVariables برو
    • ANTHROPIC_API_KEY را اضافه کن (ماسک‌شده، در صورت نیاز protected)
  2. یک job مربوط به Claude به .gitlab-ci.yml اضافه کن

stages:
- ai
claude:
stage: ai
image: node:24-alpine3.21
# Adjust rules to fit how you want to trigger the job:
# - manual runs
# - merge request events
# - web/API triggers when a comment contains '@claude'
rules:
- if: '$CI_PIPELINE_SOURCE == "web"'
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
variables:
GIT_STRATEGY: fetch
before_script:
- apk update
- apk add --no-cache git curl bash
- curl -fsSL https://claude.ai/install.sh | bash
script:
# Optional: start a GitLab MCP server if your setup provides one
- /bin/gitlab-mcp-server || true
# Use AI_FLOW_* variables when invoking via web/API triggers with context payloads
- echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
- >
claude
-p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
--permission-mode acceptEdits
--allowedTools "Bash Read Edit Write mcp__gitlab"
--debug

پس از اضافه کردنِ job و متغیرِ ANTHROPIC_API_KEY، با اجرای دستیِ job از CI/CDPipelines آزمایش کن، یا آن را از یک MR تریگر کن تا Claude بتواند در یک شاخه به‌روزرسانی پیشنهاد دهد و در صورت نیاز یک MR باز کند.

راه‌اندازیِ دستی (توصیه‌شده برای محیطِ production)

Section titled “راه‌اندازیِ دستی (توصیه‌شده برای محیطِ production)”

اگر راه‌اندازیِ کنترل‌شده‌تری را ترجیح می‌دهی یا به ارائه‌دهنده‌های سازمانی نیاز داری:

  1. دسترسیِ ارائه‌دهنده را پیکربندی کن:

    • Claude API: ANTHROPIC_API_KEY را به‌عنوان یک متغیرِ ماسک‌شده‌ی CI/CD بساز و ذخیره کن
    • Amazon Bedrock: پیکربندیِ GitLabAWS OIDC و ساختِ یک IAM role برای Bedrock
    • Google Vertex AI: پیکربندیِ Workload Identity Federation برای GitLabGCP
  2. اعتبارنامه‌های پروژه را برای عملیاتِ GitLab API اضافه کن:

    • به‌صورت پیش‌فرض از CI_JOB_TOKEN استفاده کن، یا یک Project Access Token با اسکوپِ api بساز
    • اگر از PAT استفاده می‌کنی، آن را به‌عنوان GITLAB_ACCESS_TOKEN (ماسک‌شده) ذخیره کن
  3. job مربوط به Claude را به .gitlab-ci.yml اضافه کن (نمونه‌ها را در ادامه ببین)

  4. (اختیاری) تریگرهای منشن‌محور را فعال کن:

    • یک project webhook برای «Comments (notes)» به event listener‌ات اضافه کن (اگر از یکی استفاده می‌کنی)
    • کاری کن که listener وقتی کامنتی شامل @claude است، pipeline trigger API را با متغیرهایی مثل AI_FLOW_INPUT و AI_FLOW_CONTEXT فراخوانی کند

در یک کامنتِ issue:

@claude implement this feature based on the issue description

Claude، issue و کدبیس را تحلیل می‌کند، تغییرات را در یک شاخه می‌نویسد و یک MR برای بازبینی باز می‌کند.

در یک بحثِ MR:

@claude suggest a concrete approach to cache the results of this API call

Claude تغییرات را پیشنهاد می‌دهد، کد را با کشینگِ مناسب اضافه می‌کند و MR را به‌روز می‌کند.

در یک کامنتِ issue یا MR:

@claude fix the TypeError in the user dashboard component

Claude باگ را پیدا می‌کند، یک رفع پیاده می‌کند و شاخه را به‌روز می‌کند یا یک MR جدید باز می‌کند.

استفاده با Amazon Bedrock و Google Vertex AI

Section titled “استفاده با Amazon Bedrock و Google Vertex AI”

برای محیط‌های سازمانی، می‌توانی Claude Code را به‌طور کامل روی زیرساختِ ابریِ خودت اجرا کنی، با همان تجربه‌ی توسعه‌دهنده.

پیش از راه‌اندازیِ Claude Code با Amazon Bedrock، به این‌ها نیاز داری:

  1. یک حسابِ AWS با دسترسیِ Amazon Bedrock به مدل‌های موردنظرِ Claude
  2. GitLab که به‌عنوان یک OIDC identity provider در AWS IAM پیکربندی شده باشد
  3. یک IAM role با دسترسی‌های Bedrock و یک trust policy محدودشده به project/refs‌های GitLab تو
  4. متغیرهای CI/CD مربوط به GitLab برای assume کردنِ role:
    • AWS_ROLE_TO_ASSUME (ARN مربوط به role)
    • AWS_REGION (منطقه‌ی Bedrock)

دستورالعملِ راه‌اندازی

Section titled “دستورالعملِ راه‌اندازی”

AWS را طوری پیکربندی کن که به job‌های GitLab CI اجازه دهد از طریق OIDC یک IAM role را assume کنند (بدون کلیدهای ثابت).

راه‌اندازیِ لازم:

  1. Amazon Bedrock را فعال کن و برای مدل‌های هدفِ Claude درخواستِ دسترسی بده
  2. اگر هنوز وجود ندارد، یک IAM OIDC provider برای GitLab بساز
  3. یک IAM role که موردِ اعتمادِ OIDC provider مربوط به GitLab است بساز و آن را به پروژه و protected refs‌ات محدود کن
  4. دسترسی‌های least-privilege را برای Bedrock invoke APIها به آن متصل کن

مقادیرِ لازم برای ذخیره در متغیرهای CI/CD:

  • AWS_ROLE_TO_ASSUME
  • AWS_REGION

متغیرها را در Settings → CI/CD → Variables اضافه کن:

# For Amazon Bedrock:
- AWS_ROLE_TO_ASSUME
- AWS_REGION

از نمونه job مربوط به Amazon Bedrock در بالا استفاده کن تا job token مربوط به GitLab را در زمانِ اجرا با اعتبارنامه‌های موقتِ AWS تبادل کنی.

در ادامه قطعه‌کدهای آماده‌ی استفاده‌ای هستند که می‌توانی برای pipeline‌ات تطبیق دهی.

فایلِ پایه‌ی .gitlab-ci.yml (Claude API)

Section titled “فایلِ پایه‌ی .gitlab-ci.yml (Claude API)”
stages:
- ai
claude:
stage: ai
image: node:24-alpine3.21
rules:
- if: '$CI_PIPELINE_SOURCE == "web"'
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
variables:
GIT_STRATEGY: fetch
before_script:
- apk update
- apk add --no-cache git curl bash
- curl -fsSL https://claude.ai/install.sh | bash
script:
- /bin/gitlab-mcp-server || true
- >
claude
-p "${AI_FLOW_INPUT:-'Summarize recent changes and suggest improvements'}"
--permission-mode acceptEdits
--allowedTools "Bash Read Edit Write mcp__gitlab"
--debug
# Claude Code will use ANTHROPIC_API_KEY from CI/CD variables

نمونه job مربوط به Amazon Bedrock (OIDC)

Section titled “نمونه job مربوط به Amazon Bedrock (OIDC)”

پیش‌نیازها:

  • Amazon Bedrock فعال‌شده با دسترسی به مدل(های) انتخابیِ Claude
  • OIDC مربوط به GitLab که در AWS با یک role پیکربندی شده که به project و refs‌های GitLab تو اعتماد دارد
  • یک IAM role با دسترسی‌های Bedrock (least privilege توصیه می‌شود)

متغیرهای لازمِ CI/CD:

  • AWS_ROLE_TO_ASSUME: ARN مربوط به IAM role برای دسترسی به Bedrock
  • AWS_REGION: منطقه‌ی Bedrock (مثلاً us-west-2)
claude-bedrock:
stage: ai
image: node:24-alpine3.21
rules:
- if: '$CI_PIPELINE_SOURCE == "web"'
before_script:
- apk add --no-cache bash curl jq git python3 py3-pip
- pip install --no-cache-dir awscli
- curl -fsSL https://claude.ai/install.sh | bash
# Exchange GitLab OIDC token for AWS credentials
- export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"
- if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi
- >
aws sts assume-role-with-web-identity
--role-arn "$AWS_ROLE_TO_ASSUME"
--role-session-name "gitlab-claude-$(date +%s)"
--web-identity-token "file://$AWS_WEB_IDENTITY_TOKEN_FILE"
--duration-seconds 3600 > /tmp/aws_creds.json
- export AWS_ACCESS_KEY_ID="$(jq -r .Credentials.AccessKeyId /tmp/aws_creds.json)"
- export AWS_SECRET_ACCESS_KEY="$(jq -r .Credentials.SecretAccessKey /tmp/aws_creds.json)"
- export AWS_SESSION_TOKEN="$(jq -r .Credentials.SessionToken /tmp/aws_creds.json)"
script:
- /bin/gitlab-mcp-server || true
- >
claude
-p "${AI_FLOW_INPUT:-'Implement the requested changes and open an MR'}"
--permission-mode acceptEdits
--allowedTools "Bash Read Edit Write mcp__gitlab"
--debug
variables:
AWS_REGION: "us-west-2"

نمونه job مربوط به Google Vertex AI (Workload Identity Federation)

Section titled “نمونه job مربوط به Google Vertex AI (Workload Identity Federation)”

پیش‌نیازها:

  • Vertex AI API فعال در پروژه‌ی GCP تو
  • Workload Identity Federation پیکربندی‌شده برای اعتماد به OIDC مربوط به GitLab
  • یک service account با دسترسی‌های Vertex AI

متغیرهای لازمِ CI/CD:

  • GCP_WORKLOAD_IDENTITY_PROVIDER: نامِ کاملِ منبعِ provider
  • GCP_SERVICE_ACCOUNT: ایمیلِ service account
  • CLOUD_ML_REGION: منطقه‌ی Vertex (مثلاً us-east5)
claude-vertex:
stage: ai
image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
rules:
- if: '$CI_PIPELINE_SOURCE == "web"'
before_script:
- apt-get update && apt-get install -y git && apt-get clean
- curl -fsSL https://claude.ai/install.sh | bash
# Authenticate to Google Cloud via WIF (no downloaded keys)
- >
gcloud auth login --cred-file=<(cat <<EOF
{
"type": "external_account",
"audience": "${GCP_WORKLOAD_IDENTITY_PROVIDER}",
"subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
"service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${GCP_SERVICE_ACCOUNT}:generateAccessToken",
"token_url": "https://sts.googleapis.com/v1/token"
}
EOF
)
- gcloud config set project "$(gcloud projects list --format='value(projectId)' --filter="name:${CI_PROJECT_NAMESPACE}" | head -n1)" || true
script:
- /bin/gitlab-mcp-server || true
- >
CLOUD_ML_REGION="${CLOUD_ML_REGION:-us-east5}"
claude
-p "${AI_FLOW_INPUT:-'Review and update code as requested'}"
--permission-mode acceptEdits
--allowedTools "Bash Read Edit Write mcp__gitlab"
--debug
variables:
CLOUD_ML_REGION: "us-east5"

یک فایلِ CLAUDE.md در ریشه‌ی مخزن بساز تا استانداردهای کدنویسی، معیارهای بازبینی و قواعدِ مخصوصِ پروژه را تعریف کنی. Claude این فایل را در حین اجراها می‌خواند و هنگام پیشنهادِ تغییرات از قراردادهای تو پیروی می‌کند.

هرگز کلیدهای API یا اعتبارنامه‌های ابری را در مخزنت کامیت نکن. همیشه از متغیرهای CI/CD مربوط به GitLab استفاده کن:

  • ANTHROPIC_API_KEY را به‌عنوان یک متغیرِ ماسک‌شده اضافه کن (و در صورت نیاز آن را protect کن)
  • هرجا که ممکن است از OIDC مخصوصِ ارائه‌دهنده استفاده کن (بدون کلیدهای بادوام)
  • دسترسی‌های job و خروجیِ شبکه را محدود کن
  • MR‌های Claude را مثل هر مشارکت‌کننده‌ی دیگری بازبینی کن
  • CLAUDE.md را متمرکز و مختصر نگه دار
  • توضیحاتِ روشنِ issue/MR بده تا تعدادِ تکرارها کم شود
  • timeoutهای منطقی برای job تنظیم کن تا از اجراهای لجام‌گسیخته جلوگیری کنی
  • هرجا که ممکن است نصب‌های npm و پکیج‌ها را در runnerها کش کن

هنگام استفاده از Claude Code با GitLab CI/CD، از هزینه‌های مرتبط آگاه باش:

  • زمانِ GitLab Runner:

    • Claude روی GitLab runnerهای تو اجرا می‌شود و دقایقِ محاسباتی مصرف می‌کند
    • برای جزئیات، صورت‌حسابِ runner در پلنِ GitLab‌ات را ببین
  • هزینه‌های API:

    • هر تعاملِ Claude بسته به اندازه‌ی پرامپت و پاسخ توکن مصرف می‌کند
    • مصرفِ توکن بسته به پیچیدگیِ کار و اندازه‌ی کدبیس متفاوت است
    • برای جزئیات قیمت‌گذاریِ Anthropic را ببین
  • نکاتِ بهینه‌سازیِ هزینه:

    • از دستورهای مشخصِ @claude استفاده کن تا نوبت‌های غیرضروری کم شوند
    • مقادیرِ مناسبی برای max_turns و timeout مربوط به job تنظیم کن
    • هم‌زمانی (concurrency) را محدود کن تا اجراهای موازی را کنترل کنی
  • هر job در یک کانتینرِ ایزوله با دسترسیِ شبکه‌ی محدود اجرا می‌شود
  • تغییراتِ Claude از مسیرِ MR می‌گذرند تا بازبین‌ها هر diff را ببینند
  • محافظتِ شاخه و قواعدِ تأییدیه روی کدِ تولیدشده با هوش مصنوعی اعمال می‌شوند
  • Claude Code از دسترسی‌های محدودشده به فضای کاری استفاده می‌کند تا نوشتن را مهار کند
  • هزینه‌ها زیرِ کنترلِ تو می‌مانند، چون اعتبارنامه‌های ارائه‌دهنده‌ی خودت را به کار می‌بری

Claude به دستورهای @claude پاسخ نمی‌دهد

Section titled “Claude به دستورهای @claude پاسخ نمی‌دهد”
  • بررسی کن که pipeline‌ات تریگر می‌شود (دستی، رویدادِ MR، یا از طریق یک note event listener/webhook)
  • مطمئن شو که متغیرهای CI/CD (ANTHROPIC_API_KEY یا تنظیماتِ ارائه‌دهنده‌ی ابری) موجود و در دسترس‌اند
  • بررسی کن که کامنت شاملِ @claude باشد (نه /claude) و تریگرِ منشنت پیکربندی شده باشد

job نمی‌تواند کامنت بنویسد یا MR باز کند

Section titled “job نمی‌تواند کامنت بنویسد یا MR باز کند”
  • مطمئن شو CI_JOB_TOKEN دسترسیِ کافی برای پروژه دارد، یا از یک Project Access Token با اسکوپِ api استفاده کن
  • بررسی کن که ابزارِ mcp__gitlab در --allowedTools فعال باشد
  • تأیید کن که job در کانتکستِ MR اجرا می‌شود یا کانتکستِ کافی از طریقِ متغیرهای AI_FLOW_* دارد
  • برای Claude API: تأیید کن که ANTHROPIC_API_KEY معتبر و منقضی‌نشده است
  • برای Bedrock/Vertex: پیکربندیِ OIDC/WIF، جعلِ هویتِ role و نام‌های secret را بررسی کن؛ منطقه و دسترس‌پذیریِ مدل را تأیید کن

پارامترها و متغیرهای رایج

Section titled “پارامترها و متغیرهای رایج”

Claude Code از این ورودی‌های پرکاربرد پشتیبانی می‌کند:

  • prompt / prompt_file: دستورالعمل‌ها را به‌صورت خطی (-p) یا از طریقِ یک فایل بده
  • max_turns: تعدادِ تکرارهای رفت‌وبرگشتی را محدود کن
  • timeout_minutes: کلِ زمانِ اجرا را محدود کن
  • ANTHROPIC_API_KEY: برای Claude API لازم است (برای Bedrock/Vertex استفاده نمی‌شود)
  • محیطِ مخصوصِ ارائه‌دهنده: AWS_REGION، متغیرهای project/region برای Vertex

سفارشی‌سازیِ رفتارِ Claude

Section titled “سفارشی‌سازیِ رفتارِ Claude”

می‌توانی Claude را به دو شیوه‌ی اصلی هدایت کنی:

  1. CLAUDE.md: استانداردهای کدنویسی، الزاماتِ امنیتی و قراردادهای پروژه را تعریف کن. Claude این را در حین اجراها می‌خواند و از قواعدت پیروی می‌کند.
  2. پرامپت‌های سفارشی: دستورالعمل‌های مخصوصِ هر کار را از طریقِ prompt/prompt_file در job پاس بده. برای کارهای مختلف از پرامپت‌های مختلف استفاده کن (مثلاً بازبینی، پیاده‌سازی، بازنویسی).