How to Create Groups and Move Projects in GitLab

Create a group in GitLab, then transfer the project from its settings to organize access and collaboration. Choose the group visibility deliberately, confirm the transfer in GitLab, and check the project under its new group afterward.

Create a GitLab group

1. Sign in and open Groups in the top navigation, then select Your groups.
2. Choose New group and select the group creation option shown by your GitLab instance.
3. Enter a group name and URL path. The path forms part of the group URL, so choose one that is recognizable and available.
4. Set visibility to match who should be able to discover or access the group. Review the instance’s visibility choices before creating it; organization policies may restrict them.
5. Create the group. Invite members now or later, and assign only the roles they need. Group membership and project permissions affect who can work with the project.

Before creating the group, confirm the name and URL path with the people who will use it. The path is part of the address teammates will share. If you plan to automate group creation, consult the GitLab Groups API documentation for your GitLab version to confirm the supported operation, required fields, authentication, and permissions. This guide does not provide or verify a group-creation API request.

Move an existing GitLab project to a group

1. Open the project and go to Settings > General.
2. Expand or scroll to Advanced, then locate Transfer project. The exact labels can vary by GitLab version and permissions.
3. Select the destination group. Confirm that it is the intended namespace, since the project URL changes when the transfer completes.
4. Follow GitLab’s confirmation prompt, which may ask you to enter the project name, and submit the transfer.
5. Open the project from the destination group and check its new URL and namespace. If the transfer option is absent or the destination is unavailable, ask a group owner or instance administrator to review your role and transfer policy.

For automation, verify the project-transfer endpoint, request method, payload, authentication, and permission requirements in the GitLab Projects API documentation for your GitLab version before sending a request. The documentation is authoritative for the request shape; the Python example below only assembles and prints illustrative request details. Its sample IDs and payload are not instructions to copy across GitLab versions. It does not contact GitLab or verify that a request is accepted:

import json

project_id = 456
group_id = 123
request = {
    "method": "POST",
    "path": f"/api/v4/projects/{project_id}/transfer",
    "json": {"namespace_id": group_id},
}
print(json.dumps(request, sort_keys=True))

{"json": {"namespace_id": 123}, "method": "POST", "path": "/api/v4/projects/456/transfer"}

After GitLab confirms the transfer, reopen the project from the destination group and check that its namespace and URL reflect the new location. Review who can access it under the destination group’s visibility and membership settings, and confirm that intended collaborators can reach it. If you are moving several projects, handle each transfer according to the interface or API guidance for your GitLab version; do not assume a bulk-transfer option is available. Recheck the project’s history, integrations, and access as part of your team’s move checklist.