GitLab Integration

Documentation Index

Fetch the complete documentation index at: https://docs.modelcode.ai/llms.txt

Use this file to discover all available pages before exploring further.

Modelcode connects to your GitLab repositories through GitLab OAuth. This guide covers how the connection works, how to manage your repositories, and how to configure publishing targets for your migration.

​

Prerequisites

• A Modelcode account (sign up at modelcode.ai)
• A GitLab.com (SaaS) account — not a self-hosted instance
• At least one repository you want to work with

​

How It Works

Modelcode uses GitLab OAuth to authenticate and access your repositories:

1. Sign in with GitLab — You authenticate with your GitLab account on Modelcode’s login page. This establishes your identity and grants Modelcode permission to access your repositories.
2. Repository access — Once signed in, Modelcode can list and read the repositories your GitLab account has access to. No separate app installation is required — your OAuth token provides access.

Unlike GitHub (which requires a separate GitHub App installation), GitLab access is granted in a single sign-in step through OAuth scopes.

​

Signing In with GitLab

​

Step 1: Choose GitLab as Your Provider

1. Go to modelcode.ai
2. On the login page, click Continue with GitLab
3. You’ll be redirected to GitLab’s authorization page

​

Step 2: Authorize Modelcode

On GitLab, the OAuth application appears as Morph (the Modelcode integration).

1. Review the permissions Morph is requesting (API access, repository read/write, profile, and related scopes as shown)
2. Click Authorize Morph to grant access
3. You’ll be redirected back to Modelcode

Once complete, you’ll land on the Projects page with GitLab connected. Your OAuth token is securely stored and used for all subsequent GitLab operations.

​

Creating a Project with GitLab Repositories

Once GitLab is connected:

1. Click Create Project on the Projects page
2. Enter a project name (auto-filled from your first repository name)
3. In the repository dropdown, select one or more repositories from your GitLab account
4. For each repository, confirm or change the origin branch
5. Set a feature branch name (prefixed with morph-)
6. Click Create Project

Modelcode automatically resolves the GitLab principal (user, group, or project context) for each repository based on its namespace. No manual configuration is needed during project creation.

​

If the Repository Dropdown Is Empty

If no repositories appear after connecting GitLab:

1. Verify your GitLab account has access to the repositories you expect
2. Check that the OAuth authorization was completed successfully
3. Try refreshing the page — the repository list is fetched from GitLab via Modelcode’s backend

​

Understanding GitLab Principals

When Modelcode publishes migration output (creates branches, pushes code) to GitLab, it uses a principal to determine credentials and permissions. A principal represents the GitLab entity that owns or manages the target repository.

​

Principal Types

Modelcode automatically infers the correct principal for each repository based on its namespace. In the approval UI, principals are displayed as path (type) — for example, my-company/platform (group).

​

How Principals Are Resolved

When you create a project or approve a migration plan, Modelcode resolves principals in the following order:

1. Namespace match — Matches the repository’s GitLab namespace ID and kind (user or group)
2. Declared user — Matches an explicitly declared user principal on the repository
3. Project ID — Matches the GitLab project ID directly
4. Group path — Matches a group token whose path is a parent of the repository’s namespace

In most cases, this resolution is automatic and requires no user input.

​

Approving a Migration Plan

When reviewing and approving a migration plan for a GitLab project:

1. Open Project Knowledge from the Roadmap (Modernization → Project Knowledge) with Project Spec selected
2. Review the generated migration plan
3. For each new repository in the plan, a GitLab principal dropdown appears
4. Select the principal (user, group, or project) that should own the published repository
5. Click Approve

The principal dropdown is populated from your connected GitLab account. Modelcode combines principals from stored tokens and your repository list to provide all available options.

​

Troubleshooting

​

”No repositories found”

If Modelcode says GitLab is connected but no repositories are available:

1. Verify your GitLab account has access to the repositories you expect
2. The OAuth token may have expired — sign out and sign in again with GitLab
3. Check that the repositories are not archived or restricted in GitLab

​

”GitLab principal” dropdown is empty

If the principal dropdown shows no options when approving a migration plan:

1. Your GitLab OAuth session may have expired — refresh the page
2. If the issue persists, sign out and sign in again with GitLab to refresh the OAuth token
3. Verify that your GitLab account has the necessary permissions on the target group or project

​

”Missing GitLab principal context”

If you see this error during project creation:

1. The repository metadata may be incomplete — close the modal, refresh the page, and try again
2. Reconnect GitLab by signing out and signing in again
3. Ensure your GitLab account has at least Developer access to the repository

​

”Failed to load GitLab principal tokens”

This indicates a backend communication issue:

1. Refresh the page and try again
2. If the error persists, check your network connection
3. Contact support if the issue continues

​

”We couldn’t load GitLab accounts for publishing”

This message appears in the project overview when principals cannot be loaded:

1. Reconnect GitLab using the same flow as when you add a repository
2. Refresh the page after reconnecting
3. If you already use GitLab in this project, a simple page refresh may resolve the issue

​

Next Steps

• Quickstart — Create your first migration project
• Define Modernization Goals — Write effective goals for your migration
• Modernization Instructions — Learn how to review and approve your migration plan