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	ID or URL-encoded path of the project Example: `1`
`sha` Query	String	Commit SHA to download. Accepts a tag, branch reference, or SHA. If omitted, defaults to the tip of the default branch Example: `7d70e02340bac451f281cecf0a980907974bd8be`
`ref_type` Query	String	Type of ref in `sha`. Use to select the correct ref when a branch and tag share a name Allowed values: `heads`, `tags`
`format` Query	String	Archive format Example: `tar.gz`
`path` Query	String	Subpath of the repository to download. An empty string returns the whole repository Example: `files/archives`
`include_lfs_blobs` Query	Boolean	If `true`, LFS objects are included in the archive. When set to `false`, LFS objects are excluded 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	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, up to a maximum of 20
`files[].path` Required	String	Path of the file in the repository Example: `app/models/user.rb`
`files[].ref`	String	Branch, tag, or commit to read the file from. Defaults to the default branch Example: `main`

Responses

Code	Description	Schema
`200`	OK	Array of 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	ID or URL-encoded path of the project Example: `1`
`sha` Path, required	String	SHA of the blob 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	ID or URL-encoded path of the project Example: `1`
`sha` Path, required	String	SHA of the blob 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	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	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of 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	ID or URL-encoded path of the project Example: `1`
`version` Query, required	String	Version to generate the changelog for. Must follow 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	First commit in the range of commits, as a SHA, to use for the changelog. This commit is not included in the changelog. If omitted, the most recent stable version tag before `version` is used Example: `ed899a2f4b50b4370feeea94676502b42383c746`
`to` Query	String	Last commit in the range of commits, as a SHA, to use for the changelog. This commit is included in the changelog. If omitted, uses the latest commit on the default branch. For the Add changelog data to file operation, uses the latest commit on `branch` instead. The range can contain at most 15,000 commits Example: `6104942438c14ec7bd21c6cd5bd995272b3faff6`
`date` Query	String (date-time)	Date and time of the release. Defaults to the current time Example: `2021-09-20T11:50:22.001+00:00`
`trailer` Query	String	Git trailer to use for including commits. Case-sensitive: `Example` does not match `example` or `eXaMpLE` Default: `Changelog` Example: `Changelog`
`config_file` Query	String	Path to the changelog configuration file in the project’s Git repository. If omitted, uses `.gitlab/changelog_config.yml` Example: `.gitlab/changelog_config.yml`
`config_file_ref` Query	String	Git reference, for example a branch, where the changelog configuration file is defined. Defaults to the default branch of the repository 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	ID or URL-encoded path of the project Example: `1`

Request body (application/json)

Property	Type	Description
`branch`	String	Name of the branch to commit the changelog changes to. If omitted, defaults to the project’s default branch Example: `main`
`config_file`	String	Path to the changelog configuration file in the project’s Git repository. If omitted, uses `.gitlab/changelog_config.yml` Example: `.gitlab/changelog_config.yml`
`config_file_ref`	String	Git reference, for example a branch, where the changelog configuration file is defined. Defaults to the default branch of the repository Example: `main`
`date`	String (date-time)	Date and time of the release. Defaults to the current time Example: `2021-09-20T11:50:22.001+00:00`
`file`	String	File to commit the changes to Default: `CHANGELOG.md` Example: `CHANGELOG.md`
`from`	String	First commit in the range of commits, as a SHA, to use for the changelog. This commit is not included in the changelog. If omitted, the most recent stable version tag before `version` is used Example: `ed899a2f4b50b4370feeea94676502b42383c746`
`message`	String	Commit message to use when committing the changelog changes. If omitted, defaults to `Add changelog for version X`, where `X` is the value of the `version` parameter Example: `Initial commit`
`to`	String	Last commit in the range of commits, as a SHA, to use for the changelog. This commit is included in the changelog. If omitted, uses the latest commit on the default branch. For the Add changelog data to file operation, uses the latest commit on `branch` instead. The range can contain at most 15,000 commits Example: `6104942438c14ec7bd21c6cd5bd995272b3faff6`
`trailer`	String	Git trailer to use for including commits. Case-sensitive: `Example` does not match `example` or `eXaMpLE` 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	ID or URL-encoded path of the project Example: `1`
`from` Query, required	String	Ref to compare from. Accepts a commit SHA, branch name, or tag name Example: `main`
`to` Query, required	String	Ref to compare to. Accepts a commit SHA, branch name, or tag name Example: `feature`
`from_project_id` Query	Integer	ID of the project to compare from Example: `1`
`straight` Query	Boolean	If `true`, comparison method is direct comparison between `from` and `to` (`from`..`to`). If `false`, compares using merge base (`from`…`to`) Default: `false`
`unidiff` Query	Boolean	If `true`, presents diffs in the 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	ID or URL-encoded path of the project Example: `1`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`ref` Query	String	Name of a repository branch or tag. If omitted, uses the default branch Example: `main`
`order_by` Query	String	Sort results by the specified field Allowed values: `email`, `name`, `commits` Default: `commits`
`sort` Query	String	Sort results in ascending or descending order 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	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	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of 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	ID or URL-encoded path of the project Example: `1`
`from` Query, required	String	Ref to compare from. Accepts a commit SHA, branch name, or tag name Maximum length: `255` Example: `main`
`to` Query, required	String	Ref to compare to. Accepts a commit SHA, branch name, or tag name Maximum length: `255` Example: `feature`
`max_count` Query	Integer	Maximum number of commits to count. Use `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	ID or URL-encoded path of the project Example: `1`
`generate` Query	Boolean	If `true`, generates a new health report. Set this if the endpoint returns `404` 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	ID or URL-encoded path of the project Example: `1`
`refs` Query, required	Array of strings	Refs to find the common ancestor of. Accepts multiple refs 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	ID or URL-encoded path of the project Example: `1`
`ref` Query	String	Name of a repository branch or tag. If omitted, uses the default branch Maximum length: `1024` Example: `main`
`path` Query	String	Path inside the repository, used to get the contents of subdirectories Maximum length: `1024` Example: `files/html`
`recursive` Query	Boolean	If `true`, returns a recursive tree Default: `false`
`with_last_commit` Query	Boolean	If `true`, includes the last commit for each tree entry. Cannot be combined with `recursive`. Introduced in GitLab 19.3 Default: `false`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`pagination` Query	String	Pagination method. `keyset` uses the keyset-based pagination method. `none` is valid only if `recursive` is `true` Allowed values: `legacy`, `keyset`, `none` Default: `legacy`
`page_token` Query	String	Tree record ID at which to fetch the next page. Used only with 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

Request partner program details

Request received

Error