GitLab in ChatGPT and Codex is currently in beta.
Overview
Use the GitLab Self-Managed app template to create a workspace-specific draft app for a GitLab Self-Managed or GitLab Dedicated instance. Provide the GitLab hostname and OAuth application credentials, review the draft app, and then publish it for eligible workspace members. After publication, the app’s enabled actions are available in ChatGPT conversations and Codex sessions.
For an overview of supported GitLab behavior, availability, permissions, data use, and network requirements, see: Connecting GitLab to ChatGPT and Codex.
What you are setting up
You are creating a workspace-specific app from the GitLab Self-Managed app template. The app uses:
A GitLab OAuth application registered on your GitLab Self-Managed or GitLab Dedicated host.
The GitLab OAuth Application ID and Secret for user authorization.
The required OAuth scopes: api, write_repository, and openid.
Your GitLab hostname, such as gitlab.example.com, to derive the web, API, authorization, and token endpoints.
Before you begin
You need:
ChatGPT workspace admin or owner access.
GitLab permission to create the OAuth application: group Owner access for a group-owned app, or instance administrator access for an instance-wide app.
The GitLab hostname only, without https://, a port, or a path. Use a GitLab Self-Managed or GitLab Dedicated host, not gitlab.com.
A decision about which GitLab actions ChatGPT and Codex should support, such as repository search, merge request workflows, issue workflows, file edits, or broader Codex workflows.
Keep ChatGPT and GitLab open in separate tabs. Copy the exact Redirect URI shown in ChatGPT; do not create or modify it.
Values to prepare
GitLab hostname: for example, gitlab.example.com.
Redirect URI: copy this from the ChatGPT template setup flow.
GitLab OAuth Application ID.
GitLab OAuth Secret.
OAuth scopes: copy these from the ChatGPT template setup flow.
Start the template setup in ChatGPT
In ChatGPT, switch to the workspace where the app should be available.
Go to Workspace settings > Plugins.
In Directory, find GitLab, open its GitLab Self-Managed app template, and select Enable.
Enter a clear app name and description.
Enter the GitLab hostname, such as gitlab.example.com.
Copy the Redirect URI shown in ChatGPT, and keep this tab open.
Example: https://chatgpt.com/connector/oauth/<redirect_id>. Do not remove the redirect ID, add a trailing slash, or replace the URI with a generic ChatGPT URL.
Create the GitLab OAuth application in GitLab
Choose where to create the application
Open your GitLab host, such as https://gitlab.example.com.
Choose whether to create an instance-wide application or a group-owned application. This choice determines who manages the application; project access still follows the authorizing user’s GitLab permissions and the granted OAuth scopes.
For an instance-wide application, go to Admin > Applications. For a group-owned application, go to the group’s Settings > Applications.
Add the application details
Select New application or Add new application.
Enter a clear app name, such as GitLab Self-Managed or GitLab Dedicated.
In Redirect URI, paste the exact URI copied from ChatGPT.
Keep Confidential enabled for this server-side OAuth application.
Configure access and save
For an instance-wide application, GitLab recommends selecting Trusted. This skips the user authorization prompt.
Select the api, write_repository, and openid scopes.
Review who can manage the application, and confirm that authorizing GitLab users have the appropriate group and project permissions.
Save the application.
OAuth scope requirements
The template requests the following OAuth scopes for enabled GitLab actions in ChatGPT and Codex:
api: required for GitLab API operations exposed by the app, including merge request, issue, and CI/CD actions.
write_repository: required for repository write operations over Git.
openid: required for OpenID Connect identity and membership information.
Copy the GitLab OAuth credentials
In the saved GitLab application, copy the Application ID and Secret. Treat the Secret as a credential. If it is exposed, renew it in GitLab and create a new workspace app.
Finish setup in ChatGPT
Return to the ChatGPT template setup tab.
Paste the GitLab Application ID into OAuth client ID.
Paste the GitLab Secret into OAuth client secret.
Confirm that the GitLab hostname contains only the hostname, such as gitlab.example.com.
Select Create draft.
Open the draft app details and review Role access and Configure actions.
Publish and manage the app for ChatGPT and Codex
Creating the draft app does not automatically make it available to members. After reviewing the draft:
Select Publish for the draft app.
Go to Workspace settings > Plugins, and confirm that GitLab is available to the intended roles.
Review Role access for the roles that should use the app.
In Configure actions, review the available read and write actions.
In Configure approvals, choose when users must approve an action before ChatGPT or Codex uses the app.
Ask a test user with access to open GitLab from the Plugin directory or Settings > Plugins. Confirm that the user can install the plugin and connect to the app created from the GitLab Self-Managed template.
These app approval settings apply to ChatGPT conversations and Codex threads.
Set up GitLab activity for Codex code review
After the app is published, configure GitLab activity in Codex if you plan to use Codex code review. This activity setup configures the required webhook events.
Open Codex connector settings.
Configure a workspace service account. Let Codex create the account, or provide a personal access token for an existing service account.
Enable GitLab activity for the project or one of its parent groups.
If Codex needs to run coding tasks or use project-specific setup, create a project environment.
The GitLab app uses user OAuth for reads and enabled actions in ChatGPT and Codex. For Codex review writes on GitLab Self-Managed or GitLab Dedicated, the workspace-managed service-account token determines the identity and projects where Codex can comment or react.
Read more: Review GitLab merge requests with Codex.
Connect and test the GitLab app
As a user with access, open GitLab from the Plugin directory or Settings > Plugins. Select Install Plugin, and then select Connect.
If your workspace has more than one GitLab app, choose the app for this GitLab Self-Managed or GitLab Dedicated host.
Authorize the GitLab OAuth application when prompted.
Run a small read action first in ChatGPT or Codex, such as listing accessible projects or fetching a known merge request.
If write actions are enabled, test them in a low-risk project and in each product where you plan to use them before broader rollout.
Hostname and OAuth behavior
The app uses the hostname to derive GitLab endpoints. Enter only the host, such as gitlab.example.com. Do not include https://, an API or repository path, a port, or gitlab.com. This template is for GitLab Self-Managed or GitLab Dedicated. For GitLab.com (SaaS), use the GitLab app.
Troubleshooting GitLab Self-Managed app setup
Redirect URI mismatch: Confirm that the GitLab OAuth application's Redirect URI exactly matches the Redirect URI shown in ChatGPT.
ChatGPT cannot create or save the draft app: Confirm that the hostname, Application ID, Secret, and Redirect URI are present.
Authentication succeeds but project calls fail: Confirm that the authorizing GitLab user can access the project and that the OAuth application has the template scopes.
API returns 403 or insufficient permissions: Confirm that the connected GitLab account has the required project or group permissions and that the OAuth application includes the required template scopes.
No projects are accessible: Confirm that the user has project access, is connected to the intended GitLab instance, and selected the correct GitLab app in ChatGPT or Codex.