Overview
CodeBuddy Code supports deep integration with GitLab CI/CD, enabling you to use AI assistance in CI/CD pipelines for tasks such as code review, automation implementation, and intelligent optimization. This integration is built on the CodeBuddy Code CLI and allows AI capabilities to be used programmatically in GitLab CI jobs.
Why Use CodeBuddy Code in GitLab CI/CD?
Create an MR instantly: Describe your requirements, and CodeBuddy automatically generates a complete merge request with change descriptions.
Automated implementation: Turn issues into working code through simple commands or comments.
Project awareness: CodeBuddy follows your CODEBUDDY.md guidelines and existing code conventions.
Simple configuration: Add a job and the necessary CI/CD variables to your .gitlab-ci.yml file.
Secure by default: Runs in your GitLab Runner and adheres to branch protection and approval processes.
How It Works
CodeBuddy Code uses GitLab CI/CD to run AI tasks in isolated jobs and submits results through MRs:
1. Event-driven orchestration: GitLab listens for triggers you select, such as issues, MRs, or comments mentioning @codebuddy. Jobs collect context and codebase information, build prompts, and run CodeBuddy Code.
2. Sandboxed execution: Every interaction runs in a container with strict network and file system rules. CodeBuddy Code enforces workspace-wide permission-constrained writes. Every change flows through an MR, allowing reviewers to see the diff while approval processes remain applicable.
What Can CodeBuddy Do?
CodeBuddy Code supports powerful CI/CD workflows, transforming how you collaborate with code:
Create and update MRs from Issue descriptions or comments.
Analyze performance regressions and propose optimization recommendations.
Implement the feature directly in a branch, then create an MR.
Fix bugs and regressions found in tests or comments.
Respond to follow-up comments to iteratively refine the requested changes.
Configuration Guide
Quick Configuration
The quickest way to get started is to add a minimal job to your .gitlab-ci.yml file and set the API key as a protected variable.
Step 1: Add protected CI/CD variables
Go to Settings > CI/CD > Variables in your GitLab project and add the following environment variables:
Authentication configuration:
In your GitLab project, go to Settings > CI/CD > Variables and add the following environment variables:
CODEBUDDY_API_KEY (required)
API key for model API calls
When configuring, select: ✔ Protected (Protect variable), ✔ Masked (Mask variable).
Optional configuration:
CODEBUDDY_INTERNET_ENVIRONMENT
Network environment configuration (users in China must set it to internal, and iOA users must set it to iOA)
CODEBUDDY_BASE_URL
Base URL of the custom model service (must be compatible with the OpenAI API protocol)
GITLAB_ACCESS_TOKEN
GitLab project access token (requires the api scope)
Used by CodeBuddy to create/update MRs and comments.
If not configured, CI_JOB_TOKEN is used by default.
When configuring, select: ✔ Protected, ✔ Masked.
Each section contains complete environment variable configuration methods and the address for obtaining the API KEY.
Step 2: Add the CodeBuddy job to .gitlab-ci.yml
stages:
- ai
codebuddy:
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
- npm install -g @tencent-ai/codebuddy-code
- |
if [ -z "$CODEBUDDY_API_KEY" ]; then
echo "Error: CODEBUDDY_API_KEY is not set. Configure it in GitLab CI/CD variables."
exit 1
fi
script:
- /bin/gitlab-mcp-server || true
- echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
- >
codebuddy
-p "${AI_FLOW_INPUT:-'Review this MR and implement the requested changes'}"
--permission-mode acceptEdits
--allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
--debug
After adding the job and API key variables, run the job manually through CI/CD > Pipelines to test it, or trigger it from an MR to have CodeBuddy propose updates in the branch and create an MR when needed.
Manual Configuration (Recommended for Production)
If you need finer-grained control:
1. Add project credentials for GitLab API operations:
Use CI_JOB_TOKEN by default, or create a project access token with the api scope.
If you use a PAT, store it as GITLAB_ACCESS_TOKEN (masked).
2. Add the CodeBuddy job to .gitlab-ci.yml (see the example above).
3. (Optional) Enable mention-driven triggers:
Add a project Webhook for "notes" to your event listener (if it is used).
Have the listener call the pipeline trigger API when a comment contains @codebuddy, passing variables such as AI_FLOW_INPUT and AI_FLOW_CONTEXT.
Usage Examples
Converting Issues into MRs
In Issue comments:
@codebuddy implement this feature based on the Issue description.
CodeBuddy analyzes the Issue and codebase, writes changes in a branch, and creates an MR for review.
Getting Implementation Help
In MR discussions:
@codebuddy suggest a specific approach to cache the result of this API call.
CodeBuddy proposes a change plan, adds appropriate caching code, and updates the MR.
Quick Bug Fixes
In Issue or MR comments:
@codebuddy fix the TypeError in the user dashboard component.
CodeBuddy locates the Bug, implements a fix, and updates the branch or creates a new MR.
Tips
CODEBUDDY.md Configuration
Create a CODEBUDDY.md file in the repository root to define coding standards, review standards, and project-specific rules. CodeBuddy reads this file during operation and follows your conventions when proposing changes.
Example CODEBUDDY.md:
# Project Coding Standards
## Code Style
- Use ESLint and Prettier for code formatting.
- Follow the Airbnb JavaScript Style Guide.
- Use TypeScript strict mode.
## Commit Guidelines
- Follow the Conventional Commits specification.
- Write commit messages in Chinese.
- Each commit contains only one logical change.
## Testing Requirements
- All new features must include unit tests.
- Test coverage must be no less than 80%.
- Use Jest as the testing framework.
## MR Review Checklist
- The code passes all CI checks.
- At least one team member must approve the review.
- Update relevant documentation.
Security Considerations
Never commit sensitive information to the repository! Always use GitLab CI/CD variables:
Add sensitive configurations as masked variables (mark them as protected if necessary).
Restrict job permissions and network egress.
Review CodeBuddy's MRs just as you would review those from any other contributor.
Performance Optimization
Keep CODEBUDDY.md concise and clear.
Provide clear Issue/MR descriptions to reduce iterations.
Configure reasonable job timeouts to prevent runaway execution.
Cache npm and package installations in the Runner if possible.
CI Cost Control
When using CodeBuddy Code with GitLab CI/CD, be aware of the associated costs:
GitLab Runner time:
CodeBuddy runs on your GitLab Runner and consumes compute minutes.
View the Runner billing details for your GitLab plan.
Cost Optimization Tips:
Use specific @codebuddy commands to reduce unnecessary back-and-forth.
Set appropriate values for --max-turns and job timeout.
Limit concurrency to control parallel execution.
Security and Governance
Each job runs in an isolated container with restricted network access.
Changes from CodeBuddy flow through MRs, allowing reviewers to see every diff.
Branch protection and approval rules apply to AI-generated code.
CodeBuddy Code enforces workspace-scoped permissions for write operations.
Troubleshooting
CodeBuddy Not Responding to @codebuddy Commands
Verify that your pipeline is being triggered (manually, by an MR event, or through a note event listener/Webhook).
Ensure that the CI/CD variables exist and are configured correctly.
Check whether the comment contains @codebuddy (not /codebuddy) and your mention trigger is configured.
Unable to Write Comments or Create MRs for Jobs
Ensure that CI_JOB_TOKEN has sufficient permissions on the project, or use a project access token with the api scope.
Check that the mcp__gitlab tool is enabled in --allowedTools.
Confirm that the job runs in the MR context or has sufficient context through AI_FLOW_* variables.
Authentication Errors
Authentication variables are not set:
Confirm that CODEBUDDY_API_KEY has been added in the GitLab project's Settings > CI/CD > Variables.
Check whether the variable name is spelled correctly (case-sensitive).
If the "Protected" option is set, ensure that the job runs on a protected branch.
API authentication failed (401 Unauthorized):
Verify that the API key is valid and has not expired.
Confirm that no extra spaces or line breaks were included when the API key was copied.
Check whether the API key has sufficient permissions.
API connection failed:
Check whether CODEBUDDY_BASE_URL is configured correctly (for example, when using a custom endpoint).
Verify that the GitLab Runner can access the CodeBuddy API server.
Confirm that the URL format is correct and includes a protocol (for example, https://api.example.com).
The key is visible in logs:
Ensure that the ✔ Mask variable option is selected when CI/CD variables are configured.
Avoid directly echoing or printing API keys in scripts.
GitLab Access Token related issues:
Check whether the configured CI/CD variables are set correctly.
Verify the related access permission configuration.
Ensure that CI_JOB_TOKEN or GITLAB_ACCESS_TOKEN has sufficient permissions (api scope).
Job Timeout
Increase the timeout configuration for the job.
Simplify prompts to reduce processing time.
Consider splitting large tasks into multiple smaller tasks.
Advanced Configuration
Common Parameters and Variables
Environment variables:
CodeBuddy Code uses the following environment variables in CI/CD environments:
Authentication configuration:
CODEBUDDY_API_KEY: Used for model API calls, suitable for non-interactive CI/CD environments.
Optional configuration:
CODEBUDDY_BASE_URL: Base URL of the custom model service.
GITLAB_ACCESS_TOKEN: GitLab API access token (used for MR operations).
CI_JOB_TOKEN: Job token automatically provided by GitLab CI.
Process control variables:
AI_FLOW_INPUT: User input passed through the Web/API trigger.
AI_FLOW_CONTEXT: Context information (such as Issue ID and MR ID).
AI_FLOW_EVENT: Type of the triggering event (such as note, issue, or merge_request).
Command-line arguments:
CodeBuddy Code supports the following common input methods:
prompt (-p): Provides instructions inline.
max-turns: Limits the number of back-and-forth iterations.
permission-mode: Permission mode (such as acceptEdits).
allowedTools: List of tools that are allowed to be used.
debug: Enables debug output.
Note:
The exact flags and parameters may vary depending on the version of @tencent-ai/codebuddy-code. Run codebuddy --help in your job to view the supported options.
Customizing CodeBuddy Behavior
You can guide CodeBuddy in two primary ways:
1. CODEBUDDY.md: Defines coding standards, security requirements, and project conventions. CodeBuddy reads this file during operation and follows your rules.
2. Custom prompt: Pass task-specific instructions through prompt/prompt_file in a job. Use different prompts for different jobs (such as review, implementation, and refactoring).
Multi-Environment Configuration
You can configure different CodeBuddy jobs for different environments (development, testing, and production):
codebuddy-dev:
stage: ai
rules:
- if: '$CI_COMMIT_BRANCH == "develop"'
script:
- codebuddy -p "Quickly review and automatically merge"
codebuddy-prod:
stage: ai
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
when: manual
script:
- codebuddy -p "Perform a detailed review and generate a complete change report"