Project import

Use this API to import repositories from external sources and to migrate a project between GitLab instances.

If you first migrate the parent group structure with the group import and export API, you can preserve relationships that span the group, such as connections between project issues and group epics. After an import, use the project-level CI/CD variables API to restore CI/CD variables. You must still migrate your container registry over a series of Docker pulls and pushes, and re-run any CI/CD pipelines to retrieve build artifacts.

The project relations export endpoints are used by the destination instance during group migration by direct transfer to migrate a project structure, and you don’t usually need to call them yourself. In this context, a relation is an exportable item such as a merge request, including any related items such as a label.

User contribution mapping is not supported when you import projects to a personal namespace. All contributions are assigned to the personal namespace owner and cannot be reassigned.

Import repository from Bitbucket Cloud

POST /api/v4/import/bitbucket

Imports a repository from Bitbucket Cloud to GitLab. Prerequisites: - The prerequisites for Bitbucket Cloud importer. This feature was introduced in GitLab 17.0.

Request body (application/json)

Property	Type	Description
`bitbucket_api_token` Required	String	Bitbucket Cloud API token
`bitbucket_email` Required	String	Bitbucket Cloud email
`new_name`	String	Name of the new project. Also used as the new path, so it must not start or end with a special character and must not contain consecutive special characters
`repo_path` Required	String	Path to the repository
`target_namespace` Required	String	Namespace to import the repository into. Supports subgroups, for example `/namespace/subgroup`

Responses

Code	Description	Schema
`201`	Created	ProjectImportEntity
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`422`	Unprocessable entity	—
`503`	Service unavailable	—

Import repository from Bitbucket Server

POST /api/v4/import/bitbucket_server

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.

Request body (application/json)

Property	Type	Description
`bitbucket_server_project` Required	String	Key of the Bitbucket Server project. Must contain only letters, numbers, hyphens, underscores, periods, or whitespace characters. Personal project keys start with `~`
`bitbucket_server_repo` Required	String	Name of the Bitbucket Server repository. Must contain only letters, numbers, hyphens, underscores, periods, or whitespace characters
`bitbucket_server_url` Required	String	URL of the Bitbucket Server instance
`bitbucket_server_username` Required	String	Bitbucket Server username
`new_name`	String	Name of the new project. Also used as the new path, so it must not start or end with a special character and must not contain consecutive special characters
`new_namespace`	String	Namespace to import the repository into
`personal_access_token` Required	String	Bitbucket Server personal access token or password
`timeout_strategy`	String	Strategy for handling import timeouts. `optimistic` continues to the next stage of the import. `pessimistic` fails the import immediately. Defaults to `pessimistic` Allowed values: `optimistic`, `pessimistic`

Responses

Code	Description	Schema
`201`	Created	ProjectEntity
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`422`	Unprocessable entity	—
`503`	Service unavailable	—

Import a repository from GitHub

POST /api/v4/import/github

Imports a repository from GitHub to GitLab.

Request body (application/json)

Property	Type	Description
`github_hostname`	String	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	Name of the new project. Also used as the new path, so it must not start or end with a special character and must not contain consecutive special characters
`optional_stages`	Object	Additional items to import. For a list of items, see select additional items to import
`pagination_limit`	Integer	Number of items retrieved per API request to GitHub. If omitted, defaults to `100`. Use a lower number for large repositories to reduce the risk of GitHub API errors, though this increases migration time Maximum: `100` Minimum: `1`
`personal_access_token` Required	String	GitHub personal access token
`repo_id` Required	Integer	GitHub repository ID
`target_namespace` Required	String	Namespace to import the repository into. Supports subgroups, for example `/namespace/subgroup`. Must not be blank
`timeout_strategy`	String	Strategy for handling import timeouts. `optimistic` continues to the next stage of the import. `pessimistic` fails the import immediately. Defaults to `pessimistic` Allowed values: `optimistic`, `pessimistic`

Responses

Code	Description	Schema
`201`	Created	ProjectEntity
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`422`	Unprocessable entity	—
`503`	Service unavailable	—

Cancel a GitHub project import

POST /api/v4/import/github/cancel

Cancels an in-progress import of a GitHub project to GitLab.

Request body (application/json)

Property	Type	Description
`project_id` Required	Integer	ID of the project whose import to cancel

Responses

Code	Description	Schema
`200`	OK	ProjectImportEntity
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Import a project from a local archive

POST /api/v4/projects/import

Imports a project from a local archive.

Request body (multipart/form-data)

