How to Use GitLab API – Best Practices for Your Development Team

Probably every developer is using some kind of version control system these days. From a novice intern to an experienced tech lead. This is not surprising for us. Moreover, such knowledge is very useful and even required in the industry. According to all available reports, Git is the most popular version control system. In addition, the three big Git hosting sites, namely GitHub, Bitbucket, and GitLab, are the most used. We will devote the following material to the latter, and specifically, we will focus on the GitLab APIs.

What exactly is GitLab?

As I mentioned, GitLab is one of the largest hosting services for Git VCS. Therefore, it provides all the functionalities of this system and also adds many others, such as an authentication method or GitLab CI/CD (continuous integration/continuous delivery) features for DevOps. More about GitLab itself, and other similar services, you can read in our article: Top Git hosting services for 2022.

Another very useful thing is the GitLab API. It is a tool that allows you to automate your work. Many of the basic operations that we perform manually every day can be automated. This will save us time, workload, and also reduce the number of potential problems that the user can always accidentally commit. Using API is also beneficial from the perspective of e.g. audit or compliance because it gives us the opportunity to build a rather helpful tool in these topics.

There are three types of GitLab API:

• REST – probably the most popular and the most extensive one for easy access using regular API requests (you will find detailed information about it later in the article)
• SCIM – I mention this form as a formal obligation, without going into details. It introduces a /Users endpoint for cross-domain identity management
• GraphQL – it co-exists with v4 of REST API and according to the very idea of GraphQL, it allows you to create a request for only what we need

Let’s look at this GitLab API example:

curl –include “https://gitlab.com/username/api/v4/projects”

Such a query returns all projects of a given user. The –include flag also returns HTTP response header, for example, HTTP/2 200 or HTTP/2 302, as it was in my case.

Access control and authentication

Yes, I received the above HTTP/2 302 code for a reason. This code means a redirection, in particular a redirection to the address https://gitlab.com/users/sign_in. Why so? For authentication of course, as this API does care about the access control of authenticated user. Actually, this is the first detailed topic in the GitLab API documentation. And it does not surprise me at all, because the subject of authorization and access control is crucial, otherwise all the rest of the functionality would simply make no sense and conflicting resource.

One way to handle the authentication is to use the Personal access token. To start using this feature, we just need to create a new private token in the user account settings (Access Tokens tab), the scope of which will be marked as API, as shown in the picture below:

And this is the result

Now you just need to write down the result somewhere. Proceed with caution: after being created, the access tokens will be shown only once. The Group access token works in a very similar way, it simply applies to the entire group of users.

Project-level access

It is interesting and useful to set the scope for a given access token, e.g. scope “api” grants complete read / write access to the project, including Package Registry. On the other hand, we can use scope just for read access (pull) to the repository, which is called “read_repository”. This allows us to easily control the permissions of entire groups or projects.

GitLab REST API capabilities

Now let’s go over some useful REST endpoints that we can use to automate everyday tasks. We can separate three contexts here for easier grouping of queries.

Projects context

As the name suggests, here we have endpoints for interacting with entire GitLab projects. Some possibilities are:

Access requests

Here we can view current API request for access, grant, or receive the appropriate level of it. Some API endpoints from the GitLab API documentation look like this:

GET /projects/:id/access_requests
PUT /projects/:id/access_requests/:user_id/approve
DELETE /projects/:id/access_requests/:user_id

An example query that will allow you to give “Developer access” private token for a specific :user_id in the specific project 🆔

curl –request PUT –header “PRIVATE-TOKEN: ” “https://gitlab.com/company/project/api/v4/projects/:id/access_requests/:user_id/approve?access_level=30”

Branches

Possibility to get a list of branches, a particular single branch or to create one. We can also use this to protect (or unprotect) branches. Examples:

GET /projects/:id/repository/branches/:branch
POST /projects/:id/protected_branches
POST /projects/:id/repository/branches
DELETE /projects/:id/repository/branches/:branch

Issues

It allows us to get a list of issues for a given parameter. Be aware, that by default it returns up to 20 issues at a time due to pagination. Of course, we can also create a new issue, unsubscribe one or turn it into an epic. It has all that you may need. Some examples:

GET /issues?assignee_id=5
POST /projects/:id/issues/:issue_iid/move
POST /projects/:id/issues/:issue_iid/unsubscribe

Groups context

That one is for the operations on groups. Some of them overlap with what Projects context allows, the only difference is scope.

Access requests

The principle of operation is the same as described above. The only difference is in the endpoint address. For example:

GET /projects/:id/access_requests
GET /groups/:id/access_requests

Issues

Also a similar operation, simply extended to operations on groups. In this case, however, the endpoint will be extended with group id number:

GET /issues?state=opened
GET /groups/:id/issues?state=opened

Members

This endpoint is used for group operations. We can list group members, check if a given user belongs to a given group members and, of course, add or remove a member from the group. Examples:

GET /groups/:id/members
PUT /groups/:id/members/:user_id
PUT /groups/:id/members/:member_id/approve

Standalone context

This group allows operations outside of project or group contexts. We may use here the /users endpoint to get a list of users, single users, or even filter them by the “active” status. We can also add, edit or remove the user. It also allows us to combine it with other API functions, e.g. download projects for a given user.

For GitLab Premium or higher accounts, there is also the /audit_events option, which allows us to automate this feature as well. For more information on audit_events, please refer to the GitLab documentation.

Of course, this is just a modest summary. We can also perform operations on commits, releases, tags, and others. Almost everything we can do through the user interface in the browser can be automated by using this feature. As an example, I will give each IDE that is currently using the GitLab REST API to perform operations in VCS. And nothing prevents us from creating our own tool that will help us in our daily work.

Conclusion

The main benefit that this API provides us is the possibility of automation. Huge possibilities to improve each VCS related task. Not only the basic operations that developers perform every day but above all improvements from the perspective of project management and control. All matters for audits and compliance can be fully automatic, and relatively little work can result in a powerful tool for their implementation.

Of course, we could also use these possibilities to create a system for automatic handling of backups and restorations plans, but why re-invent the wheel when there are already-made tools for this. Effective leaders should know how to use GitLab to achieve their goals. And knowing how the API and API request work, recieving error messages, they can use this tool to the maximum.

✍️ Subscribe to GitProtect DevSecOps X-Ray Newsletter – your guide to the latest DevOps & security insights

🚀 Ensure compliant DevOps backup and recovery with a 14-day free trial

📅 Let’s discuss your needs and see a live product tour