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 API.

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 authentication or CI/CD features for DevOps. More about GitLab itself, and other similar services, you can read the Top Git hosting services for 2022 article.

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 tool helpful in these topics.

There are three types of GitLab API:

  • REST – probably the most popular and the most extensive, you will find detailed information about it later in the article
  • SCIM – I mention this from 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, for example, HTTP/2 200 or HTTP/2 302, as it was in my case.

Get free trial

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. 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.

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

How to generate Personal Access Tokens for your GitLab API

And this is the result

Freshly generated Personal Access Tokens in GitLab

Now you just need to write down the result somewhere. Proceed with caution: after being created, the access token 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 projects. Some possibilities are:

Access requests

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

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” for a specific :user_id in the specific project :id:

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


Ready to work with GitLab API? Do the next best thing and secure your code with the first professional GitLab backup.


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 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 this by the “active” status. We can also add, edit or remove the user. It also allows us to combine it with other 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 works, they can use this tool to the maximum.

Comments are closed.

You may also like