Import API | GitLab Docs Skip to main content Go to GitLab Docs homepage What's new? What's new? Get free trial Toggle menu * Use GitLab * GitLab Duo * GitLab Orbit * Extend * Install * Administer * Subscribe * Contribute * Solutions Getting started Tutorials Integrations Webhooks REST API Resources .gitignore (templates) .gitlab-ci.yml (templates) Access requests Agent for Kubernetes AI Catalog admin Alert management Application appearance Application settings Application statistics Applications Attestations Audit events Avatar Branches Broadcast messages Cluster discovery (certificate-based) (deprecated) Code Suggestions Commits Compliance and policy settings Container registry Container virtual registry Custom attributes Database migrations Data management Dependencies Dependency firewall Dependency list export Deploy keys Deploy tokens Deployments Discussions Dockerfile (templates) DORA4 metrics Emoji reactions Environments Epics (deprecated) Error tracking Events Experiments External status checks Feature flags Feature flag user lists Flows Freeze periods Geo nodes (deprecated) Geo sites GitLab Duo Chat completions GitLab Pages GLQL Google Cloud integration Groups Import Instance CI/CD variables Invitations Issues Issues (epic) (deprecated) Issues statistics Jobs Job artifacts Job token scopes Keys License Licenses (templates) Linked epics (deprecated) Links (issue) Links (epic) (deprecated) Lint .gitlab-ci.yml Markdown Maven virtual registry Member roles Merge request approvals Merge request approval settings Merge request context commits Merge requests Merge trains Metadata Model registry Namespaces Notes (comments) Notification settings Orbit Organizations Package registry Pages domains Personal access tokens Pipeline schedules Pipeline trigger tokens Pipelines Plan limits Projects Repositories Repository files Repository submodules Resource group Resource iteration events Resource label events Resource milestone events Resource state events Resource weight events Runners Runner controllers Runner controller tokens Search Search migrations Secrets Manager API Secure files Service accounts Service Ping Sidekiq metrics Sidekiq queues Snippet repository storage moves Snippets Suggestions System hooks Tags To-Do List Token information Topics Users User applications Virtual registries cleanup policies Vulnerabilities Vulnerability archive export Vulnerability export Vulnerability findings Web commits Authentication Third-party clients Deprecations and removals OpenAPI Automate storage management Troubleshooting GraphQL API OAuth 2.0 identity provider API GitLab MCP server GitLab Duo CLI (duo) GitLab CLI (glab) Editor and IDE extensions * GitLab Docs / * Extend / * REST API / * Resources / * Import Help us learn about your current experience with the documentation. Take the survey . Import API * Tier : Free, Premium, Ultimate * Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated History * Reassigning contributions to a personal namespace owner when importing to a personal namespace introduced in GitLab 18.3 with a feature flag named user_mapping_to_personal_namespace_owner . Disabled by default. * Reassigning contributions to a personal namespace owner when importing to a personal namespace generally available in GitLab 18.6. Feature flag user_mapping_to_personal_namespace_owner removed. * single_endpoint_notes_import made always enabled for newly configured imports in GitLab 19.4, and can no longer be disabled. Imports configured on earlier GitLab versions keep their previously configured value. The availability of this feature is controlled by a feature flag. For more information, see the history. Use this API to import repositories from external sources . User contribution mapping is not supported when you import projects to a personal namespace . When you import to a personal namespace, all contributions are assigned to the personal namespace owner and they cannot be reassigned. Import repository from GitHub Imports a repository from GitHub to GitLab. Prerequisites: * Prerequisites for GitHub importer . * The namespace set in target_namespace must exist. * The namespace can be your user namespace or an existing group that you have the Maintainer or Owner role for. POST /import/github Attribute Type Required Description personal_access_token string Yes GitHub personal access token. repo_id integer Yes GitHub repository ID. target_namespace string Yes Namespace to import repository into. Supports subgroups like /namespace/subgroup . Must not be blank. github_hostname string No Custom GitHub Enterprise hostname. Do not set for GitHub.com. From GitLab 16.5 to GitLab 17.1, you must include the path /api/v3 . new_name string No Name of the new project. Also used as the new path so must not start or end with a special character and must not contain consecutive special characters. optional_stages object No Additional items to import . pagination_limit integer No Number of items retrieved per API request to GitHub. The default value is 100 items per page. For project imports from large repositories, a lower number can reduce the risk of GitHub API endpoints returning 500 or 502 errors. However, a smaller page size increases migration times. timeout_strategy string No Strategy for handling import timeouts. Valid values are optimistic (continue to next stage of import) or pessimistic (fail immediately). Defaults to pessimistic . curl --request POST \ --url "https://gitlab.example.com/api/v4/import/github" \ --header "content-type: application/json" \ --header "Authorization: Bearer <your_access_token>" \ --data '{ "personal_access_token": "aBc123abC12aBc123abC12abC123+_A/c123", "repo_id": "12345", "target_namespace": "group/subgroup", "new_name": "NEW-NAME", "github_hostname": "https://github.example.com", "optional_stages": { "attachments_import": true, "collaborators_import": true } }' The following keys are available for optional_stages : * attachments_import , for Markdown attachments import. * collaborators_import , for importing direct repository collaborators who are not outside collaborators. * single_endpoint_notes_import , for an alternative and more thorough comments import method that is optional on GitLab 19.3 and earlier. On GitLab 19.4 and later, this method is mandatory for newly configured imports. For more information, see select additional items to import . Example response: { "id" : 27 , "name" : "my-repo" , "full_path" : "/root/my-repo" , "full_name" : "Administrator / my-repo" , "refs_url" : "/root/my-repo/refs" , "import_source" : "my-github/repo" , "import_status" : "scheduled" , "human_import_status_name" : "scheduled" , "provider_link" : "/my-github/repo" , "relation_type" : null , "import_warning" : null } Import a public project through the API using a group access token When you import a project from GitHub to GitLab through the API using a group access token: * The GitLab project inherits the original project s visibility settings. As a result, the project is publicly accessible if the original project is public. * If the path or target_namespace does not exist, the project import fails. Cancel GitHub project import Cancels an in-progress GitHub project import. POST /import/github/cancel Attribute Type Required Description project_id integer Yes GitLab project ID. curl --request POST \ --url "https://gitlab.example.com/api/v4/import/github/cancel" \ --header "content-type: application/json" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data '{ "project_id": 12345 }' Example response: { "id" : 160 , "name" : "my-repo" , "full_path" : "/root/my-repo" , "full_name" : "Administrator / my-repo" , "import_source" : "source/source-repo" , "import_status" : "canceled" , "human_import_status_name" : "canceled" , "provider_link" : "/source/source-repo" } Returns the following status codes: * 200 OK : the project import is being canceled. * 400 Bad Request : the project import cannot be canceled. * 404 Not Found : the project associated with project_id does not exist. Import GitHub gists into GitLab snippets Imports personal GitHub gists into GitLab snippets. You can import gists with up to 10 files. GitHub gists with more than 10 files are skipped. You should manually migrate these GitHub gists. If any gists couldn t be imported, an email is sent with a list of gists that were not imported. POST /import/github/gists Attribute Type Required Description personal_access_token string Yes GitHub personal access token. curl --request POST \ --url "https://gitlab.example.com/api/v4/import/github/gists" \ --header "content-type: application/json" \ --header "PRIVATE-TOKEN: <your_gitlab_access_token>" \ --data '{ "personal_access_token": "<your_github_personal_access_token>" }' Returns the following status codes: * 202 Accepted : the gists import is being started. * 401 Unauthorized : user s GitHub personal access token is invalid. * 422 Unprocessable Entity : the gists import is already in progress. * 429 Too Many Requests : the user has exceeded GitHub s rate limit. Import repository from Bitbucket Server History * Validation of bitbucket_server_project and bitbucket_server_repo introduced in GitLab 19.1. Imports a repository from Bitbucket Server to GitLab. The Bitbucket Project Key is only used for finding the repository in Bitbucket. You must specify a target_namespace if you want to import the repository to a GitLab group. If you do not specify target_namespace , the project imports to your personal user namespace. Prerequisites: * For more information, see prerequisites for Bitbucket Server importer . POST /import/bitbucket_server Attribute Type Required Description bitbucket_server_project string Yes Bitbucket project key. Must contain only letters, numbers, hyphens, underscores, periods, or whitespace characters. Personal project keys start with ~ . bitbucket_server_repo string Yes Bitbucket repository name. Must contain only letters, numbers, hyphens, underscores, periods, or whitespace characters. bitbucket_server_url string Yes Bitbucket Server URL. bitbucket_server_username string Yes Bitbucket Server username. personal_access_token string Yes Bitbucket Server personal access token or password. new_name string No Name of the new project. Also used as the new path so must not start or end with a special character and must not contain consecutive special characters. target_namespace string No Namespace to import repository into. Supports subgroups like /namespace/subgroup . timeout_strategy string No Strategy for handling import timeouts. Valid values are optimistic (continue to next stage of import) or pessimistic (fail immediately). Defaults to pessimistic . curl --request POST \ --url "https://gitlab.example.com/api/v4/import/bitbucket_server" \ --header "content-type: application/json" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data '{ "bitbucket_server_url": "http://bitbucket.example.com", "bitbucket_server_username": "root", "personal_access_token": "Nzk4MDcxODY4MDAyOiP8y410zF3tGAyLnHRv/E0+3xYs", "bitbucket_server_project": "NEW", "bitbucket_server_repo": "my-repo", "new_name": "NEW-NAME" }' Import repository from Bitbucket Cloud History * Introduced in GitLab 17.0. * Support for Bitbucket Cloud API tokens added in GitLab 18.9. * Support for Bitbucket Cloud app passwords removed in GitLab 19.0. Imports a repository from Bitbucket Cloud to GitLab. Prerequisites: * The prerequisites for Bitbucket Cloud importer . * A Bitbucket Cloud API token with the required scopes. POST /import/bitbucket Attribute Type Required Description bitbucket_api_token string Yes Bitbucket Cloud API token. bitbucket_email string Yes Bitbucket Cloud email. repo_path string Yes Path to repository. target_namespace string Yes Namespace to import repository into. Supports subgroups like /namespace/subgroup . new_name string No Name of the new project. Also used as the new path so must not start or end with a special character and must not contain consecutive special characters. curl --request POST \ --url "https://gitlab.example.com/api/v4/import/bitbucket" \ --header "content-type: application/json" \ --header "PRIVATE-TOKEN: <your_access_token>" \ --data '{ "bitbucket_email": "[email protected]", "bitbucket_api_token": "your_bitbucket_api_token", "repo_path": "username/my_project", "target_namespace": "my_group/my_subgroup", "new_name": "new_project_name" }' Bitbucket Cloud API token scopes If you re using a Bitbucket Cloud API token for authentication, the token must have the following scopes: * read:repository:bitbucket * read:pullrequest:bitbucket * read:issue:bitbucket * read:wiki:bitbucket Related topics * Group migration by direct transfer API . * Group import and export API . * Project import and export API . * Import repository from GitHub * Import a public project through the API using a group access token * Cancel GitHub project import * Import GitHub gists into GitLab snippets * Import repository from Bitbucket Server * Import repository from Bitbucket Cloud * Bitbucket Cloud API token scopes * Related topics * Facebook * LinkedIn * Twitter * YouTube Company * About GitLab * View pricing * Try GitLab for free Feedback * View page source * Edit in Web IDE * Contribute to GitLab * Suggest updates Help & Community * Get certified * Get support * Post on the GitLab forum Resources * Terms * Privacy statement * Use of generative AI * Acceptable use of user licenses *