Using Gitlab APIs: Real Use Case Scenario

Jan 22, 2020 · 4 min read
William Arias GitLab profile

Gitlab APIs along with Continuous Integration can be very helpful when executing certain bulk tasks.

Consider this requirement derived from a real-world scenario

group

runner

pipelineview

How do we test the building of those several projects and create issues and reports about its execution automatically? Let's use Gitlab CI and APIs.

1. Company groups and projects Structure

In this case, the set of projects were grouped under a single group, following this structure:

groupview

2. Automatically creating Issues leveraging Gitlab CI and API

In order to create issues using Gitlab API we will use the Issues API an example of that can use the following cURL command:

curl

The API Call:

curl --request POST --header "PRIVATE-TOKEN:$ISSUE_API_KEY" "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/issues?title=Build%20Failed&labels=ARMbuild&description=Project%20Tests%20Failed%20on%20ARM"

The previous Gitlab API call can be configured to be executed whenever a job fails. Let's dissect this API Call to understand its parameters so you can potentially customize it for your project environment

The request is of type POST, because we are sending data to our receiver service. For this call to be successful it requires authentication for which we will use PRIVATE-TOKEN header

The private token can be generated by following these steps How-to-generate-token

When we execute the above API call, we create an issue in the corresponding Gitlab project issueproject

Great, so once the multi-project pipeline has run, each of the projects that failed in its building stage will create an issue warning us to double check why it failed while documenting the failure and labeling it for future follow-up. multiproject

3. Automatically collecting all the issues from Gitlab Group

Thanks to Gitlab CI and APIs we can collect all the issues created and report them back, by adding this script in your pipeline stage

collectissues

Let's dissect again the main API call:

curl --header "PRIVATE-TOKEN:$GROUP_ISSUE_LIST" "https://gitlab.com/api/v4/groups/9123625/issues

The previous API call will return a json object, the one we will save as an artifact when executing our pipeline job. Notice this artifact is created and saved automatically by Gitlab CI Great! So far we created issues per failed project, and collected them all in one single step

4. Reporting back to Wiki Project

wikijob

For convenience, the json report was transformed to markdown, then using the following script we publish the markdown report to the Wiki of an specific project

curl --data "format=markdown&title=$CI_JOB_ID&content=$results" --header "PRIVATE-TOKEN:$API_WIKI" "https://gitlab.com/api/v4/projects/20852684/wikis"

Let's breakdown again the API call:

Finally, when the last API call has been executed, this is an example of the output we can get:

report

Let's recapitulate, by using Gitlab CI in a multi project pipeline along with APIs we were able to test and report automatically x-number of projects and its compatibility with a new hardware CPU architecture. More information about the APIs utilized for this project here:

Issues-api Collect-group-issues WikisAPI

Multi-project-pipeline

If you’d like to see GitLab’s API in action, watch this video.

For more information, visit LEARN@GITLAB.

Cover image credit:

Cover image by Mohanan on Unsplash

“” – William Arias

Click to tweet

Guide to the Cloud

Harness the power of the cloud with microservices, cloud-agnostic DevOps, and workflow portability.

Learn more
Edit this page View source