Repositories

Use this API to manage Git repositories.

Retrieve file archive from a repository

GET /api/v4/projects/{id}/repository/archive

Retrieves the file archive of a specified repository. This endpoint can be accessed without authentication if the repository is publicly accessible. For GitLab.com users, this endpoint has a rate limit threshold of 5 requests per minute.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`sha` Query	String	The commit sha of the archive to be downloaded Example: `7d70e02340bac451f281cecf0a980907974bd8be`
`ref_type` Query	String	Type of ref in sha, heads (branch) or tags (tag) Allowed values: `heads`, `tags`
`format` Query	String	The archive format Example: `tar.gz`
`path` Query	String	Subfolder of the repository to be downloaded Example: `files/archives`
`include_lfs_blobs` Query	Boolean	Used to exclude LFS objects from archive Default: `true`
`exclude_paths` Query	Array of strings	Comma-separated list of paths to exclude from the archive Default: `[]`

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not Found	—

Get contents of multiple files in a single request

POST /api/v4/projects/{id}/repository/blobs/batch

Each blob is truncated to the first 1 MB; the truncated field indicates when this happens.

Parameters

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

Request body (application/json)

Property	Type	Description
`files` Required	Array of objects	Array of file objects to retrieve (max 20)
`files[].path` Required	String	The file path Example: `app/models/user.rb`
`files[].ref`	String	The branch, tag, or commit. Defaults to the default branch Example: `main`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesBatchBlob
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—

Retrieve a blob from a repository

GET /api/v4/projects/{id}/repository/blobs/{sha}

Retrieves information, such as size and content, about blobs in a repository. Blob content is Base64 encoded. This endpoint can be accessed without authentication, if the repository is publicly accessible.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`sha` Path, required	String	The commit hash Example: `7d70e02340bac451f281cecf0a980907974bd8be`

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not Found	—

Retrieve raw blob content

GET /api/v4/projects/{id}/repository/blobs/{sha}/raw

Retrieves the raw file contents for a blob, by blob SHA. This endpoint can be accessed without authentication if the repository is publicly accessible.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`sha` Path, required	String	The commit hash Example: `7d70e02340bac451f281cecf0a980907974bd8be`

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not Found	—

List files changed between two commits

GET /api/v4/projects/{id}/repository/changed_paths

Returns the path, change status, and file modes for every path that differs between two refs.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`from` Query, required	String	The commit SHA or branch/tag to compare from Maximum length: `255` Example: `main`
`to` Query, required	String	The commit SHA or branch/tag to compare to Maximum length: `255` Example: `feature`
`find_renames` Query	Boolean	If true, detect file renames Default: `false`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesChangedPath
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—
`429`	Too Many Requests	—

Generate changelog data

GET /api/v4/projects/{id}/repository/changelog

Generates changelog data based on commits in a repository, without committing them to a changelog file. Works exactly like POST /projects/:id/repository/changelog, except the changelog data is not committed to any changelog file.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`version` Query, required	String	The version of the release, using the semantic versioning format Pattern: `(?:(?:(0\|[1-9]\d))\.(?:(0\|[1-9]\d))\.(?:(0\|[1-9]\d)))(?:(?:-((?:\d[a-zA-Z\-][0-9a-zA-Z\-]\|[1-9]\d\|0)(?:\.(?:\d[a-zA-Z\-][0-9a-zA-Z\-]\|[1-9]\d\|0))))?(?:\+([0-9a-zA-Z\-]+(?:\.[0-9a-zA-Z\-]+)*))?)` Example: `1.0.0`
`from` Query	String	The first commit in the range of commits to use for the changelog Example: `ed899a2f4b50b4370feeea94676502b42383c746`
`to` Query	String	The last commit in the range of commits to use for the changelog Example: `6104942438c14ec7bd21c6cd5bd995272b3faff6`
`date` Query	String (date-time)	The date and time of the release Example: `2021-09-20T11:50:22.001+00:00`
`trailer` Query	String	The Git trailer to use for determining if commits are to be included in the changelog Default: `Changelog` Example: `Changelog`
`config_file` Query	String	The file path to the configuration file as stored in the project’s Git repository. Defaults to ‘.gitlab/changelog_config.yml’ Example: `.gitlab/changelog_config.yml`
`config_file_ref` Query	String	The git reference (for example, branch) where the changelog configuration file is defined. Defaults to the default repository branch Example: `main`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesChangelog
`400`	Bad Request	—
`404`	Not Found	—

