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های خودت با محافظتِ شاخه و تأییدیههایت اجرا میشود
چطور کار میکند
Section titled “چطور کار میکند”Claude Code از GitLab CI/CD استفاده میکند تا کارهای هوش مصنوعی را در jobهای ایزوله اجرا کند و نتایج را از طریق MR به مخزن بازگرداند:
-
هماهنگیِ رویدادمحور: GitLab به تریگرهای انتخابیِ تو گوش میدهد (مثلاً کامنتی که در یک issue، MR یا رشتهی بازبینی به
@claudeمنشن میزند). job کانتکست را از رشته و مخزن جمع میکند، از آن ورودی پرامپت میسازد و Claude Code را اجرا میکند. -
انتزاعِ ارائهدهنده (provider): ارائهدهندهای را که با محیطت میخواند به کار ببر:
- Claude API (SaaS)
- Amazon Bedrock (دسترسیِ مبتنی بر IAM، گزینههای چند-منطقهای)
- Google Vertex AI (بومیِ GCP، Workload Identity Federation)
-
اجرای sandboxشده: هر تعامل در یک کانتینر با قواعدِ سختگیرانهی شبکه و فایلسیستم اجرا میشود. Claude Code دسترسیهای محدودشده به فضای کاری را اعمال میکند تا نوشتن را مهار کند. هر تغییر از مسیرِ یک MR میگذرد تا بازبینها diff را ببینند و تأییدیهها همچنان اعمال شوند.
اندپوینتهای منطقهای را انتخاب کن تا تأخیر را کم کنی و نیازهای حاکمیتِ داده را برآورده کنی، در حالی که از توافقهای ابریِ موجودت استفاده میکنی.
Claude چه کاری میتواند بکند؟
Section titled “Claude چه کاری میتواند بکند؟”Claude Code ورکفلوهای قدرتمندِ CI/CD را ممکن میکند که نحوهی کارت با کد را دگرگون میکنند:
- ساخت و بهروزرسانیِ MR از روی توضیحاتِ issue یا کامنتها
- تحلیلِ افتِ کارایی (performance regression) و پیشنهادِ بهینهسازی
- پیادهسازیِ قابلیتها مستقیماً در یک شاخه، سپس باز کردنِ یک MR
- رفعِ باگها و regressionهایی که با تستها یا کامنتها شناسایی شدهاند
- پاسخ به کامنتهای پیگیری برای تکرار روی تغییراتِ درخواستشده
راهاندازی
Section titled “راهاندازی”راهاندازیِ سریع
Section titled “راهاندازیِ سریع”سریعترین راهِ شروع این است که یک job مینیمال به .gitlab-ci.yml اضافه کنی و کلید APIات را بهعنوان یک متغیرِ ماسکشده تنظیم کنی.
-
یک متغیرِ ماسکشدهی CI/CD اضافه کن
- به Settings → CI/CD → Variables برو
ANTHROPIC_API_KEYرا اضافه کن (ماسکشده، در صورت نیاز protected)
-
یک 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/CD → Pipelines آزمایش کن، یا آن را از یک MR تریگر کن تا Claude بتواند در یک شاخه بهروزرسانی پیشنهاد دهد و در صورت نیاز یک MR باز کند.
راهاندازیِ دستی (توصیهشده برای محیطِ production)
Section titled “راهاندازیِ دستی (توصیهشده برای محیطِ production)”اگر راهاندازیِ کنترلشدهتری را ترجیح میدهی یا به ارائهدهندههای سازمانی نیاز داری:
-
دسترسیِ ارائهدهنده را پیکربندی کن:
- Claude API:
ANTHROPIC_API_KEYرا بهعنوان یک متغیرِ ماسکشدهی CI/CD بساز و ذخیره کن - Amazon Bedrock: پیکربندیِ GitLab → AWS OIDC و ساختِ یک IAM role برای Bedrock
- Google Vertex AI: پیکربندیِ Workload Identity Federation برای GitLab → GCP
- Claude API:
-
اعتبارنامههای پروژه را برای عملیاتِ GitLab API اضافه کن:
- بهصورت پیشفرض از
CI_JOB_TOKENاستفاده کن، یا یک Project Access Token با اسکوپِapiبساز - اگر از PAT استفاده میکنی، آن را بهعنوان
GITLAB_ACCESS_TOKEN(ماسکشده) ذخیره کن
- بهصورت پیشفرض از
-
job مربوط به Claude را به
.gitlab-ci.ymlاضافه کن (نمونهها را در ادامه ببین) -
(اختیاری) تریگرهای منشنمحور را فعال کن:
- یک project webhook برای «Comments (notes)» به event listenerات اضافه کن (اگر از یکی استفاده میکنی)
- کاری کن که listener وقتی کامنتی شامل
@claudeاست، pipeline trigger API را با متغیرهایی مثلAI_FLOW_INPUTوAI_FLOW_CONTEXTفراخوانی کند
نمونه موارد کاربرد
Section titled “نمونه موارد کاربرد”تبدیلِ issueها به MR
Section titled “تبدیلِ issueها به MR”در یک کامنتِ issue:
@claude implement this feature based on the issue descriptionClaude، issue و کدبیس را تحلیل میکند، تغییرات را در یک شاخه مینویسد و یک MR برای بازبینی باز میکند.
کمک در پیادهسازی
Section titled “کمک در پیادهسازی”در یک بحثِ MR:
@claude suggest a concrete approach to cache the results of this API callClaude تغییرات را پیشنهاد میدهد، کد را با کشینگِ مناسب اضافه میکند و MR را بهروز میکند.
رفعِ سریعِ باگها
Section titled “رفعِ سریعِ باگها”در یک کامنتِ issue یا MR:
@claude fix the TypeError in the user dashboard componentClaude باگ را پیدا میکند، یک رفع پیاده میکند و شاخه را بهروز میکند یا یک MR جدید باز میکند.
استفاده با Amazon Bedrock و Google Vertex AI
Section titled “استفاده با Amazon Bedrock و Google Vertex AI”برای محیطهای سازمانی، میتوانی Claude Code را بهطور کامل روی زیرساختِ ابریِ خودت اجرا کنی، با همان تجربهی توسعهدهنده.
پیشنیازها
Section titled “پیشنیازها”پیش از راهاندازیِ Claude Code با Amazon Bedrock، به اینها نیاز داری:
- یک حسابِ AWS با دسترسیِ Amazon Bedrock به مدلهای موردنظرِ Claude
- GitLab که بهعنوان یک OIDC identity provider در AWS IAM پیکربندی شده باشد
- یک IAM role با دسترسیهای Bedrock و یک trust policy محدودشده به project/refsهای GitLab تو
- متغیرهای CI/CD مربوط به GitLab برای assume کردنِ role:
AWS_ROLE_TO_ASSUME(ARN مربوط به role)AWS_REGION(منطقهی Bedrock)
دستورالعملِ راهاندازی
Section titled “دستورالعملِ راهاندازی”AWS را طوری پیکربندی کن که به jobهای GitLab CI اجازه دهد از طریق OIDC یک IAM role را assume کنند (بدون کلیدهای ثابت).
راهاندازیِ لازم:
- Amazon Bedrock را فعال کن و برای مدلهای هدفِ Claude درخواستِ دسترسی بده
- اگر هنوز وجود ندارد، یک IAM OIDC provider برای GitLab بساز
- یک IAM role که موردِ اعتمادِ OIDC provider مربوط به GitLab است بساز و آن را به پروژه و protected refsات محدود کن
- دسترسیهای least-privilege را برای Bedrock invoke APIها به آن متصل کن
مقادیرِ لازم برای ذخیره در متغیرهای CI/CD:
AWS_ROLE_TO_ASSUMEAWS_REGION
متغیرها را در Settings → CI/CD → Variables اضافه کن:
# For Amazon Bedrock:- AWS_ROLE_TO_ASSUME- AWS_REGIONاز نمونه job مربوط به Amazon Bedrock در بالا استفاده کن تا job token مربوط به GitLab را در زمانِ اجرا با اعتبارنامههای موقتِ AWS تبادل کنی.
پیشنیازها
Section titled “پیشنیازها”پیش از راهاندازیِ Claude Code با Google Vertex AI، به اینها نیاز داری:
- یک پروژهی Google Cloud با:
- Vertex AI API فعال
- Workload Identity Federation پیکربندیشده برای اعتماد به OIDC مربوط به GitLab
- یک service account اختصاصی فقط با roleهای لازمِ Vertex AI
- متغیرهای CI/CD مربوط به GitLab برای WIF:
GCP_WORKLOAD_IDENTITY_PROVIDER(نامِ کاملِ منبع)GCP_SERVICE_ACCOUNT(ایمیلِ service account)
دستورالعملِ راهاندازی
Section titled “دستورالعملِ راهاندازی”Google Cloud را طوری پیکربندی کن که به jobهای GitLab CI اجازه دهد از طریق Workload Identity Federation هویتِ یک service account را جعل کنند (impersonate).
راهاندازیِ لازم:
- IAM Credentials API، STS API و Vertex AI API را فعال کن
- یک Workload Identity Pool و provider برای OIDC مربوط به GitLab بساز
- یک service account اختصاصی با roleهای Vertex AI بساز
- به WIF principal اجازه بده هویتِ service account را جعل کند
مقادیرِ لازم برای ذخیره در متغیرهای CI/CD:
GCP_WORKLOAD_IDENTITY_PROVIDERGCP_SERVICE_ACCOUNT
متغیرها را در Settings → CI/CD → Variables اضافه کن:
# For Google Vertex AI:- GCP_WORKLOAD_IDENTITY_PROVIDER- GCP_SERVICE_ACCOUNT- CLOUD_ML_REGION (for example, us-east5)از نمونه job مربوط به Google Vertex AI در بالا استفاده کن تا بدون ذخیرهی کلیدها احراز هویت کنی.
نمونههای پیکربندی
Section titled “نمونههای پیکربندی”در ادامه قطعهکدهای آمادهی استفادهای هستند که میتوانی برای 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 برای دسترسی به BedrockAWS_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: نامِ کاملِ منبعِ providerGCP_SERVICE_ACCOUNT: ایمیلِ service accountCLOUD_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"بهترین شیوهها
Section titled “بهترین شیوهها”پیکربندیِ CLAUDE.md
Section titled “پیکربندیِ CLAUDE.md”یک فایلِ CLAUDE.md در ریشهی مخزن بساز تا استانداردهای کدنویسی، معیارهای بازبینی و قواعدِ مخصوصِ پروژه را تعریف کنی. Claude این فایل را در حین اجراها میخواند و هنگام پیشنهادِ تغییرات از قراردادهای تو پیروی میکند.
ملاحظاتِ امنیتی
Section titled “ملاحظاتِ امنیتی”هرگز کلیدهای API یا اعتبارنامههای ابری را در مخزنت کامیت نکن. همیشه از متغیرهای CI/CD مربوط به GitLab استفاده کن:
ANTHROPIC_API_KEYرا بهعنوان یک متغیرِ ماسکشده اضافه کن (و در صورت نیاز آن را protect کن)- هرجا که ممکن است از OIDC مخصوصِ ارائهدهنده استفاده کن (بدون کلیدهای بادوام)
- دسترسیهای job و خروجیِ شبکه را محدود کن
- MRهای Claude را مثل هر مشارکتکنندهی دیگری بازبینی کن
بهینهسازیِ کارایی
Section titled “بهینهسازیِ کارایی”CLAUDE.mdرا متمرکز و مختصر نگه دار- توضیحاتِ روشنِ issue/MR بده تا تعدادِ تکرارها کم شود
- timeoutهای منطقی برای job تنظیم کن تا از اجراهای لجامگسیخته جلوگیری کنی
- هرجا که ممکن است نصبهای npm و پکیجها را در runnerها کش کن
هزینههای CI
Section titled “هزینههای CI”هنگام استفاده از Claude Code با GitLab CI/CD، از هزینههای مرتبط آگاه باش:
-
زمانِ GitLab Runner:
- Claude روی GitLab runnerهای تو اجرا میشود و دقایقِ محاسباتی مصرف میکند
- برای جزئیات، صورتحسابِ runner در پلنِ GitLabات را ببین
-
هزینههای API:
- هر تعاملِ Claude بسته به اندازهی پرامپت و پاسخ توکن مصرف میکند
- مصرفِ توکن بسته به پیچیدگیِ کار و اندازهی کدبیس متفاوت است
- برای جزئیات قیمتگذاریِ Anthropic را ببین
-
نکاتِ بهینهسازیِ هزینه:
- از دستورهای مشخصِ
@claudeاستفاده کن تا نوبتهای غیرضروری کم شوند - مقادیرِ مناسبی برای
max_turnsو timeout مربوط به job تنظیم کن - همزمانی (concurrency) را محدود کن تا اجراهای موازی را کنترل کنی
- از دستورهای مشخصِ
امنیت و حاکمیت
Section titled “امنیت و حاکمیت”- هر job در یک کانتینرِ ایزوله با دسترسیِ شبکهی محدود اجرا میشود
- تغییراتِ Claude از مسیرِ MR میگذرند تا بازبینها هر diff را ببینند
- محافظتِ شاخه و قواعدِ تأییدیه روی کدِ تولیدشده با هوش مصنوعی اعمال میشوند
- Claude Code از دسترسیهای محدودشده به فضای کاری استفاده میکند تا نوشتن را مهار کند
- هزینهها زیرِ کنترلِ تو میمانند، چون اعتبارنامههای ارائهدهندهی خودت را به کار میبری
عیبیابی
Section titled “عیبیابی”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_*دارد
خطاهای احراز هویت
Section titled “خطاهای احراز هویت”- برای Claude API: تأیید کن که
ANTHROPIC_API_KEYمعتبر و منقضینشده است - برای Bedrock/Vertex: پیکربندیِ OIDC/WIF، جعلِ هویتِ role و نامهای secret را بررسی کن؛ منطقه و دسترسپذیریِ مدل را تأیید کن
پیکربندیِ پیشرفته
Section titled “پیکربندیِ پیشرفته”پارامترها و متغیرهای رایج
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 را به دو شیوهی اصلی هدایت کنی:
- CLAUDE.md: استانداردهای کدنویسی، الزاماتِ امنیتی و قراردادهای پروژه را تعریف کن. Claude این را در حین اجراها میخواند و از قواعدت پیروی میکند.
- پرامپتهای سفارشی: دستورالعملهای مخصوصِ هر کار را از طریقِ
prompt/prompt_fileدر job پاس بده. برای کارهای مختلف از پرامپتهای مختلف استفاده کن (مثلاً بازبینی، پیادهسازی، بازنویسی).