GitLab hosts source code, issues, merge requests, and CI/CD pipelines. The GitLab API connector lets your RShift Sites app call the GitLab REST API on GitLab.com, GitLab Self-Managed, or GitLab Dedicated. Use it to build apps that read or update GitLab data, such as issue dashboards, merge request queues, delivery dashboards, and developer workflows.
Choose the connection type based on whose GitLab account your app should use:
| Use | If you want to |
|---|---|
| App + chat connector (this page) | Work with one shared GitLab connection in the project chat and in your published apps |
| App user connector | Let each user of your published app connect their own GitLab account and work with data they can access |
Both connection types are available on Free, Pro, Business, and Enterprise plans. On Business and Enterprise plans, workspace admins control who can create connections and clients. On Enterprise plans, this setting defaults to No one for each connection type until an admin changes it. See Who can create connections and clients.
With GitLab API, your app can:
- List projects, branches, commits, and repository files
- Create and update issues and merge requests
- Read pipelines and their status
- Build dashboards and automations on top of GitLab data
Common use cases and example apps
Use these examples to decide whether your app needs one shared GitLab connection or per-user access.
| Example app | Description |
|---|---|
| Issue triage board | Prioritize work across projects. List open issues and group them by label, milestone, assignee, or priority. |
| Merge request review queue | Keep reviews moving. Show open merge requests, reviewers, approval status, pipeline results, and age in one place. |
| Delivery dashboard | Track what is shipping. Combine pipeline and commit data into one view for your team. |
| Repository browser | Create a tailored view of source code. Let users browse projects, branches, commits, and repository files. |
| Feedback intake workflow | Turn user feedback into issues. Create a GitLab issue when someone submits feedback or reports a bug in your app. |
| Personal developer hub | Give each user a personalized workspace. Use the app user connector so each signed-in user sees the projects, issues, and merge requests available to their own GitLab account. |
For a shared connection, you can start with a prompt like:
Use our shared GitLab connection to build an issue triage dashboard for the team's projects. Show open issues by label and assignee, and let users create a new issue.For per-user access, use the app user connector and ask RShift Sites to build the sign-in flow:
Let each signed-in user connect their own GitLab account, then show the merge requests waiting for their review.Prerequisites
Before creating an app + chat connection, make sure you have:
- Access to GitLab.com, GitLab Self-Managed, or GitLab Dedicated
- A GitLab personal, project, or group access token with the scopes and resource access your app needs
- Permission to create connections in your RShift Sites workspace, as described in Who can create connections and clients
- For a restricted Self-Managed or Dedicated instance, network rules that allow traffic from RShift Sites’ connector gateway IP ranges
How GitLab API connections work
An app + chat connection uses one GitLab access token. Everyone who uses the connection acts with that token’s identity, permissions, and resource access. You can create multiple connections with different tokens to separate teams, projects, or environments.
RShift Sites sends requests through the connector gateway. The gateway stores the token securely, adds it to GitLab requests, and keeps it out of your project code and published app.
For GitLab Self-Managed and GitLab Dedicated, the connection also stores your instance URL. RShift Sites sends API requests to that instance instead of GitLab.com.
Connect GitLab API with an access token
Step 1: Create a GitLab access token
The connector accepts three GitLab access token types:
| Token type | Access boundary |
|---|---|
| Personal access token | Resources the GitLab user can access |
| Group access token | The selected group and its projects |
| Project access token | One project |
Choose the narrowest token type that covers your app’s use case. See the GitLab token overview for the requirements and availability of each token type.
Open the token settings in GitLab
For a personal access token, sign in to GitLab, select your avatar, and open Edit profile → Access → Personal access tokens.
For a group or project access token, open the relevant group or project settings and follow GitLab’s access token documentation.
Choose the minimum required scope
Select read_api if your app only reads GitLab data. Select api if the app creates or changes projects, issues, merge requests, pipelines, or repository files.
Your token also inherits the permissions and resource access of the user or bot account that owns it. A scope cannot grant access that account does not already have.
Set an expiration date
Choose an expiration date that follows your organization’s security policy. Before the token expires, plan to rotate it and update the RShift Sites connection.
Generate and copy the token
Generate the token and copy it when GitLab displays it. GitLab does not show the token again after you leave or refresh the page.
For detailed instructions, see Personal access tokens and Access token scopes in the GitLab documentation.
Step 2: Connect GitLab API to RShift Sites
Add and verify the shared connection in RShift Sites.
Open GitLab API in Connectors
Open Connectors and select GitLab API.
See Where to find connectors for the other places you can open the catalog.
Add an app + chat connection
Click Add connection, then select App + chat connector.
Configure the connection
- Display name (optional): name the connection, for example
GitLab Production. Leave it blank and RShift Sites generates a name. 2. Access token: paste the personal, project, or group access token you created. 3. Instance URL (optional): leave this empty for GitLab.com. For GitLab Self-Managed or GitLab Dedicated, expand Advanced settings and enter the instance’s HTTPS root URL, for examplehttps://gitlab.example.com. Do not add/api/v4or a resource path.
Choose who can use the connection
Under Sharing, the connection is private to you by default. To share it, click Share with others. Then add workspace members by email, or click Invite entire workspace.
Everyone with access can link the connection to projects and use the GitLab data available to its token. See Who can use connections and clients.
Connect
Click Connect. RShift Sites verifies the access token with the configured GitLab instance before saving the connection.
Link the connection to a project
In the project’s chat, tell RShift Sites what you want to build with GitLab. RShift Sites links a connection you can access, then builds the feature.
Limitations
The GitLab app + chat connector documented on this page cannot:
- Use GitLab OAuth for separate end-user accounts. For per-user OAuth, use the GitLab app user connector.
- Replace GitLab Git sync for exporting or two-way syncing your RShift Sites project’s codebase.
- Access resources outside the token owner’s membership, role, token type, or selected scopes.
- Refresh or rotate personal, project, or group access tokens automatically. Update the connection when a token expires, is revoked, or is rotated.
- Reach a Self-Managed or Dedicated instance that blocks RShift Sites’ connector gateway traffic.
- Bypass GitLab or RShift Sites gateway rate limits.
Troubleshooting
Use these checks if the connection or a GitLab API request fails.
The connection says my access token is invalid
Confirm that the token is active, has not expired or been revoked, and belongs to the GitLab instance in Instance URL. Leave Instance URL empty for GitLab.com.
A request returns 401 Unauthorized
The token has usually expired or been revoked. Create or rotate the token in GitLab, then update the connection with the new value.
A request returns 429 Too Many Requests
The GitLab account or instance has reached an API rate limit. Wait for the period in the Retry-After response header, reduce polling frequency, and avoid retrying in a fast loop.
A project or resource returns 404 even though it exists
GitLab can return 404 for private resources the token cannot access. Confirm the token owner’s membership, role, token type, and scope. When using a project path in an API call, make sure the namespace and project path are URL-encoded exactly once.
RShift Sites cannot reach my GitLab instance
Confirm that the instance uses HTTPS and is reachable from the public internet or from RShift Sites’ connector gateway IP ranges. If the instance stays private behind a VPN or firewall, the connector cannot call it.
Manage your {connector_0} connection
Connections are managed from Connectors: select {connector_0}, then open the connection.
- Unlink projects to remove {connector_0} access from specific projects while keeping the connection available for others. See Unlink projects from a connection for the steps.
- Delete the connection to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use {connector_0} stop working until a new connection is added. See Delete a connection for the steps and who can delete.