Property	Type	Description
`file` Required	String (binary)	The project export file to be imported
`file.etag`	String	Etag of the file (generated by Workhorse)
`file.md5`	String	MD5 checksum of the file (generated by Workhorse)
`file.name`	String	Real filename as send in Content-Disposition (generated by Workhorse)
`file.path`	String	Path to locally stored body (generated by Workhorse)
`file.remote_id`	String	Remote_id of the file (generated by Workhorse)
`file.remote_url`	String	Remote_url of the file (generated by Workhorse)
`file.sha1`	String	SHA1 checksum of the file (generated by Workhorse)
`file.sha256`	String	SHA256 checksum of the file (generated by Workhorse)
`file.size`	Integer	Real size of file (generated by Workhorse)
`file.type`	String	Real content type as send in Content-Type (generated by Workhorse)
`name`	String	The name of the project to be imported. Defaults to the path of the project if not provided
`namespace`	String	(deprecated) The ID or path of the namespace to import the project to. Defaults to the current user’s namespace. Mutually exclusive with `namespace_id`, `namespace_path`
`namespace_id`	Integer	The ID of the namespace that the project will be imported into. Defaults to the current user’s namespace. Mutually exclusive with `namespace`, `namespace_path` Example: `1`
`namespace_path`	String	The path of the namespace that the project will be imported into. Defaults to the current user’s namespace. Mutually exclusive with `namespace`, `namespace_id` Example: `new_path/gitlab`
`override_params`	Object	New project params to override values in the export
`override_params.allow_merge_on_skipped_pipeline`	Boolean	Allow to merge if pipeline is skipped
`override_params.analytics_access_level`	String	Analytics access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.auto_cancel_pending_pipelines`	String	Auto-cancel pending pipelines Allowed values: `disabled`, `enabled`
`override_params.auto_devops_deploy_strategy`	String	Auto Deploy strategy Allowed values: `continuous`, `manual`, `timed_incremental`
`override_params.auto_devops_enabled`	Boolean	Flag indication if Auto DevOps is enabled
`override_params.autoclose_referenced_issues`	Boolean	Flag indication if referenced issues auto-closing is enabled
`override_params.avatar`	String (binary)	Avatar image for project
`override_params.build_git_strategy`	String	The Git strategy. Defaults to `fetch` Allowed values: `fetch`, `clone`
`override_params.build_timeout`	Integer	Build timeout
`override_params.builds_access_level`	String	Builds access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.ci_config_path`	String	The path to CI config file. Defaults to `.gitlab-ci.yml`
`override_params.cicd_catalog_enabled`	Boolean	Set whether the project is a CI/CD catalog project
`override_params.container_expiration_policy_attributes`	Object	Object that contains information on the container expiration policy
`override_params.container_expiration_policy_attributes.cadence`	String	Container expiration policy cadence for recurring job
`override_params.container_expiration_policy_attributes.enabled`	Boolean	Flag indication if container expiration policy is enabled
`override_params.container_expiration_policy_attributes.keep_n`	Integer	Container expiration policy number of images to keep
`override_params.container_expiration_policy_attributes.name_regex`	String	Container expiration policy regex for image removal
`override_params.container_expiration_policy_attributes.name_regex_keep`	String	Container expiration policy regex for image retention
`override_params.container_expiration_policy_attributes.older_than`	String	Container expiration policy remove images older than value
`override_params.container_registry_access_level`	String	Controls visibility of the container registry. One of `disabled`, `private` or `enabled`. `private` will make the container registry accessible only to project members (reporter role and above). `enabled` will make the container registry accessible to everyone who has access to the project. `disabled` will disable the container registry Allowed values: `disabled`, `private`, `enabled`
`override_params.container_registry_enabled`	Boolean	Deprecated: Use :container_registry_access_level instead. Flag indication if the container registry is enabled for that project
`override_params.description`	String	The description of the project
`override_params.emails_disabled`	Boolean	Deprecated: Use emails_enabled instead
`override_params.emails_enabled`	Boolean	Enable email notifications
`override_params.enforce_auth_checks_on_uploads`	Boolean	Enforce auth check on uploads
`override_params.environments_access_level`	String	Environments access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.feature_flags_access_level`	String	Feature flags access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.forking_access_level`	String	Forks access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.group_runners_enabled`	Boolean	Flag indication if group runners are enabled for that project
`override_params.infrastructure_access_level`	String	Infrastructure access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.issue_branch_template`	String	Template used to create a branch from an issue
`override_params.issues_access_level`	String	Issues access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.issues_enabled`	Boolean	Flag indication if the issue tracker is enabled
`override_params.jobs_enabled`	Boolean	Flag indication if jobs are enabled
`override_params.lfs_enabled`	Boolean	Flag indication if Git LFS is enabled for that project
`override_params.merge_commit_template`	String	Template used to create merge commit message
`override_params.merge_method`	String	The merge method used when merging merge requests Allowed values: `ff`, `rebase_merge`, `merge`
`override_params.merge_requests_access_level`	String	Merge requests access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.merge_requests_enabled`	Boolean	Flag indication if merge requests are enabled
`override_params.model_experiments_access_level`	String	Model experiments access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.model_registry_access_level`	String	Model registry access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.monitor_access_level`	String	Monitor access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.mr_default_target_self`	Boolean	Merge requests of this forked project targets itself by default
`override_params.mr_default_title_template`	String	Template used to generate the default merge request title. Maximum 100 characters Maximum length: `100`
`override_params.only_allow_merge_if_all_discussions_are_resolved`	Boolean	Only allow to merge if all threads are resolved
`override_params.only_allow_merge_if_pipeline_succeeds`	Boolean	Only allow to merge if builds succeed
`override_params.package_registry_access_level`	String	Controls visibility of the package registry. One of `disabled`, `private`, `enabled` or `public`. `private` will make the package registry accessible only to project members (reporter role and above). `enabled` will make the package registry accessible to everyone who has access to the project. `public` will make the package registry accessible to everyone. `disabled` will disable the package registry Allowed values: `disabled`, `private`, `enabled`, `public`
`override_params.packages_enabled`	Boolean	Deprecated: Use :package_registry_access_level instead. Enable project packages feature
`override_params.pages_access_level`	String	Pages access level. One of `disabled`, `private`, `enabled` or `public` Allowed values: `disabled`, `private`, `enabled`, `public`
`override_params.printing_merge_request_link_enabled`	Boolean	Show link to create/view merge request when pushing from the command line
`override_params.public_builds`	Boolean	Deprecated: Use public_jobs instead
`override_params.public_jobs`	Boolean	Perform public builds
`override_params.releases_access_level`	String	Releases access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.remove_source_branch_after_merge`	Boolean	Remove the source branch by default after merge
`override_params.repository_access_level`	String	Repository access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.repository_storage`	String	Which storage shard the repository is on. Available only to admins
`override_params.request_access_enabled`	Boolean	Allow users to request member access
`override_params.resolve_outdated_diff_discussions`	Boolean	Automatically resolve merge request diff threads on lines changed with a push
`override_params.resource_group_default_process_mode`	String	The process mode of the resource group Allowed values: `unordered`, `oldest_first`, `newest_first`, `newest_ready_first`
`override_params.security_and_compliance_access_level`	String	Security and compliance access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.service_desk_enabled`	Boolean	Disable or enable the service desk
`override_params.shared_runners_enabled`	Boolean	Flag indication if shared runners are enabled for that project
`override_params.show_default_award_emojis`	Boolean	Show default award emojis
`override_params.show_diff_preview_in_email`	Boolean	Include the code diff preview in merge request notification emails
`override_params.snippets_access_level`	String	Snippets access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.snippets_enabled`	Boolean	Flag indication if snippets are enabled
`override_params.squash_commit_template`	String	Template used to create squash commit message
`override_params.squash_option`	String	Squash default for project. One of `never`, `always`, `default_on`, or `default_off` Allowed values: `never`, `always`, `default_on`, `default_off`
`override_params.suggestion_commit_message`	String	The commit message used to apply merge request suggestions
`override_params.tag_list`	Array of strings	Deprecated: Use :topics instead
`override_params.topics`	Array of strings	The list of topics for a project
`override_params.visibility`	String	The visibility of the project Allowed values: `private`, `internal`, `public`
`override_params.warn_about_potentially_unwanted_characters`	Boolean	Warn about potentially unwanted characters
`override_params.wiki_access_level`	String	Wiki access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.wiki_enabled`	Boolean	Flag indication if the wiki is enabled
`overwrite`	Boolean	If there is a project in the same namespace and with the same name overwrite it Default: `false`
`path` Required	String	The new project path and name

