How to use the GitLab REST API
The GitLab API allows you to perform many of the actions you typically do when using the user interface. Using the API allows us to automate the process and eliminate any user interaction.
The GitLab API comes in two flavors: the REST API and the GraphQL API. For people just getting started with APIs, the REST API is much easier to understand and use. So this is what I will be demoing in this tutorial.
How to use the GitLab REST API
The GitLab API specification defines various endpoints based on the action we want to perform.
Let’s do a simple request using Postman.
I am using gitlab.com, so the GitLab API base URL will be this:
If you are self-hosting GitLab, your base URL will look like this:
I will call the projects endpoint to get a list of all public projects.
If you want to get details about a project, all you need is to append the project id to the URL.
If the project is not public, you may get a 404 Not found status code.
GitLab API authentication
So far we have used the GitLab API to get information that is publicly available. However, essentially any action we want to perform is not available to everyone. So we need to authenticate your requests.
There are multiple ways to do this, but for what we are trying to do, a personal access token will suffice.
Go to your user profile and select Access Tokens. Give your new token a name that makes sense to use and select the api scope.
How that the token has been created, copy it, and let’s added it to the Postman request.
Go to the Authorization tab, select Bearer Token from the list, and paste the value in the respective field.
Now you can start doing useful things.
If you enjoy content like this and it helped you solve a problem, help me create more. Please leave a comment, share, and press that 👏 a few times (up to 50 times).
And consider subscribing to Medium for more amazing content.
How to get an artifact by job name
Here is a simple example. Let’s say we want to get a job artifact. The endpoint we need to use according to the GitLab API documentation is
GET /projects/:id/jobs/artifacts/:ref_name/download?job=name
Here are a few parameters we need to understand:
id— this is the project idref_name— this is the Git ref, typically the name of the branch. Trymainormaster.job=name— replacenamewith the name of the job that generated the artifact.
Using the GitLab API in GitLab CI pipelines
We have used the GitLab API inside Postman because it is easier to understand the debug. However, once the requests work as you expect, you may want/need to use them inside your GitLab CI pipeline.
While you could use Postman (with a CLI tool called Newman), for most cases, using cURL is much faster.
You can go to any Postman request and export it as a cURL command.
This will open the code generator. Select cURL from the list.
Don’t use any credentials in your GitLab CI pipeline configuration. Always use variables.
If you want to learn how to build pipelines in Gitlab CI, I have created an online course that starts with the basics of Gitlab CI and YAML and helps you understand the fundamentals of CI/CD. Learn more about the course.
Troubleshooting
Status 404 Not found
If you are getting this error, recheck your URL. Make sure all mandatory parameters are included. Make sure you don’t have any spaces or other characters in the value fields.
Syntax is incorrect: script config should be a string or a nested array of strings up to 10 levels deep
This is a very common error you may encounter when using cURL inside GitLab CI job configs. Quite often the reason for this is the column character : which has a special meaning in YAML.
To solve this, put your entire command between single or double quotes, depending on which quotes you have already used inside the command itself.
Conclusion
I hope this tutorial helped you get started with using the GitLab API. Leave a comment in the section below if you have any questions. I would love to hear from you!
Thank you for sticking with this article until the end. If you enjoyed it, please leave a comment, share, and press that 👏 a few times (up to 50 times). It will help others discover this information and maybe it will help someone else as well.
Follow me on Medium and YouTube if you’re interested in more tutorials like this one.
Want to learn how to use Git for Gitlab?
To take full advantage of GitLab, you need to know Git. So if you are interested in learning more about how you can use Git for your Gitlab projects, maybe you want to take a look at my Introduction to Git for GitLab online course. You can take this course on Skillshare for FREE (14 days trial).
