Atlas GitLab REST and GraphQL API Integration
This guide will help you configure Atlas to authenticate and proxy HTTP requests to the GitLab REST and GraphQL APIs.
GitLab is a DevSecOps platform that provides a suite of tools for hosting source code and managing various aspects of the software development lifecycle.
The GitLab REST and GitLab GraphQL APIs provide developers with programmatic access to the GitLab platform. This includes dedicated APIs for issue tracking, version control, library and package hosting, project management, automated test execution, deployments, and CI/CD.
At the end of this guide, your running instance of Atlas will be configured to:
Proxy HTTP requests to the GitLab APIs
Authenticate these requests using one or more Personal Access Tokens (or other GitLab Tokens
Availability
Public beta. This integration is available to all Atlas users, but the API may change.
Prerequisites
A running instance of Atlas. See installation guides for more details.
Provision a GitLab Personal Access Token
Step 1: [Optional] Create a dedicated GitLab user for Atlas
It is recommended but not required to create a dedicated GitLab account for generating the GitLab Personal Access Tokens Atlas needs to authenticate against the GitLab API.
The alternative is for a specific employee to generate GitLab Personal Access Tokens from their personal account, for Atlas to use. Having a dedicated GitLab account for this purpose has several advantages over this approach:
Employee-provisioned Personal Access Tokens will stop working if the employee is offboarded. For example, when a GitLab administrator removes the user from a GitLab Organization, any access tokens provisioned to access that GitLab Organization will stop working.
Dedicated GitLab accounts can be managed by a team using tools like 1Password. For example, storing the account password in 1Password allows administrators and ops teams to log in and perform routine operations like rotating secrets.
Step 2: Provision a GitLab Personal Access Token
Follow the appropriate directions under GitLab Token Overview.
Add GitLab Integration to Atlas
Once the Personal Access Token is provisioned, we will need to make it available to your running Atlas instance. We will do this by:
Adding the GitLab Personal Access Token to the Atlas configuration as an environment variable, e.g.,
GITLAB_TOKEN
.Configuring the Atlas deployment to use an HTTP adapter that adds the Personal Access Token to the
Authorization
header.
Step 1: Add GitLab Personal Access Token to Atlas Deployment as an Environment Variable
Choose an environment variable name for the GitLab Personal Access Token. Generally this is something like
GITLAB_TOKEN
.Add the GitLab Personal Access Token you provisioned as an environment variables to your Atlas deployment. The install guides have instructions for how to do this for each deployment method. For example, if you deployed Atlas using ECS, you might add an environment variable
GITLAB_TOKEN
to the Pulumi configuration. If you deployed using Kubernetes, you might add theGITLAB_TOKEN
environment variable to a.env
file.Note the name of the environment variable you chose. We will use this in the next step to configure the HTTP adapter.
Step 2: Add GitLab Personal Access Token to Atlas Configuration
We can use the mom
CLI to add the GitLab Personal Access Token to the Atlas configuration. Run this command, changing
YOUR_ATLAS_CONFIG.yml
with the path to your Atlas configuration fileGITLAB_TOKEN
to the name of the environment variable you chose in the previous stepYOUR_ADAPTER_NAME
to the name you want to use for the HTTP adapter in Atlas, e.g.,gitlab
The diff in your version control system should look something like this:
Step 3: Deploy the Updated Atlas Config
The install guides have instructions for how to deploy Atlas into a variety of environments, including Kubernetes and ECS.
Step 4: Test the Integration
Once deployed, we can use the mom curl
command to test the integration. Be sure to replace gitlab
with the name you chose in the previous step if it is something else.
Using the integration in a canvas
This integration can be used in Moment by creating a new cell in a Moment canvas, and pasting the following code. Note that you will need to assign httpAdapterName
to the name you chose for the HTTP adapter in the previous step, e.g., gitlab
If the integration is working, you should see a JSON object representing your GitLab user.
Last updated