Responses

Code	Description	Schema
`201`	Created	APIEntitiesProjectImportStatus
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Import project resources

POST /api/v4/projects/import-relation

Imports project resources included with a project archive. The type of item to import is controlled by the relation attribute. Skips items that were previously imported. This feature was introduced in GitLab 16.11.

Request body (multipart/form-data)

Property	Type	Description
`file` Required	String (binary)	The project export file from which to extract the relation
`file.etag`	String	Etag of the file (generated by Workhorse)
`file.md5`	String	MD5 checksum of the file (generated by Workhorse)
`file.name`	String	Real filename as sent in Content-Disposition (generated by Workhorse)
`file.path`	String	Path to locally stored body (generated by Workhorse)
`file.remote_id`	String	Remote_id of the file (generated by Workhorse)
`file.remote_url`	String	Remote_url of the file (generated by Workhorse)
`file.sha1`	String	SHA1 checksum of the file (generated by Workhorse)
`file.sha256`	String	SHA256 checksum of the file (generated by Workhorse)
`file.size`	Integer	Real size of file (generated by Workhorse)
`file.type`	String	Real content type as send in Content-Type (generated by Workhorse)
`path` Required	String	The project path and name
`relation` Required	String	The relation to import Allowed values: `issues`, `merge_requests`, `milestones`, `ci_pipelines` Minimum length: `1`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesRelationImportTracker
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Authorize project relation import

POST /api/v4/projects/import-relation/authorize

Authorizes uploading a project relation import file. This feature was introduced in GitLab 16.11.

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad Request	—

Workhorse authorize the project import upload

POST /api/v4/projects/import/authorize

This feature was introduced in GitLab 12.9

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad Request	—

