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

Last Updated on December 11, 2024

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

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 from 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 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” private token 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 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.

[FREE TRIAL] Ensure compliant DevOps backup and recovery with a 14-day trial 🚀
[CUSTOM DEMO] Let’s talk about how backup & DR software for DevOps can help you mitigate the risks

Frequently Asked Questions

How do I use API in my project?

To use an API in your project, you should follow the next steps:

• Obtain API access – Register with the service to get an API key or authentication token.
• Choose an HTTP client – To interact with the API, use an HTTP client like curl or Postman or code libraries – such as Axios (JavaScript), Requests (Python), or RestSharp (C#).
• Understand API documentation – Review the API’s documentation to understand endpoints, methods (GET, POST, PUT, DELETE), authentication, rate limits, and error handling.
• Make API calls – Write code that sends HTTP requests to API endpoints. For example:

import requests

url = "https://api.example.com/data"
headers = {"Authorization": "Token YOUR_API_TOKEN"}
response = requests.get(url, headers=headers)
print(response.json())

• Handle responses – Process the API’s JSON or XML responses and integrate them into your application.

Does GitLab have a workflow?

GitLab supports different workflows for continuous integration, continuous deployment, and version control. These can be defined using the .gitlab-ci.yml configuration file, which allows you to define pipelines for building, testing, and deploying your code.

GitLab’s workflow features include:

• Branching models: GitLab supports Git Flow, Feature Branch Workflow, and GitHub Flow models.
• Merge requests (MR): Similar to pull requests, MRs enable code review and approval before merging.
• CI/CD pipelines: Automatically build, test, and deploy applications based on code changes.
• Issue tracking and boards: Manage project tasks and workflows through integrated issue tracking and project boards.

GitLab automates steps for CI/CD workflows using pipelines triggered by events like code commits or MR approvals.

How to create a GitLab API token for Jenkins?

Take a few steps to use a GitLab token for integration with Jenkins.

Create a GitLab Personal Access Token:

• go to your GitLab account
• navigate to User Settings -> Access Token
• name the token and select the required scopes (e.g., API, read_repository)
• click Create Personal Access Token and copy the token for Jenkins.

Configure Jenkins to use the Token:

• in Jenkins, go to Manage Jenkins -> Credentials
• add a new Secret Text credential and paste your GitLab token.

Integrate the GitLab API in Jenkins

• Use a Jenkins plugin (e.g., GitLab Plugin) to authenticate via the token for tasks such as triggering jobs or fetching repository data.

How do I change developer permissions in GitLab?

If you want to change developer permissions in GitLab:

1. Navigate to the project where you want to modify permissions.
2. Click on Settings -> Members.
3. Locate the developer whose permissions you plan to change.
4. In the Role dropdown next to the user’s name, select the new role (e.g., Maintainer or Reporter).
5. Save the changes.

You can also set permission (for different access levels) through groups to manage access for multiple projects simultaneously.

How do I rename a GitLab API project?

Renaming a GitLab project via the GitLab API requires you to:

Use the PUT request to modify through the GitLab API.

• API Endpoint: PUT /projects/:id
• Replace :id with your project ID or URL-encoded path.

The request body should include the new name:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \ --data "name=NewProject" \
"https://gitlab.example.com/api/v4/projects/<project_id>"

The command changes the project’s name to NewProject.

Of course, you can rename the project manually in the GitLab Web UI under Settings -> General -> Project Name.

Before you go:

✍️ Subscribe to GitProtect DevSecOps X-Ray Newsletter and always stay up-to-date with the latest DevSecOps insights

🔎 Find out what security duties you have within the GitLab Shared Responsibility Model and if there is a way to reduce them

👀 Check out what security incidents and vulnerabilities GitLab faced in 2023

📚 Learn which GitLab backup best practices to implement into your security strategy to have peace of mind that your source code is safe and sound

🌟 See on practice how GitProtect helps Turntide Technologies, named “The Next Big Thing In Tech” and “A World Changing Idea”, back up and recover the company’s GitLab and Jira data

📅 Schedule a live custom demo and learn more about GitProtect backups for your GitLab data protection

📌 Or try GitProtect backups for your GitLab ecosystem to ensure that a single line of your code is never lost