Project import and export API | GitLab Docs
/ Project import and export API Tier : Free, Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed, GitLab Dedicated Use this API to migrate a project . If you first migrate the parent group structure with the group import and export API , you can preserve group-level relationships, such as connections between project issues and group epics. After using this API, you might want to use the project-level CI/CD variables API to preserve the CI/CD variables for the project.
You must still migrate your container registry over a series of Docker pulls and pushes. Re-run any CI/CD pipelines to retrieve any build artifacts. Prerequisites: For project exports, see export a project and its data . For project imports, see import a project and its data . Export a project excluded_relations attribute introduced in GitLab 18.11. avatar , lfs_objects , uploads , and wiki_repository values for excluded_relations added in GitLab 19.6.
Exports the specified project. Use the upload hash parameter to upload the exported project to a web server or any S3-compatible platform. For exports, GitLab: Only supports binary data file uploads to the final server. Sends the Content-Type: application/gzip header with upload requests. Ensure that your pre-signed URL includes this as part of the signature. Can take some time to complete the project export process. Make sure the upload URL doesn’t have a short expiration time and is available throughout the export process.
Administrators can modify the maximum export file size. By default, the maximum is unlimited ( 0 ). To change this, edit max_export_size using either: GitLab UI . Application settings API Excluded lfs_objects and uploads relations do not count toward the maximum export file size. Has a fixed limit for the maximum import file size on GitLab.com. For more information, see account and limit settings . The upload[url] parameter is required if the upload parameter is present.
For uploads to Amazon S3, refer to generating a pre-signed URL for uploading objects documentation scripts to generate the upload[url] . Because of a known issue , you can only upload files with a maximum file size of 5 GB to Amazon S3. POST /projects/:id/export Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of the project . upload[url] string Yes The URL to upload the project. description string No Overrides the project description. excluded_relations array of strings No Names of the relations to exclude from the export.
Excluded relations are not added to the archive and not available to import. For valid names, see exclude relations from a project export . upload hash No Hash that contains the information to upload the exported project to a web server. upload[http_method] string No The HTTP method to upload the exported project. Only PUT and POST methods allowed. Default is PUT . shell curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/export" \ --data "upload[http_method]=PUT" \ --data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<your_access_token>%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd" json { "message" : "202 Accepted" } Exclude relations from a project export To reduce the size of an export or avoid timeouts, use excluded_relations to leave out data.
The archive does not contain excluded relations and so excluded relations can’t be imported. Valid names for excluded_relations include issues , merge_requests , ci_pipelines , uploads , lfs_objects , avatar , and wiki_repository . For other project data, use the relation names under tree.project or ee.tree.project (GitLab Enterprise Edition) in import_export.yml . You cannot exclude: project , because the import of the archive will fail. repository , snippets_repository , and design_repository , because the archive will restore a broken project.
The snippets relation and the design records in the issues relation point to content that is stored in the snippet and design repositories. If the request contains a name that is unknown or cannot be excluded, the API returns 400 Bad request and a message that lists those names, for example Invalid excluded_relations: repository . The following example excludes the uploads and lfs_objects relations: shell curl --request POST \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/export" \ --data "excluded_relations[]=uploads" \ --data "excluded_relations[]=lfs_objects" Retrieve the status of a project export Retrieves the status of the most recent export for a specified project.
GET /projects/:id/export Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of the project . shell curl --request GET \ --header "PRIVATE-TOKEN: <your_access_token>" \ --url "https://gitlab.example.com/api/v4/projects/1/export" Status can be one of: none : No exports queued, started, finished, or being regenerated. queued : The request for export is received, and is in the queue to be processed. started : The export process has started and is in progress.
It includes: The process of exporting. Actions performed on the resulting file, such as sending an email notifying the user to download the file, or uploading the exported file to a web server. finished : After the export process has completed and the user has been notified. regeneration_in_progress : An export file is available to download, and a request to generate a new export is in process. _links are only present when export has finished. created_at is the project create timestamp, not the export start time. json { "id" : 1 , "description" : "Itaque perspiciatis minima aspernatur corporis consequatur." , "name" : "Gitlab Test" , "name_with_namespace" : "Gitlab Org / Gitlab Test" , "path" : "gitlab-test" , "path_with_namespace" : "gitlab-org/gitlab-test" , "created_at" : "2017-08-29T04:36:44.383Z" , "export_status" : "finished" , "_links" : { "api_url" : "https://gitlab.example.com/api/v4/projects/1/export/download" , "web_url" : "https://gitlab.example.com/gitlab-org/gitlab-test/download_export" } } Download a project export Downloads the most recent export of a specified project.
GET /projects/:id/export/download Attribute Type Required Description id integer or string Yes The ID or URL-encoded path of the project . shell curl --request GET \ --header "PRIVATE-TOKEN: <your_access_token>" \ --remote-header-name \ --remote-name \ --url "https://gitlab.example.com/api/v4/projects/5/export/download" shell ls *export.tar.gz 2017-12-05_22-11-148_namespace_project_export.tar.gz Import a project from a local archive namespace_id and namespace_path attributes introduced in GitLab 18.7.
Imports a project from a local archive. POST /projects/import Attribute Type Required Description file string Yes The file to be uploaded. path string Yes Name and path for new project. name string No The name of the project to be imported. Defaults to the path of the project if not provided. namespace integer or string No (Deprecated) The ID or path of the namespace to import the project to. Defaults to the current user’s namespace.
Requires the Maintainer or Owner role on the destination group. Use namespace_id or namespace_path instead. namespace_id integer No The ID of the namespace to import the project to. Defaults to the current user’s namespace. Requires the Maintainer or Owner role on the destination group. namespace_path string No The path of the namespace to import the project to. Defaults to the current user’s namespace. Requires the Maintainer or Owner role on the destination group. override_params hash No Supports all fields defined in the project API . overwrite boolean No If there is a
The rest of this page is on the live site.