Import a project from a remote archive

POST /api/v4/projects/remote-import

Imports a project from a remote archive.

Request body (multipart/form-data)

Property	Type	Description
`name`	String	The name of the project to be imported. Defaults to the path of the project if not provided
`namespace`	String	(deprecated) The ID or path of the namespace to import the project to. Defaults to the current user’s namespace. Mutually exclusive with `namespace_id`, `namespace_path`
`namespace_id`	Integer	The ID of the namespace that the project will be imported into. Defaults to the current user’s namespace. Mutually exclusive with `namespace`, `namespace_path` Example: `1`
`namespace_path`	String	The path of the namespace that the project will be imported into. Defaults to the current user’s namespace. Mutually exclusive with `namespace`, `namespace_id` Example: `new_path/gitlab`
`override_params`	Object	New project params to override values in the export
`override_params.allow_merge_on_skipped_pipeline`	Boolean	Allow to merge if pipeline is skipped
`override_params.analytics_access_level`	String	Analytics access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.auto_cancel_pending_pipelines`	String	Auto-cancel pending pipelines Allowed values: `disabled`, `enabled`
`override_params.auto_devops_deploy_strategy`	String	Auto Deploy strategy Allowed values: `continuous`, `manual`, `timed_incremental`
`override_params.auto_devops_enabled`	Boolean	Flag indication if Auto DevOps is enabled
`override_params.autoclose_referenced_issues`	Boolean	Flag indication if referenced issues auto-closing is enabled
`override_params.avatar`	String (binary)	Avatar image for project
`override_params.build_git_strategy`	String	The Git strategy. Defaults to `fetch` Allowed values: `fetch`, `clone`
`override_params.build_timeout`	Integer	Build timeout
`override_params.builds_access_level`	String	Builds access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.ci_config_path`	String	The path to CI config file. Defaults to `.gitlab-ci.yml`
`override_params.cicd_catalog_enabled`	Boolean	Set whether the project is a CI/CD catalog project
`override_params.container_expiration_policy_attributes`	Object	Object that contains information on the container expiration policy
`override_params.container_expiration_policy_attributes.cadence`	String	Container expiration policy cadence for recurring job
`override_params.container_expiration_policy_attributes.enabled`	Boolean	Flag indication if container expiration policy is enabled
`override_params.container_expiration_policy_attributes.keep_n`	Integer	Container expiration policy number of images to keep
`override_params.container_expiration_policy_attributes.name_regex`	String	Container expiration policy regex for image removal
`override_params.container_expiration_policy_attributes.name_regex_keep`	String	Container expiration policy regex for image retention
`override_params.container_expiration_policy_attributes.older_than`	String	Container expiration policy remove images older than value
`override_params.container_registry_access_level`	String	Controls visibility of the container registry. One of `disabled`, `private` or `enabled`. `private` will make the container registry accessible only to project members (reporter role and above). `enabled` will make the container registry accessible to everyone who has access to the project. `disabled` will disable the container registry Allowed values: `disabled`, `private`, `enabled`
`override_params.container_registry_enabled`	Boolean	Deprecated: Use :container_registry_access_level instead. Flag indication if the container registry is enabled for that project
`override_params.description`	String	The description of the project
`override_params.emails_disabled`	Boolean	Deprecated: Use emails_enabled instead
`override_params.emails_enabled`	Boolean	Enable email notifications
`override_params.enforce_auth_checks_on_uploads`	Boolean	Enforce auth check on uploads
`override_params.environments_access_level`	String	Environments access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.feature_flags_access_level`	String	Feature flags access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.forking_access_level`	String	Forks access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.group_runners_enabled`	Boolean	Flag indication if group runners are enabled for that project
`override_params.infrastructure_access_level`	String	Infrastructure access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.issue_branch_template`	String	Template used to create a branch from an issue
`override_params.issues_access_level`	String	Issues access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.issues_enabled`	Boolean	Flag indication if the issue tracker is enabled
`override_params.jobs_enabled`	Boolean	Flag indication if jobs are enabled
`override_params.lfs_enabled`	Boolean	Flag indication if Git LFS is enabled for that project
`override_params.merge_commit_template`	String	Template used to create merge commit message
`override_params.merge_method`	String	The merge method used when merging merge requests Allowed values: `ff`, `rebase_merge`, `merge`
`override_params.merge_requests_access_level`	String	Merge requests access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.merge_requests_enabled`	Boolean	Flag indication if merge requests are enabled
`override_params.model_experiments_access_level`	String	Model experiments access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.model_registry_access_level`	String	Model registry access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.monitor_access_level`	String	Monitor access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.mr_default_target_self`	Boolean	Merge requests of this forked project targets itself by default
`override_params.mr_default_title_template`	String	Template used to generate the default merge request title. Maximum 100 characters Maximum length: `100`
`override_params.only_allow_merge_if_all_discussions_are_resolved`	Boolean	Only allow to merge if all threads are resolved
`override_params.only_allow_merge_if_pipeline_succeeds`	Boolean	Only allow to merge if builds succeed
`override_params.package_registry_access_level`	String	Controls visibility of the package registry. One of `disabled`, `private`, `enabled` or `public`. `private` will make the package registry accessible only to project members (reporter role and above). `enabled` will make the package registry accessible to everyone who has access to the project. `public` will make the package registry accessible to everyone. `disabled` will disable the package registry Allowed values: `disabled`, `private`, `enabled`, `public`
`override_params.packages_enabled`	Boolean	Deprecated: Use :package_registry_access_level instead. Enable project packages feature
`override_params.pages_access_level`	String	Pages access level. One of `disabled`, `private`, `enabled` or `public` Allowed values: `disabled`, `private`, `enabled`, `public`
`override_params.printing_merge_request_link_enabled`	Boolean	Show link to create/view merge request when pushing from the command line
`override_params.public_builds`	Boolean	Deprecated: Use public_jobs instead
`override_params.public_jobs`	Boolean	Perform public builds
`override_params.releases_access_level`	String	Releases access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.remove_source_branch_after_merge`	Boolean	Remove the source branch by default after merge
`override_params.repository_access_level`	String	Repository access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.repository_storage`	String	Which storage shard the repository is on. Available only to admins
`override_params.request_access_enabled`	Boolean	Allow users to request member access
`override_params.resolve_outdated_diff_discussions`	Boolean	Automatically resolve merge request diff threads on lines changed with a push
`override_params.resource_group_default_process_mode`	String	The process mode of the resource group Allowed values: `unordered`, `oldest_first`, `newest_first`, `newest_ready_first`
`override_params.security_and_compliance_access_level`	String	Security and compliance access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.service_desk_enabled`	Boolean	Disable or enable the service desk
`override_params.shared_runners_enabled`	Boolean	Flag indication if shared runners are enabled for that project
`override_params.show_default_award_emojis`	Boolean	Show default award emojis
`override_params.show_diff_preview_in_email`	Boolean	Include the code diff preview in merge request notification emails
`override_params.snippets_access_level`	String	Snippets access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.snippets_enabled`	Boolean	Flag indication if snippets are enabled
`override_params.squash_commit_template`	String	Template used to create squash commit message
`override_params.squash_option`	String	Squash default for project. One of `never`, `always`, `default_on`, or `default_off` Allowed values: `never`, `always`, `default_on`, `default_off`
`override_params.suggestion_commit_message`	String	The commit message used to apply merge request suggestions
`override_params.tag_list`	Array of strings	Deprecated: Use :topics instead
`override_params.topics`	Array of strings	The list of topics for a project
`override_params.visibility`	String	The visibility of the project Allowed values: `private`, `internal`, `public`
`override_params.warn_about_potentially_unwanted_characters`	Boolean	Warn about potentially unwanted characters
`override_params.wiki_access_level`	String	Wiki access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.wiki_enabled`	Boolean	Flag indication if the wiki is enabled
`overwrite`	Boolean	If there is a project in the same namespace and with the same name overwrite it Default: `false`
`path` Required	String	The new project path and name
`url` Required	String	The URL for the file

