[Skip to main content](https://docs.gitlab.com/api/commits/#skipTarget) [Go to GitLab Docs homepage](https://docs.gitlab.com/)
`/`
[What's new?](https://about.gitlab.com/releases/whats-new/)
English
  * Language
  * English
  * 日本語


v18.10
  *     * [18.10 (not yet released)](https://docs.gitlab.com/api/commits/)
  *     * [18.9 (recently released)](https://docs.gitlab.com/18.9/api/commits/)
    * [18.8](https://docs.gitlab.com/18.8/api/commits/)
    * [18.7](https://archives.docs.gitlab.com/18.7/api/commits/)
  *     * [17.11](https://archives.docs.gitlab.com/17.11/api/commits/)
    * [16.11](https://archives.docs.gitlab.com/16.11/ee/api/commits.html)
  *     * [Archives](https://docs.gitlab.com/archives)


Select theme and layout
  * Light mode
  * Dark mode
  * Auto


  * Fixed width
  * Fluid width


[What's new?](https://about.gitlab.com/releases/whats-new/) [Get free trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com&amp;glm_content=navigation-cta-docs)
Toggle menu
  * [Use GitLab](https://docs.gitlab.com/user/)
  * [GitLab Duo](https://docs.gitlab.com/user/gitlab_duo/)
  * [Extend](https://docs.gitlab.com/api/)
  * [Install](https://docs.gitlab.com/install/)
  * [Administer](https://docs.gitlab.com/administration/)
  * [Subscribe](https://docs.gitlab.com/subscriptions/)
  * [Contribute](https://docs.gitlab.com/development/)
  * [Solutions](https://docs.gitlab.com/solutions/)


Select a topicUse GitLab GitLab Duo Extend Install Administer Subscribe Contribute Solutions
[Getting started](https://docs.gitlab.com/api/get_started/get_started_extending/)
[Tutorials](https://docs.gitlab.com/tutorials/develop/)
[Integrations](https://docs.gitlab.com/integration/)
[Webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/)
[REST API](https://docs.gitlab.com/api/rest/)
[Resources](https://docs.gitlab.com/api/api_resources/)
[.gitignore (templates)](https://docs.gitlab.com/api/templates/gitignores/)
[.gitlab-ci.yml (templates)](https://docs.gitlab.com/api/templates/gitlab_ci_ymls/)
[Access requests](https://docs.gitlab.com/api/access_requests/)
[Agent for Kubernetes](https://docs.gitlab.com/api/cluster_agents/)
[AI Catalog admin](https://docs.gitlab.com/api/admin/ai_catalog/)
[Alert management](https://docs.gitlab.com/api/alert_management_alerts/)
[Application appearance](https://docs.gitlab.com/api/appearance/)
[Application settings](https://docs.gitlab.com/api/settings/)
[Application statistics](https://docs.gitlab.com/api/statistics/)
[Applications](https://docs.gitlab.com/api/applications/)
[Attestations](https://docs.gitlab.com/api/attestations/)
[Audit events](https://docs.gitlab.com/api/audit_events/)
[Avatar](https://docs.gitlab.com/api/avatar/)
[Branches](https://docs.gitlab.com/api/branches/)
[Broadcast messages](https://docs.gitlab.com/api/broadcast_messages/)
[Cluster discovery (certificate-based) (deprecated)](https://docs.gitlab.com/api/cluster_discovery/)
[Code Suggestions](https://docs.gitlab.com/api/code_suggestions/)
[Commits](https://docs.gitlab.com/api/commits/)
[Compliance and policy settings](https://docs.gitlab.com/api/compliance_policy_settings/)
[Composer](https://docs.gitlab.com/api/packages/composer/)
[Conan v1](https://docs.gitlab.com/api/packages/conan_v1/)
[Conan v2](https://docs.gitlab.com/api/packages/conan_v2/)
[Container registry](https://docs.gitlab.com/api/container_registry/)
[Container repository protection rules](https://docs.gitlab.com/api/container_repository_protection_rules/)
[Container registry protection tag rules](https://docs.gitlab.com/api/container_registry_protection_tag_rules/)
[Container virtual registry](https://docs.gitlab.com/api/container_virtual_registries/)
[Custom attributes](https://docs.gitlab.com/api/custom_attributes/)
[Database migrations](https://docs.gitlab.com/api/database_migrations/)
[Data management](https://docs.gitlab.com/api/admin/data_management/)
[Debian](https://docs.gitlab.com/api/packages/debian/)
[Debian group distributions](https://docs.gitlab.com/api/packages/debian_group_distributions/)
[Debian project distributions](https://docs.gitlab.com/api/packages/debian_project_distributions/)
[Dependencies](https://docs.gitlab.com/api/dependencies/)
[Dependency list export](https://docs.gitlab.com/api/dependency_list_export/)
[Dependency Proxy](https://docs.gitlab.com/api/dependency_proxy/)
[Deploy keys](https://docs.gitlab.com/api/deploy_keys/)
[Deploy tokens](https://docs.gitlab.com/api/deploy_tokens/)
[Deployments](https://docs.gitlab.com/api/deployments/)
[Discussions](https://docs.gitlab.com/api/discussions/)
[Dockerfile (templates)](https://docs.gitlab.com/api/templates/dockerfiles/)
[DORA4 metrics](https://docs.gitlab.com/api/dora/metrics/)
[Emoji reactions](https://docs.gitlab.com/api/emoji_reactions/)
[Environments](https://docs.gitlab.com/api/environments/)
[Epics (deprecated)](https://docs.gitlab.com/api/epics/)
[Error tracking](https://docs.gitlab.com/api/error_tracking/)
[Events](https://docs.gitlab.com/api/events/)
[Experiments](https://docs.gitlab.com/api/experiments/)
[External status checks](https://docs.gitlab.com/api/status_checks/)
[Feature flags](https://docs.gitlab.com/api/feature_flags/)
[Feature flag user lists](https://docs.gitlab.com/api/feature_flag_user_lists/)
[Freeze periods](https://docs.gitlab.com/api/freeze_periods/)
[Geo nodes (deprecated)](https://docs.gitlab.com/api/geo_nodes/)
[Geo sites](https://docs.gitlab.com/api/geo_sites/)
[GitLab Duo Chat completions](https://docs.gitlab.com/api/chat/)
[GitLab Pages](https://docs.gitlab.com/api/pages/)
[GLQL](https://docs.gitlab.com/api/glql/)
[Go Proxy](https://docs.gitlab.com/api/packages/go_proxy/)
[Google Cloud integration](https://docs.gitlab.com/api/google_cloud_integration/)
[Groups](https://docs.gitlab.com/api/groups/)
[Helm](https://docs.gitlab.com/api/packages/helm/)
[Import](https://docs.gitlab.com/api/import/)
[Instance CI/CD variables](https://docs.gitlab.com/api/instance_level_ci_variables/)
[Invitations](https://docs.gitlab.com/api/invitations/)
[Issues](https://docs.gitlab.com/api/issues/)
[Issues (epic) (deprecated)](https://docs.gitlab.com/api/epic_issues/)
[Issues statistics](https://docs.gitlab.com/api/issues_statistics/)
[Jobs](https://docs.gitlab.com/api/jobs/)
[Job artifacts](https://docs.gitlab.com/api/job_artifacts/)
[Job token scopes](https://docs.gitlab.com/api/project_job_token_scopes/)
[Keys](https://docs.gitlab.com/api/keys/)
[License](https://docs.gitlab.com/api/license/)
[Licenses (templates)](https://docs.gitlab.com/api/templates/licenses/)
[Linked epics (deprecated)](https://docs.gitlab.com/api/linked_epics/)
[Links (issue)](https://docs.gitlab.com/api/issue_links/)
[Links (epic) (deprecated)](https://docs.gitlab.com/api/epic_links/)
[Lint .gitlab-ci.yml](https://docs.gitlab.com/api/lint/)
[Markdown](https://docs.gitlab.com/api/markdown/)
[Maven](https://docs.gitlab.com/api/packages/maven/)
[Maven virtual registry](https://docs.gitlab.com/api/maven_virtual_registries/)
[Member roles](https://docs.gitlab.com/api/member_roles/)
[Merge request approvals](https://docs.gitlab.com/api/merge_request_approvals/)
[Merge request approval settings](https://docs.gitlab.com/api/merge_request_approval_settings/)
[Merge request context commits](https://docs.gitlab.com/api/merge_request_context_commits/)
[Merge requests](https://docs.gitlab.com/api/merge_requests/)
[Merge trains](https://docs.gitlab.com/api/merge_trains/)
[Metadata](https://docs.gitlab.com/api/metadata/)
[Model registry](https://docs.gitlab.com/api/model_registry/)
[Namespaces](https://docs.gitlab.com/api/namespaces/)
[Notes (comments)](https://docs.gitlab.com/api/notes/)
[Notification settings](https://docs.gitlab.com/api/notification_settings/)
[npm](https://docs.gitlab.com/api/packages/npm/)
[NuGet](https://docs.gitlab.com/api/packages/nuget/)
[Organizations](https://docs.gitlab.com/api/organizations/)
[Packages](https://docs.gitlab.com/api/packages/)
[Pages domains](https://docs.gitlab.com/api/pages_domains/)
[Personal access tokens](https://docs.gitlab.com/api/personal_access_tokens/)
[Pipeline schedules](https://docs.gitlab.com/api/pipeline_schedules/)
[Pipeline trigger tokens](https://docs.gitlab.com/api/pipeline_triggers/)
[Pipelines](https://docs.gitlab.com/api/pipelines/)
[Plan limits](https://docs.gitlab.com/api/plan_limits/)
[Product analytics](https://docs.gitlab.com/api/product_analytics/)
[Projects](https://docs.gitlab.com/api/projects/)
[PyPI](https://docs.gitlab.com/api/packages/pypi/)
[Repositories](https://docs.gitlab.com/api/repositories/)
[Repository files](https://docs.gitlab.com/api/repository_files/)
[Repository submodules](https://docs.gitlab.com/api/repository_submodules/)
[Resource group](https://docs.gitlab.com/api/resource_groups/)
[Resource iteration events](https://docs.gitlab.com/api/resource_iteration_events/)
[Resource label events](https://docs.gitlab.com/api/resource_label_events/)
[Resource milestone events](https://docs.gitlab.com/api/resource_milestone_events/)
[Resource state events](https://docs.gitlab.com/api/resource_state_events/)
[Resource weight events](https://docs.gitlab.com/api/resource_weight_events/)
[Ruby gems](https://docs.gitlab.com/api/packages/rubygems/)
[Runners](https://docs.gitlab.com/api/runners/)
[Runner controllers](https://docs.gitlab.com/api/runner_controllers/)
[Runner controller tokens](https://docs.gitlab.com/api/runner_controller_tokens/)
[Search](https://docs.gitlab.com/api/search/)
[Search migrations](https://docs.gitlab.com/api/search_admin/)
[Secure files](https://docs.gitlab.com/api/secure_files/)
[Service accounts](https://docs.gitlab.com/api/service_accounts/)
[Service Ping](https://docs.gitlab.com/api/usage_data/)
[Sidekiq metrics](https://docs.gitlab.com/api/sidekiq_metrics/)
[Sidekiq queues](https://docs.gitlab.com/api/admin_sidekiq_queues/)
[Snippet repository storage moves](https://docs.gitlab.com/api/snippet_repository_storage_moves/)
[Snippets](https://docs.gitlab.com/api/snippets/)
[Suggestions](https://docs.gitlab.com/api/suggestions/)
[System hooks](https://docs.gitlab.com/api/system_hooks/)
[Tags](https://docs.gitlab.com/api/tags/)
[Terraform registry](https://docs.gitlab.com/api/packages/terraform-modules/)
[To-Do List](https://docs.gitlab.com/api/todos/)
[Token information](https://docs.gitlab.com/api/admin/token/)
[Topics](https://docs.gitlab.com/api/topics/)
[Users](https://docs.gitlab.com/api/users/)
[Version](https://docs.gitlab.com/api/version/)
[Virtual registries cleanup policies](https://docs.gitlab.com/api/virtual_registries_cleanup_policies/)
[Vulnerabilities](https://docs.gitlab.com/api/vulnerabilities/)
[Vulnerability archive export](https://docs.gitlab.com/api/vulnerability_archive_exports/)
[Vulnerability export](https://docs.gitlab.com/api/vulnerability_exports/)
[Vulnerability findings](https://docs.gitlab.com/api/vulnerability_findings/)
[Web commits](https://docs.gitlab.com/api/web_commits/)
[Authentication](https://docs.gitlab.com/api/rest/authentication/)
[Third-party clients](https://docs.gitlab.com/api/rest/third_party_clients/)
[Deprecations and removals](https://docs.gitlab.com/api/rest/deprecations/)
[OpenAPI](https://docs.gitlab.com/api/openapi/openapi_interactive/)
[Automate storage management](https://docs.gitlab.com/user/storage_management_automation/)
[Troubleshooting](https://docs.gitlab.com/api/rest/troubleshooting/)
[GraphQL API](https://docs.gitlab.com/api/graphql/)
[OAuth 2.0 identity provider API](https://docs.gitlab.com/api/oauth2/)
[GitLab Duo CLI (duo)](https://docs.gitlab.com/user/gitlab_duo_cli/)
[GitLab CLI (glab)](https://docs.gitlab.com/cli/)
[Editor and IDE extensions](https://docs.gitlab.com/editor_extensions/)
/
  1. [GitLab Docs](https://docs.gitlab.com/)
  2. [Extend](https://docs.gitlab.com/api/)
  3. [REST API](https://docs.gitlab.com/api/rest/)
  4. [Resources](https://docs.gitlab.com/api/api_resources/)
  5. [Commits](https://docs.gitlab.com/api/commits/)


* * *
# Commits API
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


Use this API to manage [Git commits](https://docs.gitlab.com/user/project/repository/commits/).
## Responses[](https://docs.gitlab.com/api/commits/#responses "Permalink")
Some date fields in responses from this API are, or can appear to be, duplicated information:
  * The `created_at` field exists solely for consistency with other GitLab APIs. It is always identical to the `committed_date` field.
  * The `committed_date` and `authored_date` fields are generated from different sources, and may not be identical.


### Pagination response headers[](https://docs.gitlab.com/api/commits/#pagination-response-headers "Permalink")
For performance reasons, GitLab does not return the following headers in Commits API responses:
  * `x-total`
  * `x-total-pages`


For more information, see [issue 389582](https://gitlab.com/gitlab-org/gitlab/-/issues/389582).
## List repository commits[](https://docs.gitlab.com/api/commits/#list-repository-commits "Permalink")
Get a list of repository commits in a project.
```
GET /projects/:id/repository/commits
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`all` | boolean | No | Retrieve every commit from the repository. If `true`, the `ref_name` parameter is ignored.
`author` | string | No | Search commits by commit author.
`first_parent` | boolean | No | If `true`, follows only the first parent commit upon seeing a merge commit.
`order` | string | No | List commits in order. Possible values: `default`, [`topo`](https://git-scm.com/docs/git-log#Documentation/git-log.txt---topo-order). Defaults to `default`, the commits are shown in reverse chronological order.
`path` | string | No | The file path.
`ref_name` | string | No | The name of a repository branch, tag or revision range, or if not given the default branch.
`since` | string | No | Only commits after or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ`.
`trailers` | boolean | No | If `true`, parses and includes [Git trailers](https://git-scm.com/docs/git-interpret-trailers) for every commit.
`until` | string | No | Only commits before or on this date are returned in ISO 8601 format `YYYY-MM-DDTHH:MM:SSZ`.
`with_stats` | boolean | No | If `true`, retrieve stats about each commit.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`author_email` | string | Email address of the commit author.
`author_name` | string | Name of the commit author.
`authored_date` | string | Date when the commit was authored.
`committed_date` | string | Date when the commit was committed.
`committer_email` | string | Email address of the commit committer.
`committer_name` | string | Name of the commit committer.
`created_at` | string | Date when the commit was created (identical to `committed_date`).
`extended_trailers` | object | Extended Git trailers with all values.
`id` | string | SHA of the commit.
`message` | string | Full commit message.
`parent_ids` | array | Array of parent commit SHAs.
`short_id` | string | Short SHA of the commit.
`title` | string | Title of the commit message.
`trailers` | object | Git trailers parsed from the commit message.
`web_url` | string | Web URL of the commit.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits"
```

Example response:
json
```
[
  {
    "id": "ed899a2f4b50b4370feeea94676502b42383c746",
    "short_id": "ed899a2f4b5",
    "title": "Replace sanitize with escape once",
    "author_name": "Example User",
    "author_email": "user@example.com",
    "authored_date": "2021-09-20T11:50:22.001+00:00",
    "committer_name": "Administrator",
    "committer_email": "admin@example.com",
    "committed_date": "2021-09-20T11:50:22.001+00:00",
    "created_at": "2021-09-20T11:50:22.001+00:00",
    "message": "Replace sanitize with escape once",
    "parent_ids": [
      "6104942438c14ec7bd21c6cd5bd995272b3faff6"
    ],
    "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746",
    "trailers": {},
    "extended_trailers": {}
  },
  {
    "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
    "short_id": "6104942438c",
    "title": "Sanitize for network graph",
    "author_name": "randx",
    "author_email": "user@example.com",
    "committer_name": "ExampleName",
    "committer_email": "user@example.com",
    "created_at": "2021-09-20T09:06:12.201+00:00",
    "message": "Sanitize for network graph\nCc: John Doe <johndoe@gitlab.com>\nCc: Jane Doe <janedoe@gitlab.com>",
    "parent_ids": [
      "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
    ],
    "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746",
    "trailers": {
      "Cc": "Jane Doe <janedoe@gitlab.com>"
    },
    "extended_trailers": {
      "Cc": [
        "John Doe <johndoe@gitlab.com>",
        "Jane Doe <janedoe@gitlab.com>"
      ]
    }
  }
]
```

## Create a commit[](https://docs.gitlab.com/api/commits/#create-a-commit "Permalink")
History
  * `allow_empty` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/211520) in GitLab 18.8.
  * Request size and rate limits introduced in GitLab 18.7.


Create a commit by posting a JSON payload
```
POST /projects/:id/repository/commits
```

This endpoint is subject to [request size and rate limits](https://docs.gitlab.com/administration/instance_limits/#commits-and-files-api-limits). Requests larger than a default 300 MB limit are rejected. Requests greater than 20 MB are rate limited to 3 requests every 30 seconds.
Attribute | Type | Required | Description
---|---|---|---
`branch` | string | Yes | Name of the branch to commit into. To create a new branch, also provide either `start_branch` or `start_sha`, and optionally `start_project`.
`commit_message` | string | Yes | Commit message.
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`actions[]` | array | No | An array of action hashes to commit as a batch. See the next table for what attributes it can take.
`allow_empty` | boolean | No | When `true`, creates an empty commit. Default is `false`.
`author_email` | string | No | Specify the commit author’s email address.
`author_name` | string | No | Specify the commit author’s name.
`force` | boolean | No | If `true`, overwrites `branch` with a new commit based on `start_branch` or `start_sha`, replacing the branch’s existing commit history. Default is `false`. 1
`start_branch` | string | No | Name of the branch to use as the parent for the new commit. If not provided and `start_sha` is also not provided, defaults to the value of `branch`. Mutually exclusive with `start_sha`. 1
`start_project` | integer or string | No | The project ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths) to use as the source for `start_branch` or `start_sha`. Defaults to the value of `id`.
`start_sha` | string | No | SHA of the commit to use as the parent for the new commit. Must be a full 40-character SHA. Mutually exclusive with `start_branch`. 1
`stats` | boolean | No | Include commit stats. Default is `true`.
**Footnotes** :
  1. When `force` is `true`, provide `start_branch` or `start_sha` to specify a different parent commit. If neither is provided, `start_branch` defaults to the value of `branch`, and the new commit is based on the current branch tip. In that case, `force` has no effect because the result is the same as a regular commit.


Large requests with many actions may be subject to size limits. For more information, see [Commits API limits](https://docs.gitlab.com/administration/instance_limits/#commits-and-files-api-limits).
`actions[]` Attribute | Type | Required | Description
---|---|---|---
`action` | string | Yes | The action to perform: `create`, `delete`, `move`, `update`, or `chmod`.
`file_path` | string | Yes | Full path to the file. For example: `lib/class.rb`.
`content` | string | No | File content, required for all except `delete`, `chmod`, and `move`. Move actions that do not specify `content` preserve the existing file content, and any other value of `content` overwrites the file content.
`encoding` | string | No |  `text` or `base64`. `text` is default.
`execute_filemode` | boolean | No | If `true`, enables the execute flag on the file. If `false`, disables it. Only considered for `chmod` action.
`last_commit_id` | string | No | Last known file commit ID. Only considered in update, move, and delete actions.
`previous_path` | string | No | Original full path to the file being moved. For example `lib/class1.rb`. Only considered for `move` action.
If successful, returns [`201 Created`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`author_email` | string | Email address of the commit author.
`author_name` | string | Name of the commit author.
`authored_date` | string | Date when the commit was authored.
`committed_date` | string | Date when the commit was committed.
`committer_email` | string | Email address of the commit committer.
`committer_name` | string | Name of the commit committer.
`created_at` | string | Date when the commit was created.
`id` | string | SHA of the created commit.
`message` | string | Full commit message.
`parent_ids` | array | Array of parent commit SHAs.
`short_id` | string | Short SHA of the created commit.
`stats` | object | Statistics about the commit (additions, deletions, total).
`status` | string | Status of the commit.
`title` | string | Title of the commit message.
`web_url` | string | Web URL of the commit.
shell
```
PAYLOAD=$(cat << 'JSON'
{
  "branch": "main",
  "commit_message": "some commit message",
  "actions": [
    {
      "action": "create",
      "file_path": "foo/bar",
      "content": "some content"
    },
    {
      "action": "delete",
      "file_path": "foo/bar2"
    },
    {
      "action": "move",
      "file_path": "foo/bar3",
      "previous_path": "foo/bar4",
      "content": "some content"
    },
    {
      "action": "update",
      "file_path": "foo/bar5",
      "content": "new content"
    },
    {
      "action": "chmod",
      "file_path": "foo/bar5",
      "execute_filemode": true
    }
  ]
}
JSON
)
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data "$PAYLOAD" \
  --url "https://gitlab.example.com/api/v4/projects/1/repository/commits"
```

Example response:
json
```
{
  "id": "ed899a2f4b50b4370feeea94676502b42383c746",
  "short_id": "ed899a2f4b5",
  "title": "some commit message",
  "author_name": "Example User",
  "author_email": "user@example.com",
  "committer_name": "Example User",
  "committer_email": "user@example.com",
  "created_at": "2016-09-20T09:26:24.000-07:00",
  "message": "some commit message",
  "parent_ids": [
    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
  ],
  "committed_date": "2016-09-20T09:26:24.000-07:00",
  "authored_date": "2016-09-20T09:26:24.000-07:00",
  "stats": {
    "additions": 2,
    "deletions": 2,
    "total": 4
  },
  "status": null,
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"
}
```

GitLab supports [form encoding](https://docs.gitlab.com/api/rest/#array-and-hash-types). The following is an example using Commit API with form encoding:
shell
```
curl --request POST \
     --form "branch=main" \
     --form "commit_message=some commit message" \
     --form "start_branch=main" \
     --form "actions[][action]=create" \
     --form "actions[][file_path]=foo/bar" \
     --form "actions[][content]=</path/to/local.file" \
     --form "actions[][action]=delete" \
     --form "actions[][file_path]=foo/bar2" \
     --form "actions[][action]=move" \
     --form "actions[][file_path]=foo/bar3" \
     --form "actions[][previous_path]=foo/bar4" \
     --form "actions[][content]=</path/to/local1.file" \
     --form "actions[][action]=update" \
     --form "actions[][file_path]=foo/bar5" \
     --form "actions[][content]=</path/to/local2.file" \
     --form "actions[][action]=chmod" \
     --form "actions[][file_path]=foo/bar5" \
     --form "actions[][execute_filemode]=true" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/1/repository/commits"
```

## Retrieve a commit[](https://docs.gitlab.com/api/commits/#retrieve-a-commit "Permalink")
Retrieves a specified commit identified by the commit hash or name of a branch or tag.
```
GET /projects/:id/repository/commits/:sha
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit hash or name of a repository branch or tag.
`stats` | boolean | No | Include commit stats. Default is `true`.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`author_email` | string | Email address of the commit author.
`author_name` | string | Name of the commit author.
`authored_date` | string | Date when the commit was authored.
`committed_date` | string | Date when the commit was committed.
`committer_email` | string | Email address of the commit committer.
`committer_name` | string | Name of the commit committer.
`created_at` | string | Date when the commit was created.
`id` | string | SHA of the commit.
`last_pipeline` | object | Information about the last pipeline for this commit.
`message` | string | Full commit message.
`parent_ids` | array | Array of parent commit SHAs.
`short_id` | string | Short SHA of the commit.
`stats` | object | Statistics about the commit (additions, deletions, total).
`status` | string | Status of the commit.
`title` | string | Title of the commit message.
`web_url` | string | Web URL of the commit.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main"
```

Example response:
json
```
{
  "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
  "short_id": "6104942438c",
  "title": "Sanitize for network graph",
  "author_name": "randx",
  "author_email": "user@example.com",
  "committer_name": "Dmitriy",
  "committer_email": "user@example.com",
  "created_at": "2021-09-20T09:06:12.300+03:00",
  "message": "Sanitize for network graph",
  "committed_date": "2021-09-20T09:06:12.300+03:00",
  "authored_date": "2021-09-20T09:06:12.420+03:00",
  "parent_ids": [
    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
  ],
  "last_pipeline": {
    "id": 8,
    "ref": "main",
    "sha": "2dc6aa325a317eda67812f05600bdf0fcdc70ab0",
    "status": "created"
  },
  "stats": {
    "additions": 15,
    "deletions": 10,
    "total": 25
  },
  "status": "running",
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/6104942438c14ec7bd21c6cd5bd995272b3faff6"
}
```

## List all references a commit is pushed to[](https://docs.gitlab.com/api/commits/#list-all-references-a-commit-is-pushed-to "Permalink")
Lists all references (from branches or tags) a commit is pushed to. The pagination parameters `page` and `per_page` can be used to restrict the list of references.
```
GET /projects/:id/repository/commits/:sha/refs
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit hash.
`type` | string | No | The scope of commits. Possible values `branch`, `tag`, `all`. Default is `all`.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`name` | string | Name of the branch or tag.
`type` | string | Type of reference (`branch` or `tag`).
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all"
```

Example response:
json
```
[
  {
    "type": "branch",
    "name": "'test'"
  },
  {
    "type": "branch",
    "name": "add-balsamiq-file"
  },
  {
    "type": "branch",
    "name": "wip"
  },
  {
    "type": "tag",
    "name": "v1.1.0"
  }
]
```

## Get commit sequence[](https://docs.gitlab.com/api/commits/#get-commit-sequence "Permalink")
History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/438151) in GitLab 16.9.


Get the sequence number of a commit in a project by following the parent links from the given commit.
This API provides essentially the same features as the `git rev-list --count` command for a given commit SHA.
```
GET /projects/:id/repository/commits/:sha/sequence
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit hash.
`first_parent` | boolean | No | If `true`, follows only the first parent commit upon seeing a merge commit.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`count` | integer | Sequence number of the commit.
Example request:
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/sequence"
```

Example response:
json
```
{
  "count": 632
}
```

## Cherry-pick a commit[](https://docs.gitlab.com/api/commits/#cherry-pick-a-commit "Permalink")
Cherry-picks a commit to a given branch.
```
POST /projects/:id/repository/commits/:sha/cherry_pick
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`branch` | string | Yes | The name of the branch.
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit hash.
`dry_run` | boolean | No | If `true`, does not commit any changes. Default is `false`.
`message` | string | No | A custom commit message to use for the new commit.
If successful, returns [`201 Created`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`author_email` | string | Email address of the original commit author.
`author_name` | string | Name of the original commit author.
`authored_date` | string | Date when the original commit was authored.
`committed_date` | string | Date when the cherry-picked commit was committed.
`committer_email` | string | Email address of the cherry-pick committer.
`committer_name` | string | Name of the cherry-pick committer.
`created_at` | string | Date when the cherry-picked commit was created.
`id` | string | SHA of the cherry-picked commit.
`message` | string | Full commit message.
`parent_ids` | array | Array of parent commit SHAs.
`short_id` | string | Short SHA of the cherry-picked commit.
`title` | string | Title of the commit message.
`web_url` | string | Web URL of the cherry-picked commit.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "branch=main" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/cherry_pick"
```

Example response:
json
```
{
  "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad",
  "short_id": "8b090c1b",
  "author_name": "Example User",
  "author_email": "user@example.com",
  "authored_date": "2016-12-12T20:10:39.000+01:00",
  "created_at": "2016-12-12T20:10:39.000+01:00",
  "committer_name": "Administrator",
  "committer_email": "admin@example.com",
  "committed_date": "2016-12-12T20:10:39.000+01:00",
  "title": "Feature added",
  "message": "Feature added\n\nSigned-off-by: Example User <user@example.com>\n",
  "parent_ids": [
    "a738f717824ff53aebad8b090c1b79a14f2bd9e8"
  ],
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/8b090c1b79a14f2bd9e8a738f717824ff53aebad"
}
```

In the event of a failed cherry-pick, the response provides context about why:
json
```
{
  "message": "Sorry, we cannot cherry-pick this commit automatically. This commit may already have been cherry-picked, or a more recent commit may have updated some of its content.",
  "error_code": "empty"
}
```

In this case, the cherry-pick failed because the changeset was empty and likely indicates that the commit already exists in the target branch. The other possible error code is `conflict`, which indicates that there was a merge conflict.
When `dry_run` is enabled, the server attempts to apply the cherry-pick _but not actually commit any resulting changes_. If the cherry-pick applies cleanly, the API responds with `200 OK`:
json
```
{
  "dry_run": "success"
}
```

In the event of a failure, an error displays that is identical to a failure without dry run.
## Revert a commit[](https://docs.gitlab.com/api/commits/#revert-a-commit "Permalink")
Reverts a commit in a given branch.
```
POST /projects/:id/repository/commits/:sha/revert
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`branch` | string | Yes | Target branch name.
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | Commit SHA to revert.
`dry_run` | boolean | No | If `true`, does not commit any changes. Default is `false`.
If successful, returns [`201 Created`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`author_email` | string | Email address of the revert commit author.
`author_name` | string | Name of the revert commit author.
`authored_date` | string | Date when the revert commit was authored.
`committed_date` | string | Date when the revert commit was committed.
`committer_email` | string | Email address of the revert commit committer.
`committer_name` | string | Name of the revert commit committer.
`created_at` | string | Date when the revert commit was created.
`id` | string | SHA of the revert commit.
`message` | string | Full revert commit message.
`parent_ids` | array | Array of parent commit SHAs.
`short_id` | string | Short SHA of the revert commit.
`title` | string | Title of the revert commit message.
`web_url` | string | Web URL of the revert commit.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "branch=main" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert"
```

Example response:
json
```
{
  "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad",
  "short_id": "8b090c1b",
  "title": "Revert \"Feature added\"",
  "created_at": "2018-11-08T15:55:26.000Z",
  "parent_ids": [
    "a738f717824ff53aebad8b090c1b79a14f2bd9e8"
  ],
  "message": "Revert \"Feature added\"\n\nThis reverts commit a738f717824ff53aebad8b090c1b79a14f2bd9e8",
  "author_name": "Administrator",
  "author_email": "admin@example.com",
  "authored_date": "2018-11-08T15:55:26.000Z",
  "committer_name": "Administrator",
  "committer_email": "admin@example.com",
  "committed_date": "2018-11-08T15:55:26.000Z",
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/8b090c1b79a14f2bd9e8a738f717824ff53aebad"
}
```

In the event of a failed revert, the response provides context about why:
json
```
{
  "message": "Sorry, we cannot revert this commit automatically. This commit may already have been reverted, or a more recent commit may have updated some of its content.",
  "error_code": "conflict"
}
```

In this case, the revert failed because the attempted revert generated a merge conflict. The other possible error code is `empty`, which indicates that the changeset was empty, likely due to the change having already been reverted.
When `dry_run` is enabled, the server attempts to apply the revert _but not actually commit any resulting changes_. If the revert applies cleanly, the API responds with `200 OK`:
json
```
{
  "dry_run": "success"
}
```

In the event of a failure, an error displays that is identical to a failure without dry run.
## Retrieve commit diff[](https://docs.gitlab.com/api/commits/#retrieve-commit-diff "Permalink")
History
  * `collapsed` and `too_large` response attributes [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/199633) in GitLab 18.4.


Retrieves the diff of a commit in a project.
```
GET /projects/:id/repository/commits/:sha/diff
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit hash or name of a repository branch or tag.
`unidiff` | boolean | No | If `true`, presents diffs in the [unified diff](https://www.gnu.org/software/diffutils/manual/html_node/Detailed-Unified.html) format. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/130610) in GitLab 16.5.
This endpoint is subject to [diff limits](https://docs.gitlab.com/administration/diff_limits/). When a commit exceeds the configured maximum number of files, pagination stops and no additional files are returned beyond the limit. For GitLab.com specific limits, see [diff display limits](https://docs.gitlab.com/user/gitlab_com/#diff-display-limits).
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`a_mode` | string | Old file mode of the file.
`b_mode` | string | New file mode of the file.
`collapsed` | boolean | File diffs are excluded but can be fetched on request.
`deleted_file` | boolean | File has been removed.
`diff` | string | Diff representation of the changes made to the file.
`new_file` | boolean | File has been added.
`new_path` | string | New path of the file.
`old_path` | string | Old path of the file.
`renamed_file` | boolean | File has been renamed.
`too_large` | boolean | File diffs are excluded and cannot be retrieved.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/diff"
```

Example response:
json
```
[
  {
    "diff": "@@ -71,6 +71,8 @@\n sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production\n sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production\n \n+sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production\n+\n ```\n \n ### 6. Update config files",
    "collapsed": false,
    "too_large": false,
    "new_path": "doc/update/5.4-to-6.0.md",
    "old_path": "doc/update/5.4-to-6.0.md",
    "a_mode": null,
    "b_mode": "100644",
    "new_file": false,
    "renamed_file": false,
    "deleted_file": false
  }
]
```

## List all commit comments[](https://docs.gitlab.com/api/commits/#list-all-commit-comments "Permalink")
Lists all the comments of a commit in a project.
```
GET /projects/:id/repository/commits/:sha/comments
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit hash or name of a repository branch or tag.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`author` | object | Information about the comment author.
`note` | string | The comment text.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/comments"
```

Example response:
json
```
[
  {
    "note": "this code is really nice",
    "author": {
      "id": 11,
      "username": "admin",
      "email": "admin@local.host",
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
    }
  }
]
```

## Post comment to commit[](https://docs.gitlab.com/api/commits/#post-comment-to-commit "Permalink")
Creates a comment on a commit.
To post a comment in a particular line of a particular file, you must specify the full commit SHA, the `path`, the `line`, and `line_type` should be `new`.
The comment is added at the end of the last commit if at least one of the following cases is valid:
  * the `sha` is instead a branch or a tag and the `line` or `path` are invalid
  * the `line` number is invalid (does not exist)
  * the `path` is invalid (does not exist)


In any of the previous cases, the response of `line`, `line_type` and `path` is set to `null`.
For other approaches to commenting on a merge request, see [Create a merge request note](https://docs.gitlab.com/api/notes/#create-a-merge-request-note) in the Notes API, and [Create a new thread in the merge request diff](https://docs.gitlab.com/api/discussions/#create-a-new-thread-in-the-merge-request-diff) in the Discussions API.
```
POST /projects/:id/repository/commits/:sha/comments
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`note` | string | Yes | The text of the comment.
`sha` | string | Yes | The commit SHA or name of a repository branch or tag.
`line` | integer | No | The line number where the comment should be placed.
`line_type` | string | No | The line type. Takes `new` or `old` as arguments.
`path` | string | No | The file path relative to the repository.
If successful, returns [`201 Created`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`author` | object | Information about the comment author.
`created_at` | string | Date when the comment was created.
`line_type` | string | Type of line the comment is on.
`line` | integer | Line number where the comment is placed.
`note` | string | The comment text.
`path` | string | File path relative to the repository.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "note=Nice picture\!" \
  --form "path=README.md" \
  --form "line=11" \
  --form "line_type=new" \
  --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments"
```

Example response:
json
```
{
  "author": {
    "web_url": "https://gitlab.example.com/janedoe",
    "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
    "username": "janedoe",
    "state": "active",
    "name": "Jane Doe",
    "id": 28
  },
  "created_at": "2016-01-19T09:44:55.600Z",
  "line_type": "new",
  "path": "README.md",
  "line": 11,
  "note": "Nice picture!"
}
```

## List all commit discussions[](https://docs.gitlab.com/api/commits/#list-all-commit-discussions "Permalink")
Lists all the discussions of a commit in a project.
```
GET /projects/:id/repository/commits/:sha/discussions
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit hash or name of a repository branch or tag.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`id` | string | ID of the discussion.
`individual_note` | boolean | If `true`, the discussion is an individual note.
`notes` | array | Array of notes in the discussion.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/4604744a1c64de00ff62e1e8a6766919923d2b41/discussions"
```

Example response:
json
```
[
  {
    "id": "4604744a1c64de00ff62e1e8a6766919923d2b41",
    "individual_note": true,
    "notes": [
      {
        "id": 334686748,
        "type": null,
        "body": "Nice piece of code!",
        "attachment": null,
        "author": {
          "id": 28,
          "name": "Jane Doe",
          "username": "janedoe",
          "web_url": "https://gitlab.example.com/janedoe",
          "state": "active",
          "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png"
        },
        "created_at": "2020-04-30T18:48:11.432Z",
        "updated_at": "2020-04-30T18:48:11.432Z",
        "system": false,
        "noteable_id": null,
        "noteable_type": "Commit",
        "resolvable": false,
        "confidential": null,
        "noteable_iid": null,
        "commands_changes": {}
      }
    ]
  }
]
```

## Commit status[](https://docs.gitlab.com/api/commits/#commit-status "Permalink")
The commit status API for use with GitLab.
### List commit statuses[](https://docs.gitlab.com/api/commits/#list-commit-statuses "Permalink")
History
  * `pipeline_id`, `order_by`, and `sort` fields [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/176142) in GitLab 17.9.


List the statuses of a commit in a project. The pagination parameters `page` and `per_page` can be used to restrict the list of references.
```
GET /projects/:id/repository/commits/:sha/statuses
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | Hash of the commit.
`all` | boolean | No | If `true`, include all statuses instead of latest only. Default is `false`.
`name` | string | No | Filter statuses by [job name](https://docs.gitlab.com/ci/yaml/#job-keywords). For example, `bundler:audit`.
`order_by` | string | No | Values for sorting statuses. Valid values are `id` and `pipeline_id`. Default is `id`.
`pipeline_id` | integer | No | Filter statuses by pipeline ID. For example, `1234`.
`ref` | string | No | Name of the branch or tag. Default is the default branch.
`sort` | string | No | Sort statuses in ascending or descending order. Valid values are `asc` and `desc`. Default is `asc`.
`stage` | string | No | Filter statuses by [build stage](https://docs.gitlab.com/ci/yaml/#stages). For example, `test`.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`allow_failure` | boolean | If `true`, the status allows failure.
`author` | object | Information about the status author.
`created_at` | string | Date when the status was created.
`description` | string | Description of the status.
`finished_at` | string | Date when the status was finished.
`id` | integer | ID of the status.
`name` | string | Name of the status.
`ref` | string | Reference (branch or tag) of the commit.
`sha` | string | SHA of the commit.
`started_at` | string | Date when the status was started.
`status` | string | Status of the commit.
`target_url` | string | Target URL associated with the status.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses"
```

Example response:
json
```
[
  ...
  {
    "status": "pending",
    "created_at": "2016-01-19T08:40:25.934Z",
    "started_at": null,
    "name": "bundler:audit",
    "allow_failure": true,
    "author": {
      "username": "janedoe",
      "state": "active",
      "web_url": "https://gitlab.example.com/janedoe",
      "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
      "id": 28,
      "name": "Jane Doe"
    },
    "description": null,
    "sha": "18f3e63d05582537db6d183d9d557be09e1f90c8",
    "target_url": "https://gitlab.example.com/janedoe/gitlab-foss/builds/91",
    "finished_at": null,
    "id": 91,
    "ref": "main"
  },
  {
    "started_at": null,
    "name": "test",
    "allow_failure": false,
    "status": "pending",
    "created_at": "2016-01-19T08:40:25.832Z",
    "target_url": "https://gitlab.example.com/janedoe/gitlab-foss/builds/90",
    "id": 90,
    "finished_at": null,
    "ref": "main",
    "sha": "18f3e63d05582537db6d183d9d557be09e1f90c8",
    "author": {
      "id": 28,
      "name": "Jane Doe",
      "username": "janedoe",
      "web_url": "https://gitlab.example.com/janedoe",
      "state": "active",
      "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png"
    },
    "description": null
  }
  ...
]
```

### Set commit pipeline status[](https://docs.gitlab.com/api/commits/#set-commit-pipeline-status "Permalink")
Add or update the status of a commit represented by a job in an `external` stage. If the commit is associated with a merge request, target the commit in the merge request’s source branch.
When you set a commit status:
  * Existing pipelines are searched first to append the job to.
  * If no suitable pipeline exists, a new pipeline is created with `CI_PIPELINE_SOURCE: external`.


For more information, see [external commit statuses](https://docs.gitlab.com/ci/ci_cd_for_external_repos/external_commit_statuses/).
When duplicate pipelines exist for the same commit, it can be ambiguous which pipeline receives the external status. Configure your pipeline to [avoid duplicates](https://docs.gitlab.com/ci/jobs/job_rules/#avoid-duplicate-pipelines).
If a pipeline already exists and it exceeds the [maximum number of jobs in a single pipeline limit](https://docs.gitlab.com/administration/instance_limits/#maximum-number-of-jobs-in-a-pipeline):
  * If `pipeline_id` is specified, a `422` error is returned: `The number of jobs has exceeded the limit`.
  * Otherwise, a new pipeline is created.


If an update is already in progress for a SHA/ref combination, a `409` error is returned. To handle this error, retry the request.
```
POST /projects/:id/statuses/:sha
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit SHA.
`state` | string | Yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled`, `skipped`.
`coverage` | float | No | The total code coverage.
`description` | string | No | The short description of the status. Must be 255 characters or fewer.
`name` or `context` | string | No | The label to differentiate this status from the status of other systems. Default value is `default`.
`pipeline_id` | integer | No | The ID of the pipeline to set status. Use in case of several pipeline on same SHA.
`ref` | string | No | The `ref` (branch or tag) to which the status refers. Must be 255 characters or fewer.
`target_url` | string | No | The target URL to associate with this status. Must be 255 characters or fewer.
If successful, returns [`201 Created`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`allow_failure` | boolean | If `true`, the status allows failure.
`author` | object | Information about the status author.
`coverage` | float | Code coverage percentage.
`created_at` | string | Date when the status was created.
`description` | string | Description of the status.
`finished_at` | string | Date when the status was finished.
`id` | integer | ID of the status.
`name` | string | Name of the status.
`ref` | string | Reference (branch or tag) of the commit.
`sha` | string | SHA of the commit.
`started_at` | string | Date when the status was started.
`status` | string | Status of the commit.
`target_url` | string | Target URL associated with the status.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"
```

Example response:
json
```
{
  "author": {
    "web_url": "https://gitlab.example.com/janedoe",
    "name": "Jane Doe",
    "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
    "username": "janedoe",
    "state": "active",
    "id": 28
  },
  "name": "default",
  "sha": "18f3e63d05582537db6d183d9d557be09e1f90c8",
  "status": "success",
  "coverage": 100.0,
  "description": null,
  "id": 93,
  "target_url": null,
  "ref": null,
  "started_at": null,
  "created_at": "2016-01-19T09:05:50.355Z",
  "allow_failure": false,
  "finished_at": "2016-01-19T09:05:50.365Z"
}
```

## List merge requests associated with a commit[](https://docs.gitlab.com/api/commits/#list-merge-requests-associated-with-a-commit "Permalink")
History
  * `state` attribute [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/191169) in GitLab 18.2.


Returns information about the merge request that originally introduced a specific commit.
```
GET /projects/:id/repository/commits/:sha/merge_requests
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit SHA.
`state` | string | No | Returns merge requests with the specified state: `opened`, `closed`, `locked`, or `merged`. Omit this parameter to get all merge requests regardless of state.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`assignee` | object | Information about the merge request assignee.
`author` | object | Information about the merge request author.
`created_at` | string | Date when the merge request was created.
`description` | string | Description of the merge request.
`discussion_locked` | boolean | If `true`, discussions are locked.
`downvotes` | integer | Number of downvotes.
`draft` | boolean | If `true`, the merge request is a draft.
`force_remove_source_branch` | boolean | If `true`, forces source branch removal.
`id` | integer | ID of the merge request.
`iid` | integer | Internal ID of the merge request.
`labels` | array | Labels associated with the merge request.
`merge_commit_sha` | string | SHA of the merge commit.
`merge_status` | string | Merge status of the merge request.
`merge_when_pipeline_succeeds` | boolean | If `true`, merges when pipeline succeeds.
`milestone` | object | Milestone associated with the merge request.
`project_id` | integer | ID of the project.
`sha` | string | SHA of the merge request.
`should_remove_source_branch` | boolean | If `true`, removes source branch after merge.
`source_branch` | string | Source branch of the merge request.
`source_project_id` | integer | ID of the source project.
`squash_commit_sha` | string | SHA of the squash commit.
`state` | string | State of the merge request.
`target_branch` | string | Target branch of the merge request.
`target_project_id` | integer | ID of the target project.
`time_stats` | object | Time tracking statistics.
`title` | string | Title of the merge request.
`updated_at` | string | Date when the merge request was last updated.
`upvotes` | integer | Number of upvotes.
`user_notes_count` | integer | Number of user notes.
`web_url` | string | Web URL of the merge request.
`work_in_progress` | boolean | If `true`, the merge request is set as work in progress.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests?state=opened"
```

Example response:
json
```
[
  {
    "id": 45,
    "iid": 1,
    "project_id": 35,
    "title": "Add new file",
    "description": "",
    "state": "opened",
    "created_at": "2018-03-26T17:26:30.916Z",
    "updated_at": "2018-03-26T17:26:30.916Z",
    "target_branch": "main",
    "source_branch": "test-branch",
    "upvotes": 0,
    "downvotes": 0,
    "author": {
      "web_url": "https://gitlab.example.com/janedoe",
      "name": "Jane Doe",
      "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
      "username": "janedoe",
      "state": "active",
      "id": 28
    },
    "assignee": null,
    "source_project_id": 35,
    "target_project_id": 35,
    "labels": [],
    "draft": false,
    "work_in_progress": false,
    "milestone": null,
    "merge_when_pipeline_succeeds": false,
    "merge_status": "can_be_merged",
    "sha": "af5b13261899fb2c0db30abdd0af8b07cb44fdc5",
    "merge_commit_sha": null,
    "squash_commit_sha": null,
    "user_notes_count": 0,
    "discussion_locked": null,
    "should_remove_source_branch": null,
    "force_remove_source_branch": false,
    "web_url": "https://gitlab.example.com/root/test-project/merge_requests/1",
    "time_stats": {
      "time_estimate": 0,
      "total_time_spent": 0,
      "human_time_estimate": null,
      "human_total_time_spent": null
    }
  }
]
```

## Retrieve commit signature[](https://docs.gitlab.com/api/commits/#retrieve-commit-signature "Permalink")
Retrieves the [signature from a commit](https://docs.gitlab.com/user/project/repository/signed_commits/), if it is signed. For unsigned commits, it results in a 404 response.
```
GET /projects/:id/repository/commits/:sha/signature
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
`sha` | string | Yes | The commit hash or name of a repository branch or tag.
If successful, returns [`200 OK`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) and the following response attributes:
Attribute | Type | Description
---|---|---
`commit_source` | string | Source of the commit.
`gpg_key_id` | integer | ID of the GPG key (for PGP signatures).
`gpg_key_primary_keyid` | string | Primary key ID of the GPG key.
`gpg_key_subkey_id` | string | Subkey ID of the GPG key.
`gpg_key_user_email` | string | Email address associated with the GPG key.
`gpg_key_user_name` | string | User name associated with the GPG key.
`key` | object | SSH key information (for SSH signatures).
`signature_type` | string | Type of signature (`PGP`, `SSH`, or `X509`).
`verification_status` | string | Verification status of the signature.
`x509_certificate` | object | X.509 certificate information (for X.509 signatures).
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/repository/commits/da738facbc19eb2fc2cef57c49be0e6038570352/signature"
```

Example response if commit is GPG signed:
json
```
{
  "signature_type": "PGP",
  "verification_status": "verified",
  "gpg_key_id": 1,
  "gpg_key_primary_keyid": "8254AAB3FBD54AC9",
  "gpg_key_user_name": "John Doe",
  "gpg_key_user_email": "johndoe@example.com",
  "gpg_key_subkey_id": null,
  "commit_source": "gitaly"
}
```

Example response if commit is signed with SSH:
json
```
{
  "signature_type": "SSH",
  "verification_status": "verified",
  "key": {
    "id": 11,
    "title": "Key",
    "created_at": "2023-05-08T09:12:38.503Z",
    "expires_at": "2024-05-07T00:00:00.000Z",
    "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILZzYDq6DhLp3aX84DGIV3F6Vf+Ae4yCTTz7RnqMJOlR MyKey)",
    "usage_type": "auth_and_signing"
  },
  "commit_source": "gitaly"
}
```

Example response if commit is X.509 signed:
json
```
{
  "signature_type": "X509",
  "verification_status": "unverified",
  "x509_certificate": {
    "id": 1,
    "subject": "CN=gitlab@example.org,OU=Example,O=World",
    "subject_key_identifier": "BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC",
    "email": "gitlab@example.org",
    "serial_number": 278969561018901340486471282831158785578,
    "certificate_status": "good",
    "x509_issuer": {
      "id": 1,
      "subject": "CN=PKI,OU=Example,O=World",
      "subject_key_identifier": "AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB",
      "crl_url": "http://example.com/pki.crl"
    }
  },
  "commit_source": "gitaly"
}
```

Example response if commit is unsigned:
json
```
{
  "message": "404 GPG Signature Not Found"
}
```

Was this page helpful?YesNo
Edit this page
  *     * [ Open in Web IDE`.`Quickly and easily edit multiple files. ](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/commits.md)
    * [ View page sourceEdit this file only. ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/commits.md)
    * [ Create an issueSuggest improvements. ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


  * [Responses](https://docs.gitlab.com/api/commits/#responses)
  * [Pagination response headers](https://docs.gitlab.com/api/commits/#pagination-response-headers)
  * [List repository commits](https://docs.gitlab.com/api/commits/#list-repository-commits)
  * [Create a commit](https://docs.gitlab.com/api/commits/#create-a-commit)
  * [Retrieve a commit](https://docs.gitlab.com/api/commits/#retrieve-a-commit)
  * [List all references a commit is pushed to](https://docs.gitlab.com/api/commits/#list-all-references-a-commit-is-pushed-to)
  * [Get commit sequence](https://docs.gitlab.com/api/commits/#get-commit-sequence)
  * [Cherry-pick a commit](https://docs.gitlab.com/api/commits/#cherry-pick-a-commit)
  * [Revert a commit](https://docs.gitlab.com/api/commits/#revert-a-commit)
  * [Retrieve commit diff](https://docs.gitlab.com/api/commits/#retrieve-commit-diff)
  * [List all commit comments](https://docs.gitlab.com/api/commits/#list-all-commit-comments)
  * [Post comment to commit](https://docs.gitlab.com/api/commits/#post-comment-to-commit)
  * [List all commit discussions](https://docs.gitlab.com/api/commits/#list-all-commit-discussions)
  * [Commit status](https://docs.gitlab.com/api/commits/#commit-status)
  * [List commit statuses](https://docs.gitlab.com/api/commits/#list-commit-statuses)
  * [Set commit pipeline status](https://docs.gitlab.com/api/commits/#set-commit-pipeline-status)
  * [List merge requests associated with a commit](https://docs.gitlab.com/api/commits/#list-merge-requests-associated-with-a-commit)
  * [Retrieve commit signature](https://docs.gitlab.com/api/commits/#retrieve-commit-signature)


[![GitLab Docs logo](https://docs.gitlab.com/gitlab-logo-footer.svg)](https://docs.gitlab.com/)
  * [Facebook](https://www.facebook.com/gitlab)
  * [LinkedIn](https://www.linkedin.com/company/gitlab-com)
  * [Twitter](https://twitter.com/gitlab)
  * [YouTube](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg)

[![Creative Commons License](https://docs.gitlab.com/by-sa.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
Company
  * [About GitLab](https://about.gitlab.com/company/)
  * [View pricing](https://about.gitlab.com/pricing/)
  * [Try GitLab for free](https://about.gitlab.com/free-trial/)


Feedback
  * [View page source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/commits.md)
  * [Edit in Web IDE](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/commits.md)
  * [Contribute to GitLab](https://about.gitlab.com/community/contribute/)
  * [Suggest updates](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


Help & Community
  * [Get certified](https://university.gitlab.com/pages/certifications)
  * [Get support](https://about.gitlab.com/support/)
  * [Post on the GitLab forum](https://forum.gitlab.com/new-topic?title=topic%20title&body=topic%20body&tags=docs-feedback)


Resources
  * [Terms](https://about.gitlab.com/terms/)
  * [Privacy statement](https://about.gitlab.com/privacy/)
  * [Use of generative AI](https://docs.gitlab.com/legal/use_generative_ai/)
  * [Acceptable use of user licenses](https://docs.gitlab.com/legal/licensing_policy/)
  * Cookie Preferences


![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fcommits%2F&_biz_t=1772174230696&_biz_i=Commits%20API%20%7C%20GitLab%20Docs&_biz_n=25&rnd=816489&cdn_o=a&_biz_z=1772174230697)
![Company Logo](https://cdn.cookielaw.org/logos/aa14a5c8-79e3-442a-8177-464ad850b19d/e46c1d0d-1f66-481f-bc06-5427671431da/253e6fee-c4c0-4b60-bc35-79cdae5dda32/gitlab-logo-100.png)
## Privacy Preference Center
## Privacy Preference Center
  * ### Your Privacy
  * ### Strictly Necessary Cookies
  * ### Functionality Cookies
  * ### Performance and Analytics Cookies
  * ### Targeting and Advertising Cookies
  * ### Ad User Data
  * ### Ad Personalization


#### Your Privacy
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
[Cookie Policy](https://about.gitlab.com/privacy/cookies/)
**User ID:** 42fad8d5-ed56-4786-8d74-3c72635252d2
_This User ID will be used as a unique identifier while storing and accessing your preferences for future._
**Timestamp:** --
#### Strictly Necessary Cookies
Always Active
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, enabling you to securely log into the site, filling in forms, or using the customer checkout. GitLab processes any personal data collected through these cookies on the basis of our legitimate interest.
Cookies Details
#### Functionality Cookies
Functionality Cookies
These cookies enable helpful but non-essential website functions that improve your website experience. By recognizing you when you return to our website, they may, for example, allow us to personalize our content for you or remember your preferences. If you do not allow these cookies then some or all of these services may not function properly. GitLab processes any personal data collected through these cookies on the basis of your consent
Cookies Details
#### Performance and Analytics Cookies
Performance and Analytics Cookies
These cookies allow us and our third-party service providers to recognize and count the number of visitors on our websites and to see how visitors move around our websites when they are using it. This helps us improve our products and ensures that users can easily find what they need on our websites. These cookies usually generate aggregate statistics that are not associated with an individual. To the extent any personal data is collected through these cookies, GitLab processes that data on the basis of your consent.
Cookies Details
#### Targeting and Advertising Cookies
Targeting and Advertising Cookies
These cookies enable different advertising related functions. They may allow us to record information about your visit to our websites, such as pages visited, links followed, and videos viewed so we can make our websites and the advertising displayed on it more relevant to your interests. They may be set through our website by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant advertisements on other websites. GitLab processes any personal data collected through these cookies on the basis of your consent.
Cookies Details
#### Ad User Data
Ad User Data
Sets consent for sending user data to Google for advertising purposes.
Cookies Details
#### Ad Personalization
Ad Personalization
Sets consent for personalized advertising.
Cookies Details
Back Button
### Cookie List
Filter Button
Consent Leg.Interest
checkbox label label
checkbox label label
checkbox label label
Clear
  * checkbox label label


Apply Cancel
Confirm My Choices
Allow All
[![Powered by Onetrust](https://cdn.cookielaw.org/logos/static/powered_by_logo.svg)](https://www.onetrust.com/products/cookie-consent/)