Add changelog data to file

POST /api/v4/projects/{id}/repository/changelog

Adds changelog data to file.

Parameters

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

Request body (application/json)

Property	Type	Description
`branch`	String	The branch to commit the changelog changes to Example: `main`
`config_file`	String	The file path to the configuration file as stored in the project’s Git repository. Defaults to ‘.gitlab/changelog_config.yml’ Example: `.gitlab/changelog_config.yml`
`config_file_ref`	String	The git reference (for example, branch) where the changelog configuration file is defined. Defaults to the default repository branch Example: `main`
`date`	String (date-time)	The date and time of the release Example: `2021-09-20T11:50:22.001+00:00`
`file`	String	The file to commit the changelog changes to Default: `CHANGELOG.md` Example: `CHANGELOG.md`
`from`	String	The first commit in the range of commits to use for the changelog Example: `ed899a2f4b50b4370feeea94676502b42383c746`
`message`	String	The commit message to use when committing the changelog Example: `Initial commit`
`to`	String	The last commit in the range of commits to use for the changelog Example: `6104942438c14ec7bd21c6cd5bd995272b3faff6`
`trailer`	String	The Git trailer to use for determining if commits are to be included in the changelog Default: `Changelog` Example: `Changelog`

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not Found	—

Compare branches, tags, or commits

GET /api/v4/projects/{id}/repository/compare

Compares branches, tags, or commits. Retrieves the differences between two branches, tags, or commits in a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`from` Query, required	String	The commit, branch name, or tag name to start comparison Example: `main`
`to` Query, required	String	The commit, branch name, or tag name to stop comparison Example: `feature`
`from_project_id` Query	Integer	The project to compare from Example: `1`
`straight` Query	Boolean	Comparison method, `true` for direct comparison between `from` and `to` (`from`..`to`), `false` to compare using merge base (`from`…`to`) Default: `false`
`unidiff` Query	Boolean	A diff in a Unified diff format Default: `false`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCompare
`400`	Bad Request	—
`404`	Not Found	—

Retrieve contributors metrics

GET /api/v4/projects/{id}/repository/contributors

Retrieves a list of contributors to a specified repository.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`ref` Query	String	The name of a repository branch or tag, if not given the default branch is used Example: `main`
`order_by` Query	String	Return contributors ordered by `name` or `email` or `commits` Allowed values: `email`, `name`, `commits` Default: `commits`
`sort` Query	String	Sort by asc (ascending) or desc (descending) Allowed values: `asc`, `desc` Default: `asc`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesContributor
`400`	Bad Request	—
`404`	Not Found	—

Get diff statistics between two commits

GET /api/v4/projects/{id}/repository/diff_stats

Returns the number of added and deleted lines for every file that differs between two refs.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`from` Query, required	String	The commit SHA or branch/tag to compare from Maximum length: `255` Example: `main`
`to` Query, required	String	The commit SHA or branch/tag to compare to Maximum length: `255` Example: `feature`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesDiffStat
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`429`	Too many requests	—

Retrieve diverging commit counts between two refs

GET /api/v4/projects/{id}/repository/diverging_commits

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`from` Query, required	String	The ref to compare from Maximum length: `255` Example: `main`
`to` Query, required	String	The ref to compare to Maximum length: `255` Example: `feature`
`max_count` Query	Integer	Maximum number of commits to count. 0 for unlimited Default: `0` Minimum: `0` Example: `1000`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesDivergingCommitCount
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—
`429`	Too many requests	—

Retrieve repository health statistics

GET /api/v4/projects/{id}/repository/health

Retrieves statistics related to the health of a project repository. This endpoint is rate-limited to 5 requests/hour per project when generate is true. Available only to users with push access to the repository.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`generate` Query	Boolean	Triggers a new health report to be generated Default: `false`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesRepositoryHealth
`400`	Bad Request	—
`404`	Not Found	—

Retrieve a merge base

GET /api/v4/projects/{id}/repository/merge_base

Retrieves the merge base for two specified commits.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`refs` Query, required	Array of strings	The refs to find the common ancestor of, multiple refs can be passed Example: `["main","feature"]`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCommit
`400`	Bad Request	—
`404`	Not Found	—

List all repository trees in a project

GET /api/v4/projects/{id}/repository/tree

Lists all repository files and directories in a specified project. This endpoint can be accessed without authentication if the repository is publicly accessible. This command provides essentially the same features as the git ls-tree command. Use with_last_commit to include the last commit that changed each entry. with_last_commit cannot be combined with recursive.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `1`
`ref` Query	String	The name of a repository branch or tag, if not given the default branch is used Maximum length: `1024` Example: `main`
`path` Query	String	The path of the tree Maximum length: `1024` Example: `files/html`
`recursive` Query	Boolean	Used to get a recursive tree Default: `false`
`with_last_commit` Query	Boolean	Include the last commit for each tree entry. Cannot be combined with “recursive” Default: `false`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`pagination` Query	String	Specify the pagination method (“none” is only valid if “recursive” is true) Allowed values: `legacy`, `keyset`, `none` Default: `legacy`
`page_token` Query	String	Record from which to start the keyset pagination Example: `a1e8f8d745cc87e3a9248358d9352bb7f9a0aeba`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesTreeObject
`400`	Bad Request	—
`404`	404 Project Not Found	—

Schemas

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

APIEntitiesBatchBlob

Property	Type	Description
`content`	String	Example: `VGhpcyBpcyBhIGZpbGU=`
`encoding`	String	Example: `base64`
`path`	String	Example: `app/models/user.rb`
`ref`	String	Example: `main`
`size`	Integer	Example: `1476`
`truncated`	Boolean	Example: `false`

APIEntitiesChangedPath

Property	Type	Description
`new_mode`	String	Example: `100644`
`old_mode`	String	Example: `100644`
`old_path`	String	Example: `app/models/user.rb`
`path`	String	Example: `app/models/user.rb`
`status`	String	Example: `MODIFIED`

APIEntitiesChangelog

Property	Type	Description
`notes`	String	Example: `## 1.0.0 (2023-01-01)`

APIEntitiesCommit

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`created_at`	String (date-time)	Example: `2017-07-26T11:08:53.000+02:00`
`extended_trailers`	Object	Example: `{"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`
`short_id`	String	Example: `2695effb`
`title`	String	Example: `Initial commit`
`trailers`	Object	Example: `{"Merged-By":"Jane Doe janedoe@gitlab.com"}`
`web_url`	String	Example: `https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746`

APIEntitiesCompare

Property	Type	Description
`commit`	APIEntitiesCommit	—
`commits`	Array of APIEntitiesCommit	—
`compare_same_ref`	Boolean	—
`compare_timeout`	Boolean	—
`diffs`	Array of APIEntitiesDiff	—
`web_url`	String	Example: `https://gitlab.example.com/gitlab/gitlab-foss/-/compare/main...feature`

APIEntitiesContributor

Property	Type	Description
`additions`	Integer	Example: `3`
`commits`	Integer	Example: `117`
`deletions`	Integer	Example: `5`
`email`	String	Example: `johndoe@example.com`
`name`	String	Example: `John Doe`

APIEntitiesDiff

Property	Type	Description
`a_mode`	String	Example: `100755`
`b_mode`	String	Example: `100644`
`collapsed`	Boolean	—
`deleted_file`	Boolean	—
`diff`	String	Example: `@@ -71,6 +71,8 @@\n...`
`generated_file`	Boolean	—
`new_file`	Boolean	—
`new_path`	String	Example: `doc/update/5.4-to-6.0.md`
`old_path`	String	Example: `doc/update/5.4-to-6.0.md`
`renamed_file`	Boolean	—
`too_large`	Boolean	—

APIEntitiesDiffStat

Property	Type	Description
`additions`	Integer	Example: `10`
`deletions`	Integer	Example: `3`
`old_path`	String	Example: `app/models/user.rb`
`path`	String	Example: `app/models/user.rb`

APIEntitiesDivergingCommitCount

Property	Type	Description
`ahead`	Integer	Example: `5`
`behind`	Integer	Example: `3`

APIEntitiesRepositoryHealth

Property	Type	Description
`alternates`	Object	—
`bitmap`	APIEntitiesRepositoryHealthBitmap	—
`commit_graph`	APIEntitiesRepositoryHealthCommitGraph	—
`is_object_pool`	Boolean	—
`last_full_repack`	APIEntitiesRepositoryHealthLastFullRepack	—
`multi_pack_index`	APIEntitiesRepositoryHealthMultiPackIndex	—
`multi_pack_index_bitmap`	APIEntitiesRepositoryHealthBitmap	—
`objects`	APIEntitiesRepositoryHealthObjects	—
`references`	APIEntitiesRepositoryHealthReferences	—
`size`	Integer	—
`updated_at`	String (date-time)	Example: `2025-02-24T09:05:50.355Z`

APIEntitiesRepositoryHealthBitmap

Property	Type	Description
`has_hash_cache`	Boolean	—
`has_lookup_table`	Boolean	—
`version`	Integer	—

APIEntitiesRepositoryHealthCommitGraph

Property	Type	Description
`commit_graph_chain_length`	Integer	—
`has_bloom_filters`	Boolean	—
`has_generation_data`	Boolean	—
`has_generation_data_overflow`	Boolean	—

APIEntitiesRepositoryHealthLastFullRepack

Property	Type	Description
`nanos`	Integer	—
`seconds`	Integer	—

APIEntitiesRepositoryHealthMultiPackIndex

Property	Type	Description
`packfile_count`	Integer	—
`version`	Integer	—

APIEntitiesRepositoryHealthObjects

Property	Type	Description
`cruft_count`	Integer	—
`keep_count`	Integer	—
`keep_size`	Integer	—
`loose_objects_count`	Integer	—
`loose_objects_garbage_count`	Integer	—
`packfile_count`	Integer	—
`recent_size`	Integer	—
`reverse_index_count`	Integer	—
`size`	Integer	—
`stale_loose_objects_count`	Integer	—
`stale_size`	Integer	—

APIEntitiesRepositoryHealthReferences

Property	Type	Description
`loose_count`	Integer	—
`packed_size`	Integer	—
`reference_backend`	String	—

APIEntitiesTreeObject

Property	Type	Description
`id`	String	Example: `a1e8f8d745cc87e3a9248358d9352bb7f9a0aeba`
`last_commit`	APIEntitiesCommit	—
`mode`	String	Example: `040000`
`name`	String	Example: `html`
`path`	String	Example: `files/html`
`type`	String	Example: `tree`

Retrieve file archive from a repository

Get contents of multiple files in a single request

Retrieve a blob from a repository

Retrieve raw blob content

List files changed between two commits

Generate changelog data

Add changelog data to file

Compare branches, tags, or commits

Retrieve contributors metrics

Get diff statistics between two commits

Retrieve diverging commit counts between two refs

Retrieve repository health statistics

Retrieve a merge base

List all repository trees in a project

Schemas

APIEntitiesBatchBlob

APIEntitiesChangedPath

APIEntitiesChangelog

APIEntitiesCommit

APIEntitiesCompare

APIEntitiesContributor

APIEntitiesDiff

APIEntitiesDiffStat

APIEntitiesDivergingCommitCount

APIEntitiesRepositoryHealth

APIEntitiesRepositoryHealthBitmap

APIEntitiesRepositoryHealthCommitGraph

APIEntitiesRepositoryHealthLastFullRepack

APIEntitiesRepositoryHealthMultiPackIndex

APIEntitiesRepositoryHealthObjects

APIEntitiesRepositoryHealthReferences

APIEntitiesTreeObject

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