Responses

Code	Description	Schema
`201`	Created	APIEntitiesProjectImportStatus
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`429`	Too many requests	—
`503`	Service unavailable	—

Import a project from an AWS S3 bucket

POST /api/v4/projects/remote-import-s3

Imports a project from an archive stored in a specified AWS S3 bucket.

Request body (multipart/form-data)

Property	Type	Description
`access_key_id` Required	String	Access key id
`bucket_name` Required	String	Bucket name
`file_key` Required	String	File key
`name`	String	The name of the project to be imported. Defaults to the path of the project if not provided
`namespace`	String	(deprecated) The ID or path of the namespace to import the project to. Defaults to the current user’s namespace. Mutually exclusive with `namespace_id`, `namespace_path`
`namespace_id`	Integer	The ID of the namespace that the project will be imported into. Defaults to the current user’s namespace. Mutually exclusive with `namespace`, `namespace_path` Example: `1`
`namespace_path`	String	The path of the namespace that the project will be imported into. Defaults to the current user’s namespace. Mutually exclusive with `namespace`, `namespace_id` Example: `new_path/gitlab`
`override_params`	Object	New project params to override values in the export
`override_params.allow_merge_on_skipped_pipeline`	Boolean	Allow to merge if pipeline is skipped
`override_params.analytics_access_level`	String	Analytics access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.auto_cancel_pending_pipelines`	String	Auto-cancel pending pipelines Allowed values: `disabled`, `enabled`
`override_params.auto_devops_deploy_strategy`	String	Auto Deploy strategy Allowed values: `continuous`, `manual`, `timed_incremental`
`override_params.auto_devops_enabled`	Boolean	Flag indication if Auto DevOps is enabled
`override_params.autoclose_referenced_issues`	Boolean	Flag indication if referenced issues auto-closing is enabled
`override_params.avatar`	String (binary)	Avatar image for project
`override_params.build_git_strategy`	String	The Git strategy. Defaults to `fetch` Allowed values: `fetch`, `clone`
`override_params.build_timeout`	Integer	Build timeout
`override_params.builds_access_level`	String	Builds access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.ci_config_path`	String	The path to CI config file. Defaults to `.gitlab-ci.yml`
`override_params.cicd_catalog_enabled`	Boolean	Set whether the project is a CI/CD catalog project
`override_params.container_expiration_policy_attributes`	Object	Object that contains information on the container expiration policy
`override_params.container_expiration_policy_attributes.cadence`	String	Container expiration policy cadence for recurring job
`override_params.container_expiration_policy_attributes.enabled`	Boolean	Flag indication if container expiration policy is enabled
`override_params.container_expiration_policy_attributes.keep_n`	Integer	Container expiration policy number of images to keep
`override_params.container_expiration_policy_attributes.name_regex`	String	Container expiration policy regex for image removal
`override_params.container_expiration_policy_attributes.name_regex_keep`	String	Container expiration policy regex for image retention
`override_params.container_expiration_policy_attributes.older_than`	String	Container expiration policy remove images older than value
`override_params.container_registry_access_level`	String	Controls visibility of the container registry. One of `disabled`, `private` or `enabled`. `private` will make the container registry accessible only to project members (reporter role and above). `enabled` will make the container registry accessible to everyone who has access to the project. `disabled` will disable the container registry Allowed values: `disabled`, `private`, `enabled`
`override_params.container_registry_enabled`	Boolean	Deprecated: Use :container_registry_access_level instead. Flag indication if the container registry is enabled for that project
`override_params.description`	String	The description of the project
`override_params.emails_disabled`	Boolean	Deprecated: Use emails_enabled instead
`override_params.emails_enabled`	Boolean	Enable email notifications
`override_params.enforce_auth_checks_on_uploads`	Boolean	Enforce auth check on uploads
`override_params.environments_access_level`	String	Environments access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.feature_flags_access_level`	String	Feature flags access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.forking_access_level`	String	Forks access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.group_runners_enabled`	Boolean	Flag indication if group runners are enabled for that project
`override_params.infrastructure_access_level`	String	Infrastructure access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.issue_branch_template`	String	Template used to create a branch from an issue
`override_params.issues_access_level`	String	Issues access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.issues_enabled`	Boolean	Flag indication if the issue tracker is enabled
`override_params.jobs_enabled`	Boolean	Flag indication if jobs are enabled
`override_params.lfs_enabled`	Boolean	Flag indication if Git LFS is enabled for that project
`override_params.merge_commit_template`	String	Template used to create merge commit message
`override_params.merge_method`	String	The merge method used when merging merge requests Allowed values: `ff`, `rebase_merge`, `merge`
`override_params.merge_requests_access_level`	String	Merge requests access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.merge_requests_enabled`	Boolean	Flag indication if merge requests are enabled
`override_params.model_experiments_access_level`	String	Model experiments access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.model_registry_access_level`	String	Model registry access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.monitor_access_level`	String	Monitor access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.mr_default_target_self`	Boolean	Merge requests of this forked project targets itself by default
`override_params.mr_default_title_template`	String	Template used to generate the default merge request title. Maximum 100 characters Maximum length: `100`
`override_params.only_allow_merge_if_all_discussions_are_resolved`	Boolean	Only allow to merge if all threads are resolved
`override_params.only_allow_merge_if_pipeline_succeeds`	Boolean	Only allow to merge if builds succeed
`override_params.package_registry_access_level`	String	Controls visibility of the package registry. One of `disabled`, `private`, `enabled` or `public`. `private` will make the package registry accessible only to project members (reporter role and above). `enabled` will make the package registry accessible to everyone who has access to the project. `public` will make the package registry accessible to everyone. `disabled` will disable the package registry Allowed values: `disabled`, `private`, `enabled`, `public`
`override_params.packages_enabled`	Boolean	Deprecated: Use :package_registry_access_level instead. Enable project packages feature
`override_params.pages_access_level`	String	Pages access level. One of `disabled`, `private`, `enabled` or `public` Allowed values: `disabled`, `private`, `enabled`, `public`
`override_params.printing_merge_request_link_enabled`	Boolean	Show link to create/view merge request when pushing from the command line
`override_params.public_builds`	Boolean	Deprecated: Use public_jobs instead
`override_params.public_jobs`	Boolean	Perform public builds
`override_params.releases_access_level`	String	Releases access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.remove_source_branch_after_merge`	Boolean	Remove the source branch by default after merge
`override_params.repository_access_level`	String	Repository access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.repository_storage`	String	Which storage shard the repository is on. Available only to admins
`override_params.request_access_enabled`	Boolean	Allow users to request member access
`override_params.resolve_outdated_diff_discussions`	Boolean	Automatically resolve merge request diff threads on lines changed with a push
`override_params.resource_group_default_process_mode`	String	The process mode of the resource group Allowed values: `unordered`, `oldest_first`, `newest_first`, `newest_ready_first`
`override_params.security_and_compliance_access_level`	String	Security and compliance access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.service_desk_enabled`	Boolean	Disable or enable the service desk
`override_params.shared_runners_enabled`	Boolean	Flag indication if shared runners are enabled for that project
`override_params.show_default_award_emojis`	Boolean	Show default award emojis
`override_params.show_diff_preview_in_email`	Boolean	Include the code diff preview in merge request notification emails
`override_params.snippets_access_level`	String	Snippets access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.snippets_enabled`	Boolean	Flag indication if snippets are enabled
`override_params.squash_commit_template`	String	Template used to create squash commit message
`override_params.squash_option`	String	Squash default for project. One of `never`, `always`, `default_on`, or `default_off` Allowed values: `never`, `always`, `default_on`, `default_off`
`override_params.suggestion_commit_message`	String	The commit message used to apply merge request suggestions
`override_params.tag_list`	Array of strings	Deprecated: Use :topics instead
`override_params.topics`	Array of strings	The list of topics for a project
`override_params.visibility`	String	The visibility of the project Allowed values: `private`, `internal`, `public`
`override_params.warn_about_potentially_unwanted_characters`	Boolean	Warn about potentially unwanted characters
`override_params.wiki_access_level`	String	Wiki access level. One of `disabled`, `private` or `enabled` Allowed values: `disabled`, `private`, `enabled`
`override_params.wiki_enabled`	Boolean	Flag indication if the wiki is enabled
`overwrite`	Boolean	If there is a project in the same namespace and with the same name overwrite it Default: `false`
`path` Required	String	The new project path and name
`region` Required	String	AWS region
`secret_access_key` Required	String	Secret access key

Responses

Code	Description	Schema
`201`	Created	APIEntitiesProjectImportStatus
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`429`	Too many requests	—
`503`	Service unavailable	—

Retrieve the status of a project export

GET /api/v4/projects/{id}/export

Retrieves the status of the most recent export for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectExportStatus
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Export a project

POST /api/v4/projects/{id}/export

Exports a project. Use the upload hash parameter to upload the exported project to a web server or any S3-compatible platform.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`description`	String	Overrides the project description
`excluded_relations`	Array of strings	Project relation names to exclude from the export, for example `merge_requests` and `issues`
`upload`	Object	Details for uploading the exported project to a web server
`upload.http_method`	String	HTTP method to upload the exported project Allowed values: `PUT`, `POST` Default: `PUT`
`upload.url`	String	URL to upload the exported project to

Responses

Code	Description	Schema
`202`	Accepted	—
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`429`	Too many requests	—
`503`	Service unavailable	—

Download a project export

GET /api/v4/projects/{id}/export/download

Downloads the most recent export of a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Responses

Code	Description	Schema
`200`	OK	String (binary) (`application/octet-stream`)
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Schedule a relations export for a project

POST /api/v4/projects/{id}/export_relations

Schedules a relations export for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`batched`	Boolean	If `true`, exports in batches

Responses

Code	Description	Schema
`202`	Accepted	—
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Download a relations export for a project

GET /api/v4/projects/{id}/export_relations/download

Downloads a project relations export file.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`relation` Query, required	String	Name of the project top-level relation to download or view
`batched` Query	Boolean	If `true`, downloads the batch specified by `batch_number`. Set to `true` only for batched exports. All or none of `batched`, `batch_number` must be provided
`batch_number` Query	Integer	Number of the export batch to download. All or none of `batched`, `batch_number` must be provided

Responses

Code	Description	Schema
`200`	OK	String (binary) (`application/gzip`) String (binary) (`application/octet-stream`)
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`500`	Internal Server Error	—
`503`	Service unavailable	—

Retrieve the status of an relations export for a project

GET /api/v4/projects/{id}/export_relations/status

Retrieves the status of a relations export for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`relation` Query	String	Name of the project top-level relation to download or view

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesBulkImportsExportStatus
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Receive a GitHub webhook delivery for an OAuth-connected repository

POST /api/v4/projects/{id}/github/webhooks

Verifies the webhook signature and, once available, triggers repository reconciliation.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of the project

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad request	—
`404`	Not found	—
`429`	Too many requests	—

Retrieve the status of a project import

GET /api/v4/projects/{id}/import

Retrieves the status of the most recent import for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectImportStatus
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Import a project from a Git URL

POST /api/v4/projects/{id}/import/git

Imports a project from a specified Git URL. This feature was introduced in GitLab 18.10.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`import_url` Required	String	URL from which the project is imported
`import_url_password`	String	Password for the import URL
`import_url_user`	String	Username for the import URL

Responses

Code	Description	Schema
`201`	Created	APIEntitiesProjectImportStatus
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`409`	Conflict	—
`422`	Unprocessable Entity	—

Retrieve the status of a project resource import

GET /api/v4/projects/{id}/relation-imports

Retrieves the status of the most recent relation import for a specified project. Because only one relation import can be scheduled at a time, you can use this endpoint to check whether the previous import completed successfully. This feature was introduced in GitLab 16.11.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectImportStatus
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`503`	Service unavailable	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesBulkImportsExportBatchStatus

Property	Type	Description
`batch_number`	Integer	Example: `1`
`error`	String	Example: `Error message`
`objects_count`	Integer	Example: `100`
`status`	String	Allowed values: `started`, `finished`, `failed` Example: `started`
`updated_at`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`

