GitLab offers a very extensive API
The API is located at /api/v4/
The notes how to use the API include:
Objects are referenced by ID or url-encoded path
(for example subgroup foo/bar becomes foo%2Fbar)
Resources for every aspect of GitLab
Authentication using a token (personal/group/project)
Token requires read_api or api scope
Send token in HTTP header using Private-Token:
curl "http://gitlab.${DOMAIN}/api/v4/projects" \
--silent \
--verbose \
--header "Private-Token: <your_access_token>"
GitLab API returns HTTP headers:
| Header | Description |
|---|---|
x-next-page |
Index of next page |
x-page |
Index of current page |
x-per-page |
Number of items per page |
x-prev-page |
Index of previous page |
x-total |
Total number of items |
x-total-pages |
Total number of pages |
Keyset-based pagination is also supported
cURLRetrieve projects using a private access token:
curl http://gitlab.${DOMAIN}/api/v4/projects \
--silent \
--header "Private-Token: <TOKEN>"
Check pagination headers:
curl http://gitlab.${DOMAIN}/api/v4/projects \
--silent \
--verbose \
--header "Private-Token: <TOKEN>"
glabglab was adopted as the official CLI in November 2022:
Configure glab:
glab auth login --hostname gitlab.${DOMAIN}
Search for projects:
GL_HOST=gitlab.${DOMAIN} glab repo search -s foo
Send raw API requests with automatic pagination:
GL_HOST=gitlab.${DOMAIN} glab api --paginate /projects
Token without expiry are a security threat
GitLab 16.0 (May 2023) sets a 1-year lifetime on such tokens
Rotation API introduced in GitLab 16.0 (May 2023)
Automatic reuse detection prevents use of rotated tokens: