canonical: https://jentic.com/apis/gitlab.com/gitlab

# GitLab REST API

Interact with GitLab projects, merge requests, issues, CI/CD pipelines, and container registries through 358 REST endpoints. Supports personal access tokens, OAuth 2.0, and project-level deploy tokens for granular access. Covers the complete DevOps lifecycle from source control and code review through automated testing, deployment pipelines, and package publishing.

## For AI agents

Automate GitLab project management, merge request workflows, CI/CD pipeline triggering, and issue tracking across groups and projects. Covers 358 endpoints for the full DevOps lifecycle.

## Scope

Does not handle cloud infrastructure provisioning, container orchestration, or artifact storage - use for source control, code review, and CI/CD pipeline management only.

## Capabilities

- Open merge requests with source and target branch refs, assign reviewers, and set approval rules
- Trigger CI/CD pipelines on specific branches and monitor job status through to deployment
- Search and filter issues across projects with label, milestone, and assignee qualifiers
- Fork projects, configure protected branches, and manage repository access permissions
- Retrieve pipeline job logs and artifact downloads for build debugging
- Configure project-level runners and shared runner assignments for CI execution
- Manage group membership, access levels, and nested subgroup hierarchies

## Use cases

### AI Agent Merge Request Automation

AI agents use the GitLab API through Jentic to automate merge request workflows - creating MRs, assigning reviewers, checking pipeline status, and posting comments. An agent searches Jentic for 'create a merge request', receives the schema for POST /v3/projects/{id}/merge_requests, and executes with source branch, target branch, and title. The entire flow from MR creation to approval tracking completes without manual context-switching.

Example prompt: Create a merge request from feature/auth to main in project ID 12345, assign two reviewers, and verify the pipeline passes before requesting approval

### CI/CD Pipeline Management

Trigger pipelines on specific branches or tags, monitor job progress through stages, and download artifacts when builds complete. The API exposes pipeline status, individual job logs, and retry capabilities. Teams integrate this into larger deployment orchestration systems that coordinate across multiple GitLab projects and environments.

Example prompt: Trigger a pipeline on the release/v3.0 branch of project 12345, wait for the deploy stage to complete, and report whether all jobs succeeded

### Project and Group Administration

Create projects, configure settings, manage group membership, and set access levels across nested subgroup hierarchies. The API supports bulk operations for onboarding new teams - creating project structures, assigning permissions, and configuring default branch protections in a single automated flow.

Example prompt: Create a new project under the engineering group, set the default branch to main with push protection requiring one approval, and add three team members with Developer access

### Issue Tracking and Sprint Planning

Create, search, and update issues with labels, milestones, weights, and due dates. Filter across projects within a group or globally. Agents automate triage by labeling incoming issues based on content, assigning to appropriate milestones, and linking related issues for sprint planning.

Example prompt: Search for all open issues labeled 'severity::1' in the platform group created in the last 48 hours, and assign them to the current sprint milestone

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v3/projects/{id}/merge_requests | Create a merge request |
| GET | /v3/projects/{id}/merge_requests | List merge requests for a project |
| GET | /v3/projects | List all projects accessible to the user |
| GET | /v3/groups/{id}/issues | List issues for a group |
| POST | /v3/projects/{id}/issues | Create a new issue |
| GET | /v3/projects/{id}/runners | List project runners |
| GET | /v3/projects/{id}/builds | List project builds (CI jobs) |

## Key resources

- **Projects** — Create, fork, configure settings, and manage repository access and visibility
- **Merge Requests** — Open, review, approve, and merge code changes with pipeline integration
- **Issues** — Create, search, label, assign, and track issues with milestones and boards
- **Groups** — Organize projects into groups with membership, access levels, and subgroups
- **Runners** — Register, configure, and manage CI/CD runner instances
- **Builds** — Trigger, monitor, retry, and cancel CI/CD pipeline jobs

## Why Jentic

- **Setup:** Wiring GitLab by hand means handling both personal access tokens and OAuth2, minding token scopes like api and read_api, and mapping the 358-endpoint surface yourself. Through Jentic you install once, import the GitLab REST API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** GitLab puts the project id in the URL path (/v3/projects/{id}/...), so a rule can pin your agent to one project: it can open merge requests and issues there and nothing else. You choose the operations it may call, so destructive ones like deleting a project or removing a merge request are not included unless you add them.
- **Credential handling:** Your GitLab personal access token or OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a merge request' or 'trigger a pipeline', and Jentic returns the matching GitLab operation with its input schema so the agent calls the right endpoint without browsing the 358-endpoint reference docs.

## Related APIs

- **GitHub v3 REST API** — Cloud-hosted Git platform with Actions CI/CD and extensive marketplace integrations
- **CircleCI REST API** — Dedicated CI/CD platform that integrates with GitLab repositories
- **Linear API** — Project tracking tool that can sync with GitLab merge requests

## FAQ

### What authentication does the GitLab REST API use?

The GitLab API supports personal access tokens passed via the PRIVATE-TOKEN header, OAuth 2.0 bearer tokens, and project/group deploy tokens for CI/CD. Through Jentic, tokens are stored encrypted in your Jentic One instance and injected automatically - agents never see raw credentials. Personal access tokens can be scoped to specific permissions like read_api, read_repository, or API (full access).

### How do I create a merge request through the GitLab API via Jentic?

Search Jentic for 'create a merge request', load the operation schema for POST /v3/projects/{id}/merge_requests, and execute with source_branch, target_branch, and title fields. Jentic handles authentication automatically. The response includes the MR IID, web URL, and pipeline status. You can also assign reviewers and set labels in the same request.

### What are the rate limits for the GitLab REST API?

GitLab.com applies 2000 requests per minute for authenticated users by default. Self-managed instances configure their own limits. The API returns RateLimit-Remaining and RateLimit-Reset headers. Unauthenticated requests are limited to 500 per minute on gitlab.com. Heavy endpoints like search have lower per-endpoint limits.

### Can I trigger CI/CD pipelines via the GitLab API?

Yes. Use the pipeline trigger endpoint to start a new pipeline on a specified ref (branch or tag). You can pass variables as key-value pairs to customize the pipeline run. Monitor status by polling the pipelines list endpoint filtered by SHA or ref, and retrieve individual job logs for debugging.

### How do I list all projects within a specific GitLab group?

Use GET /v3/groups/{id}/projects to list all projects under a group. Filter by visibility, archived status, or search term. Results include project metadata, default branch, last activity date, and access level. For nested subgroups, use the subgroups endpoint to traverse the hierarchy.

### Is the GitLab REST API free to use?

The API is free for all GitLab.com tiers including Free. Rate limits differ by plan: Free tier gets 2000 requests/minute, Premium and Ultimate get higher limits. Self-managed GitLab instances have configurable limits. There is no per-request API cost.

### Can I limit what my agent is allowed to do with the GitLab REST API?

Yes. Because your Jentic One instance is self-hosted, your own rules decide which GitLab operations and credentials the agent may use. Since GitLab puts the project id in the URL path (/v3/projects/{id}/...), a rule can pin the agent to a single project so it can open merge requests and issues there and nowhere else. You choose the operations it may call, so destructive actions like deleting a project or a merge request stay out of reach unless you add them.