APIEntitiesBulkImportsExportStatus

Property	Type	Description
`batched`	Boolean	Example: `true`
`batches`	APIEntitiesBulkImportsExportBatchStatus	—
`batches_count`	Integer	Example: `2`
`error`	String	Example: `Error message`
`relation`	String	Example: `issues`
`status`	String	Allowed values: `pending`, `started`, `finished`, `failed` Example: `started`
`total_objects_count`	Integer	Example: `100`
`updated_at`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`

APIEntitiesProjectExportStatus

Property	Type	Description
`_links`	Object	—
`_links.api_url`	String	Example: `https://gitlab.example.com/api/v4/projects/1/export/download`
`_links.web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-test/download_export`
`created_at`	String (date-time)	Example: `2020-05-07T04:27:17.016Z`
`description`	String	Example: `desc`
`export_status`	String	Allowed values: `queued`, `started`, `finished`, `failed` Example: `finished`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `project1`
`name_with_namespace`	String	Example: `John Doe / project1`
`path`	String	Example: `project1`
`path_with_namespace`	String	Example: `namespace1/project1`

APIEntitiesProjectImportFailedRelation

Property	Type	Description
`created_at`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`exception_class`	String	Example: `StandardError`
`exception_message`	String	—
`id`	Integer (int64)	Example: `1`
`line_number`	Integer	Example: `1`
`relation_name`	String	Example: `issues`
`source`	String	Example: `ImportRepositoryWorker`

