Initial commit
This commit is contained in:
Zhongwei Li
797
skills/gitlab/references/api.md
Normal file
797
skills/gitlab/references/api.md
Normal file
@@ -0,0 +1,797 @@
|
||||
# GitLab REST API Reference
|
||||
|
||||
## Overview
|
||||
|
||||
The GitLab REST API provides programmatic access to GitLab resources. All API requests require authentication and return JSON responses.
|
||||
|
||||
## Base URL
|
||||
|
||||
```
|
||||
https://gitlab.com/api/v4
|
||||
```
|
||||
|
||||
For self-hosted GitLab instances:
|
||||
```
|
||||
https://your-gitlab-instance.com/api/v4
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
### Personal Access Tokens (Recommended)
|
||||
|
||||
Include in request header:
|
||||
```
|
||||
PRIVATE-TOKEN: <your_access_token>
|
||||
```
|
||||
|
||||
Or as query parameter:
|
||||
```
|
||||
?private_token=<your_access_token>
|
||||
```
|
||||
|
||||
### OAuth 2.0 Token
|
||||
|
||||
Include in request header:
|
||||
```
|
||||
Authorization: Bearer <oauth_token>
|
||||
```
|
||||
|
||||
### Job Token (CI/CD)
|
||||
|
||||
Use within GitLab CI/CD jobs:
|
||||
```
|
||||
JOB-TOKEN: <CI_JOB_TOKEN>
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
- Default: 2000 requests per minute per user
|
||||
- Authenticated requests: counted per user
|
||||
- Unauthenticated requests: counted per IP
|
||||
- Response headers include rate limit info:
|
||||
- `RateLimit-Limit`: Request limit
|
||||
- `RateLimit-Remaining`: Remaining requests
|
||||
- `RateLimit-Reset`: Reset time (Unix timestamp)
|
||||
|
||||
## Common Parameters
|
||||
|
||||
### Pagination
|
||||
|
||||
- `page`: Page number (default: 1)
|
||||
- `per_page`: Items per page (default: 20, max: 100)
|
||||
|
||||
Headers in response:
|
||||
- `X-Total`: Total number of items
|
||||
- `X-Total-Pages`: Total number of pages
|
||||
- `X-Per-Page`: Items per page
|
||||
- `X-Page`: Current page
|
||||
- `X-Next-Page`: Next page number
|
||||
- `X-Prev-Page`: Previous page number
|
||||
|
||||
### Filtering
|
||||
|
||||
- `search`: Search by specific fields
|
||||
- `order_by`: Order results (e.g., `created_at`, `updated_at`, `name`)
|
||||
- `sort`: Sort direction (`asc` or `desc`)
|
||||
|
||||
## Core API Resources
|
||||
|
||||
### Projects
|
||||
|
||||
**List all projects**
|
||||
```
|
||||
GET /projects
|
||||
```
|
||||
|
||||
**Get project by ID**
|
||||
```
|
||||
GET /projects/:id
|
||||
```
|
||||
|
||||
**Create project**
|
||||
```
|
||||
POST /projects
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `name` (required): Project name
|
||||
- `path`: Repository path (defaults to name)
|
||||
- `namespace_id`: Namespace for project
|
||||
- `description`: Project description
|
||||
- `visibility`: `private`, `internal`, or `public`
|
||||
- `initialize_with_readme`: Boolean
|
||||
|
||||
**Update project**
|
||||
```
|
||||
PUT /projects/:id
|
||||
```
|
||||
|
||||
**Delete project**
|
||||
```
|
||||
DELETE /projects/:id
|
||||
```
|
||||
|
||||
**Fork project**
|
||||
```
|
||||
POST /projects/:id/fork
|
||||
```
|
||||
|
||||
**List project members**
|
||||
```
|
||||
GET /projects/:id/members
|
||||
```
|
||||
|
||||
**Add project member**
|
||||
```
|
||||
POST /projects/:id/members
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `user_id` (required): User ID
|
||||
- `access_level` (required): 10 (Guest), 20 (Reporter), 30 (Developer), 40 (Maintainer), 50 (Owner)
|
||||
|
||||
### Repository
|
||||
|
||||
**List repository files**
|
||||
```
|
||||
GET /projects/:id/repository/tree
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `path`: Directory path
|
||||
- `ref`: Branch/tag name
|
||||
- `recursive`: Boolean for recursive listing
|
||||
|
||||
**Get file content**
|
||||
```
|
||||
GET /projects/:id/repository/files/:file_path
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `ref` (required): Branch/tag/commit
|
||||
|
||||
**Create file**
|
||||
```
|
||||
POST /projects/:id/repository/files/:file_path
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `branch` (required): Branch name
|
||||
- `content` (required): File content
|
||||
- `commit_message` (required): Commit message
|
||||
- `encoding`: `text` or `base64`
|
||||
|
||||
**Update file**
|
||||
```
|
||||
PUT /projects/:id/repository/files/:file_path
|
||||
```
|
||||
|
||||
**Delete file**
|
||||
```
|
||||
DELETE /projects/:id/repository/files/:file_path
|
||||
```
|
||||
|
||||
**Get repository archive**
|
||||
```
|
||||
GET /projects/:id/repository/archive
|
||||
```
|
||||
|
||||
### Commits
|
||||
|
||||
**List commits**
|
||||
```
|
||||
GET /projects/:id/repository/commits
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `ref_name`: Branch/tag name
|
||||
- `since`: Start date (ISO 8601 format)
|
||||
- `until`: End date
|
||||
- `path`: File path to filter commits
|
||||
|
||||
**Get single commit**
|
||||
```
|
||||
GET /projects/:id/repository/commits/:sha
|
||||
```
|
||||
|
||||
**Create commit**
|
||||
```
|
||||
POST /projects/:id/repository/commits
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `branch` (required): Branch name
|
||||
- `commit_message` (required): Commit message
|
||||
- `actions` (required): Array of actions
|
||||
|
||||
Action types:
|
||||
- `create`: Create file
|
||||
- `delete`: Delete file
|
||||
- `move`: Move file
|
||||
- `update`: Update file
|
||||
- `chmod`: Change permissions
|
||||
|
||||
**Get commit diff**
|
||||
```
|
||||
GET /projects/:id/repository/commits/:sha/diff
|
||||
```
|
||||
|
||||
**Get commit comments**
|
||||
```
|
||||
GET /projects/:id/repository/commits/:sha/comments
|
||||
```
|
||||
|
||||
### Branches
|
||||
|
||||
**List branches**
|
||||
```
|
||||
GET /projects/:id/repository/branches
|
||||
```
|
||||
|
||||
**Get single branch**
|
||||
```
|
||||
GET /projects/:id/repository/branches/:branch
|
||||
```
|
||||
|
||||
**Create branch**
|
||||
```
|
||||
POST /projects/:id/repository/branches
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `branch` (required): Branch name
|
||||
- `ref` (required): Source branch/tag/commit
|
||||
|
||||
**Delete branch**
|
||||
```
|
||||
DELETE /projects/:id/repository/branches/:branch
|
||||
```
|
||||
|
||||
**Protect branch**
|
||||
```
|
||||
POST /projects/:id/protected_branches
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `name` (required): Branch name or wildcard
|
||||
- `push_access_level`: 0 (No access), 30 (Developer), 40 (Maintainer)
|
||||
- `merge_access_level`: Similar access levels
|
||||
- `allow_force_push`: Boolean
|
||||
|
||||
### Merge Requests
|
||||
|
||||
**List merge requests**
|
||||
```
|
||||
GET /projects/:id/merge_requests
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `state`: `opened`, `closed`, `merged`, `all`
|
||||
- `scope`: `created_by_me`, `assigned_to_me`, `all`
|
||||
- `source_branch`: Filter by source branch
|
||||
- `target_branch`: Filter by target branch
|
||||
|
||||
**Get merge request**
|
||||
```
|
||||
GET /projects/:id/merge_requests/:merge_request_iid
|
||||
```
|
||||
|
||||
**Create merge request**
|
||||
```
|
||||
POST /projects/:id/merge_requests
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `source_branch` (required): Source branch
|
||||
- `target_branch` (required): Target branch
|
||||
- `title` (required): MR title
|
||||
- `description`: MR description
|
||||
- `assignee_id`: Assignee user ID
|
||||
- `reviewer_ids`: Array of reviewer user IDs
|
||||
- `labels`: Comma-separated label names
|
||||
- `remove_source_branch`: Boolean
|
||||
|
||||
**Update merge request**
|
||||
```
|
||||
PUT /projects/:id/merge_requests/:merge_request_iid
|
||||
```
|
||||
|
||||
**Accept/Merge MR**
|
||||
```
|
||||
PUT /projects/:id/merge_requests/:merge_request_iid/merge
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `merge_commit_message`: Custom merge message
|
||||
- `squash_commit_message`: Squash commit message
|
||||
- `squash`: Boolean
|
||||
- `should_remove_source_branch`: Boolean
|
||||
|
||||
**Get MR changes**
|
||||
```
|
||||
GET /projects/:id/merge_requests/:merge_request_iid/changes
|
||||
```
|
||||
|
||||
**Get MR commits**
|
||||
```
|
||||
GET /projects/:id/merge_requests/:merge_request_iid/commits
|
||||
```
|
||||
|
||||
**Get MR approvals**
|
||||
```
|
||||
GET /projects/:id/merge_requests/:merge_request_iid/approvals
|
||||
```
|
||||
|
||||
**Approve MR**
|
||||
```
|
||||
POST /projects/:id/merge_requests/:merge_request_iid/approve
|
||||
```
|
||||
|
||||
### Issues
|
||||
|
||||
**List issues**
|
||||
```
|
||||
GET /projects/:id/issues
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `state`: `opened`, `closed`, `all`
|
||||
- `labels`: Comma-separated label names
|
||||
- `milestone`: Milestone title
|
||||
- `assignee_id`: Assignee user ID
|
||||
- `author_id`: Author user ID
|
||||
|
||||
**Get issue**
|
||||
```
|
||||
GET /projects/:id/issues/:issue_iid
|
||||
```
|
||||
|
||||
**Create issue**
|
||||
```
|
||||
POST /projects/:id/issues
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `title` (required): Issue title
|
||||
- `description`: Issue description
|
||||
- `assignee_ids`: Array of assignee IDs
|
||||
- `labels`: Comma-separated labels
|
||||
- `milestone_id`: Milestone ID
|
||||
- `due_date`: Due date (YYYY-MM-DD)
|
||||
- `weight`: Issue weight
|
||||
|
||||
**Update issue**
|
||||
```
|
||||
PUT /projects/:id/issues/:issue_iid
|
||||
```
|
||||
|
||||
**Close issue**
|
||||
```
|
||||
PUT /projects/:id/issues/:issue_iid
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `state_event`: `close`
|
||||
|
||||
**Delete issue**
|
||||
```
|
||||
DELETE /projects/:id/issues/:issue_iid
|
||||
```
|
||||
|
||||
### Pipelines
|
||||
|
||||
**List pipelines**
|
||||
```
|
||||
GET /projects/:id/pipelines
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `ref`: Branch/tag name
|
||||
- `status`: `running`, `pending`, `success`, `failed`, `canceled`, `skipped`
|
||||
- `scope`: `running`, `pending`, `finished`, `branches`, `tags`
|
||||
|
||||
**Get pipeline**
|
||||
```
|
||||
GET /projects/:id/pipelines/:pipeline_id
|
||||
```
|
||||
|
||||
**Create pipeline**
|
||||
```
|
||||
POST /projects/:id/pipeline
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `ref` (required): Branch/tag name
|
||||
- `variables`: Array of pipeline variables
|
||||
|
||||
**Retry pipeline**
|
||||
```
|
||||
POST /projects/:id/pipelines/:pipeline_id/retry
|
||||
```
|
||||
|
||||
**Cancel pipeline**
|
||||
```
|
||||
POST /projects/:id/pipelines/:pipeline_id/cancel
|
||||
```
|
||||
|
||||
**Delete pipeline**
|
||||
```
|
||||
DELETE /projects/:id/pipelines/:pipeline_id
|
||||
```
|
||||
|
||||
**Get pipeline variables**
|
||||
```
|
||||
GET /projects/:id/pipelines/:pipeline_id/variables
|
||||
```
|
||||
|
||||
### Jobs
|
||||
|
||||
**List project jobs**
|
||||
```
|
||||
GET /projects/:id/jobs
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `scope`: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `manual`
|
||||
|
||||
**Get pipeline jobs**
|
||||
```
|
||||
GET /projects/:id/pipelines/:pipeline_id/jobs
|
||||
```
|
||||
|
||||
**Get job**
|
||||
```
|
||||
GET /projects/:id/jobs/:job_id
|
||||
```
|
||||
|
||||
**Get job artifacts**
|
||||
```
|
||||
GET /projects/:id/jobs/:job_id/artifacts
|
||||
```
|
||||
|
||||
**Download artifact file**
|
||||
```
|
||||
GET /projects/:id/jobs/:job_id/artifacts/:artifact_path
|
||||
```
|
||||
|
||||
**Get job trace**
|
||||
```
|
||||
GET /projects/:id/jobs/:job_id/trace
|
||||
```
|
||||
|
||||
**Retry job**
|
||||
```
|
||||
POST /projects/:id/jobs/:job_id/retry
|
||||
```
|
||||
|
||||
**Cancel job**
|
||||
```
|
||||
POST /projects/:id/jobs/:job_id/cancel
|
||||
```
|
||||
|
||||
**Erase job**
|
||||
```
|
||||
POST /projects/:id/jobs/:job_id/erase
|
||||
```
|
||||
|
||||
**Play manual job**
|
||||
```
|
||||
POST /projects/:id/jobs/:job_id/play
|
||||
```
|
||||
|
||||
### Users
|
||||
|
||||
**List users**
|
||||
```
|
||||
GET /users
|
||||
```
|
||||
|
||||
**Get user**
|
||||
```
|
||||
GET /users/:id
|
||||
```
|
||||
|
||||
**Get current user**
|
||||
```
|
||||
GET /user
|
||||
```
|
||||
|
||||
**Create user** (Admin only)
|
||||
```
|
||||
POST /users
|
||||
```
|
||||
|
||||
**Update user**
|
||||
```
|
||||
PUT /users/:id
|
||||
```
|
||||
|
||||
**Delete user** (Admin only)
|
||||
```
|
||||
DELETE /users/:id
|
||||
```
|
||||
|
||||
### Groups
|
||||
|
||||
**List groups**
|
||||
```
|
||||
GET /groups
|
||||
```
|
||||
|
||||
**Get group**
|
||||
```
|
||||
GET /groups/:id
|
||||
```
|
||||
|
||||
**Create group**
|
||||
```
|
||||
POST /groups
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `name` (required): Group name
|
||||
- `path` (required): Group path
|
||||
- `description`: Group description
|
||||
- `visibility`: `private`, `internal`, `public`
|
||||
|
||||
**Update group**
|
||||
```
|
||||
PUT /groups/:id
|
||||
```
|
||||
|
||||
**Delete group**
|
||||
```
|
||||
DELETE /groups/:id
|
||||
```
|
||||
|
||||
**List group members**
|
||||
```
|
||||
GET /groups/:id/members
|
||||
```
|
||||
|
||||
**Add group member**
|
||||
```
|
||||
POST /groups/:id/members
|
||||
```
|
||||
|
||||
### Runners
|
||||
|
||||
**List runners**
|
||||
```
|
||||
GET /runners
|
||||
```
|
||||
|
||||
**Get runner**
|
||||
```
|
||||
GET /runners/:id
|
||||
```
|
||||
|
||||
**Update runner**
|
||||
```
|
||||
PUT /runners/:id
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `description`: Runner description
|
||||
- `active`: Boolean
|
||||
- `tag_list`: Array of tags
|
||||
- `run_untagged`: Boolean
|
||||
- `locked`: Boolean
|
||||
- `access_level`: `not_protected`, `ref_protected`
|
||||
|
||||
**Delete runner**
|
||||
```
|
||||
DELETE /runners/:id
|
||||
```
|
||||
|
||||
**List project runners**
|
||||
```
|
||||
GET /projects/:id/runners
|
||||
```
|
||||
|
||||
**Enable runner for project**
|
||||
```
|
||||
POST /projects/:id/runners
|
||||
```
|
||||
|
||||
**Disable runner for project**
|
||||
```
|
||||
DELETE /projects/:id/runners/:runner_id
|
||||
```
|
||||
|
||||
### Variables
|
||||
|
||||
**List project variables**
|
||||
```
|
||||
GET /projects/:id/variables
|
||||
```
|
||||
|
||||
**Get variable**
|
||||
```
|
||||
GET /projects/:id/variables/:key
|
||||
```
|
||||
|
||||
**Create variable**
|
||||
```
|
||||
POST /projects/:id/variables
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `key` (required): Variable key
|
||||
- `value` (required): Variable value
|
||||
- `variable_type`: `env_var` or `file`
|
||||
- `protected`: Boolean
|
||||
- `masked`: Boolean
|
||||
- `environment_scope`: Environment scope (default: `*`)
|
||||
|
||||
**Update variable**
|
||||
```
|
||||
PUT /projects/:id/variables/:key
|
||||
```
|
||||
|
||||
**Delete variable**
|
||||
```
|
||||
DELETE /projects/:id/variables/:key
|
||||
```
|
||||
|
||||
### Webhooks
|
||||
|
||||
**List project webhooks**
|
||||
```
|
||||
GET /projects/:id/hooks
|
||||
```
|
||||
|
||||
**Get webhook**
|
||||
```
|
||||
GET /projects/:id/hooks/:hook_id
|
||||
```
|
||||
|
||||
**Create webhook**
|
||||
```
|
||||
POST /projects/:id/hooks
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `url` (required): Webhook URL
|
||||
- `token`: Secret token
|
||||
- `push_events`: Boolean
|
||||
- `issues_events`: Boolean
|
||||
- `merge_requests_events`: Boolean
|
||||
- `wiki_page_events`: Boolean
|
||||
- `pipeline_events`: Boolean
|
||||
- `job_events`: Boolean
|
||||
- `deployment_events`: Boolean
|
||||
- `enable_ssl_verification`: Boolean
|
||||
|
||||
**Update webhook**
|
||||
```
|
||||
PUT /projects/:id/hooks/:hook_id
|
||||
```
|
||||
|
||||
**Delete webhook**
|
||||
```
|
||||
DELETE /projects/:id/hooks/:hook_id
|
||||
```
|
||||
|
||||
**Test webhook**
|
||||
```
|
||||
POST /projects/:id/hooks/:hook_id/test/:trigger
|
||||
```
|
||||
|
||||
Triggers: `push_events`, `issues_events`, `merge_requests_events`, etc.
|
||||
|
||||
### Tags
|
||||
|
||||
**List tags**
|
||||
```
|
||||
GET /projects/:id/repository/tags
|
||||
```
|
||||
|
||||
**Get tag**
|
||||
```
|
||||
GET /projects/:id/repository/tags/:tag_name
|
||||
```
|
||||
|
||||
**Create tag**
|
||||
```
|
||||
POST /projects/:id/repository/tags
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `tag_name` (required): Tag name
|
||||
- `ref` (required): Source commit SHA
|
||||
- `message`: Tag message
|
||||
- `release_description`: Release description
|
||||
|
||||
**Delete tag**
|
||||
```
|
||||
DELETE /projects/:id/repository/tags/:tag_name
|
||||
```
|
||||
|
||||
### Releases
|
||||
|
||||
**List releases**
|
||||
```
|
||||
GET /projects/:id/releases
|
||||
```
|
||||
|
||||
**Get release**
|
||||
```
|
||||
GET /projects/:id/releases/:tag_name
|
||||
```
|
||||
|
||||
**Create release**
|
||||
```
|
||||
POST /projects/:id/releases
|
||||
```
|
||||
|
||||
Parameters:
|
||||
- `name` (required): Release name
|
||||
- `tag_name` (required): Tag name
|
||||
- `description`: Release description
|
||||
- `ref`: Commit SHA, branch, or tag (required if tag doesn't exist)
|
||||
- `milestones`: Array of milestone titles
|
||||
- `assets`: Release assets
|
||||
|
||||
**Update release**
|
||||
```
|
||||
PUT /projects/:id/releases/:tag_name
|
||||
```
|
||||
|
||||
**Delete release**
|
||||
```
|
||||
DELETE /projects/:id/releases/:tag_name
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### HTTP Status Codes
|
||||
|
||||
- `200 OK`: Request successful
|
||||
- `201 Created`: Resource created
|
||||
- `204 No Content`: Successful deletion
|
||||
- `400 Bad Request`: Invalid parameters
|
||||
- `401 Unauthorized`: Authentication required
|
||||
- `403 Forbidden`: Insufficient permissions
|
||||
- `404 Not Found`: Resource not found
|
||||
- `409 Conflict`: Resource conflict
|
||||
- `422 Unprocessable Entity`: Validation error
|
||||
- `429 Too Many Requests`: Rate limit exceeded
|
||||
- `500 Internal Server Error`: Server error
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Error message",
|
||||
"error": "error_type"
|
||||
}
|
||||
```
|
||||
|
||||
Validation errors:
|
||||
```json
|
||||
{
|
||||
"message": {
|
||||
"field": ["error message"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use Personal Access Tokens**: More secure than OAuth for scripts and automation
|
||||
2. **Handle Rate Limits**: Implement exponential backoff for rate limit errors
|
||||
3. **Use Pagination**: For large datasets, implement proper pagination
|
||||
4. **Cache Responses**: Cache API responses when appropriate
|
||||
5. **Error Handling**: Always handle error responses gracefully
|
||||
6. **Project IDs**: Use URL-encoded project paths (e.g., `namespace%2Fproject`)
|
||||
7. **Webhooks**: Use webhook tokens and verify SSL certificates
|
||||
8. **Minimize Requests**: Batch operations when possible
|
||||
9. **Use Specific Scopes**: Request only necessary API scopes
|
||||
10. **Monitor Usage**: Track API usage through rate limit headers
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- Official GitLab API Documentation: https://docs.gitlab.com/ee/api/
|
||||
- API Libraries: Available for Python, Ruby, JavaScript, Go, etc.
|
||||
- GraphQL API: Available at `/api/graphql` for more efficient queries
|
||||
Reference in New Issue
Block a user