APIEntitiesProjectImportStatus

Property	Type	Description
`correlation_id`	String	Example: `dfcf583058ed4508e4c7c617bd7f0edd`
`created_at`	String (date-time)	Example: `2020-05-07T04:27:17.016Z`
`description`	String	Example: `desc`
`failed_relations`	Array of APIEntitiesProjectImportFailedRelation	—
`id`	Integer (int64)	Example: `1`
`import_error`	String	Example: `Error message`
`import_status`	String	Example: `scheduled`
`import_type`	String	Example: `gitlab_project`
`name`	String	Example: `project1`
`name_with_namespace`	String	Example: `John Doe / project1`
`path`	String	Example: `project1`
`path_with_namespace`	String	Example: `namespace1/project1`
`stats`	Object	—

APIEntitiesRelationImportTracker

Property	Type	Description
`created_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`id`	Integer (int64)	Example: `1`
`project_path`	String	Example: `namespace1/project1`
`relation`	String	Example: `issues`
`status`	String	Example: `pending`
`updated_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`

ProjectEntity

Property	Type	Description
`forked`	Boolean	Example: `true`
`full_name`	String	Example: `GitLab Org / GitLab`
`full_path`	String	Example: `gitlab-org/gitlab`
`id`	Integer	Example: `1`
`name`	String	Example: `GitLab`
`refs_url`	String	—

ProjectImportEntity

Property	Type	Description
`forked`	Boolean	Example: `true`
`full_name`	String	Example: `GitLab Org / GitLab`
`full_path`	String	Example: `gitlab-org/gitlab`
`human_import_status_name`	String	Example: `canceled`
`id`	Integer	Example: `1`
`import_error`	String	—
`import_source`	String	Example: `source/source-repo`
`import_status`	String	Allowed values: `scheduled`, `started`, `finished`, `failed`, `canceled` Example: `scheduled`
`import_warning`	String	—
`name`	String	Example: `GitLab`
`provider_link`	String	Example: `/source/source-repo`
`refs_url`	String	—
`relation_type`	String	—

Import repository from Bitbucket Cloud

Import repository from Bitbucket Server

Import a repository from GitHub

Cancel a GitHub project import

Import a project from a local archive

Import project resources

Authorize project relation import

Workhorse authorize the project import upload

Import a project from a remote archive

Import a project from an AWS S3 bucket

Retrieve the status of a project export

Export a project

Download a project export

Schedule a relations export for a project

Download a relations export for a project

Retrieve the status of an relations export for a project

Receive a GitHub webhook delivery for an OAuth-connected repository

Retrieve the status of a project import

Import a project from a Git URL

Retrieve the status of a project resource import

Schemas

APIEntitiesBulkImportsExportBatchStatus

APIEntitiesBulkImportsExportStatus

APIEntitiesProjectExportStatus

APIEntitiesProjectImportFailedRelation

APIEntitiesProjectImportStatus

APIEntitiesRelationImportTracker

ProjectEntity

ProjectImportEntity

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error