正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

コミットAPI

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、Gitコミットを管理します。

応答

このAPIからの応答に含まれる日付フィールドの一部で、情報が重複しているか、またはそのように見えることがあります:

  • created_atフィールドは、他のGitLab APIとの整合性だけを目的として存在しています。常にcommitted_dateフィールドと同一です。
  • committed_dateフィールドとauthored_dateフィールドは異なるソースから生成されるため、同一ではない場合があります。

ページネーションレスポンスヘッダー

パフォーマンス上の理由から、GitLabはコミットAPIのレスポンスで以下のヘッダーを返しません:

  • x-total
  • x-total-pages

詳細については、イシュー389582を参照してください。

リポジトリコミットをリストする

プロジェクト内のリポジトリコミットのリストを取得します。

GET /projects/:id/repository/commits
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
allブール値いいえリポジトリからすべてのコミットを取得します。trueの場合、ref_nameパラメータは無視されます。
author文字列いいえコミット作成者でコミットを検索します。
first_parentブール値いいえtrueの場合、マージコミットが確認されたら、最初の親コミットのみをフォローします。
order文字列いいえコミットを順にリストします。使用可能な値はdefault、topoです。デフォルトはdefaultで、コミットは逆時系列順に表示されます。
path文字列いいえファイルのパス。
ref_name文字列いいえリポジトリのブランチ、タグ、またはリビジョン範囲の名前。指定されていない場合はデフォルトのブランチの名前です。
since文字列いいえこの日付以降のコミットのみがISO 8601形式（YYYY-MM-DDTHH:MM:SSZ）で返されます。
trailersブール値いいえtrueの場合、すべてのコミットに対してGitトレーラーを解析し、含めます。
until文字列いいえこの日付以前のコミットのみがISO 8601形式（YYYY-MM-DDTHH:MM:SSZ）で返されます。
with_statsブール値いいえtrueの場合、各コミットに関する統計情報を取得します。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
author_email文字列コミットの作成者のメールアドレス。
author_name文字列コミットの作成者名。
authored_date文字列コミットが作成済みの日付。
committed_date文字列コミットがコミットされた日付。
committer_email文字列コミットのコミッターのメールアドレス。
committer_name文字列コミットのコミッター名。
created_at文字列コミットが作成された日付（committed_dateと同じ）。
extended_trailersオブジェクトすべての値を含む拡張Gitトレーラー。
id文字列コミットのハッシュ。
message文字列完全なコミットメッセージ。
parent_ids配列親コミットSHAの配列。
short_id文字列コミットの短いSHA。
title文字列コミットメッセージのタイトル。
trailersオブジェクトコミットメッセージから解析されたGitトレーラー。
web_url文字列コミットのWeb URL。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits"

レスポンス例:

[
  {
    "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>"
      ]
    }
  }
]

複数のファイルとアクションを含むコミットを作成する

JSONペイロードを送信することでコミットを作成します。

POST /projects/:id/repository/commits
属性型必須説明
actions[]配列はいバッチとしてコミットするアクションハッシュの配列。取れる属性については、次の表を参照してください。
branch文字列はいコミット先のブランチの名前。新しいブランチを作成するには、start_branchまたはstart_shaを指定します。また、オプションでstart_projectも指定できます。
commit_message文字列はいコミットメッセージ。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
author_email文字列いいえコミットの作成者のメールアドレスを指定します。
author_name文字列いいえコミットの作成者の名前を指定します。
forceブール値いいえtrueの場合、start_branchまたはstart_shaに基づく新しいコミットでターゲットブランチを上書きします。
start_branch文字列いいえ新しいブランチの開始元となるブランチの名前。
start_project整数または文字列いいえ新しいブランチの開始元となるプロジェクトのプロジェクトIDまたはURLエンコードされたパス。デフォルトはidの値です。
start_sha文字列いいえ新しいブランチの開始元となるコミットのSHA。
statsブール値いいえコミット統計を含めます。デフォルトはtrueです。
actions[]属性型必須説明
action文字列はい実行するアクション: create、delete、move、update、またはchmod。
file_path文字列はいファイルのフルパス。例: lib/class.rb。
content文字列いいえファイルの内容。delete、chmod、moveを除くすべての場合に必須です。移動アクションでcontentが指定されていない場合、既存のファイルコンテンツが保持されます。content以外の値の場合、ファイルの内容が上書きされます。
encoding文字列いいえtextまたはbase64。textがデフォルトです。
execute_filemodeブール値いいえtrueの場合、ファイルの実行フラグを有効にします。falseの場合、無効になります。chmodアクションの場合のみ考慮されます。
last_commit_id文字列いいえ既知の最新のファイルコミットID。update、move、およびdeleteアクションでのみ考慮されます。
previous_path文字列いいえ移動されるファイルの元のフルパス。例: lib/class1.rb。moveアクションの場合のみ考慮されます。

成功した場合は、201 Createdと以下のレスポンス属性が返されます:

属性型説明
author_email文字列コミットの作成者のメールアドレス。
author_name文字列コミットの作成者名。
authored_date文字列コミットが作成済みの日付。
committed_date文字列コミットがコミットされた日付。
committer_email文字列コミットのコミッターのメールアドレス。
committer_name文字列コミットのコミッター名。
created_at文字列コミットが作成された日付。
id文字列作成されたコミットのSHA。
message文字列完全なコミットメッセージ。
parent_ids配列親コミットSHAの配列。
short_id文字列作成されたコミットの短いSHA。
statsオブジェクトコミットに関する統計（追加、削除、合計）。
status文字列コミットの状態。
title文字列コミットメッセージのタイトル。
web_url文字列コミットのWeb URL。
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"

レスポンス例:

{
  "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はフォームエンコードをサポートしています。次に、フォームエンコードでCommits APIを使用する例を示します:

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"

1つのコミットを取得する

ブランチまたはタグのコミットハッシュまたは名前で識別される特定のコミットを取得します。

GET /projects/:id/repository/commits/:sha

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいリポジトリのブランチまたはタグのコミットハッシュまたは名前。
statsブール値いいえコミット統計を含めます。デフォルトはtrueです。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
author_email文字列コミットの作成者のメールアドレス。
author_name文字列コミットの作成者名。
authored_date文字列コミットが作成済みの日付。
committed_date文字列コミットがコミットされた日付。
committer_email文字列コミットのコミッターのメールアドレス。
committer_name文字列コミットのコミッター名。
created_at文字列コミットが作成された日付。
id文字列コミットのハッシュ。
last_pipelineオブジェクトこのコミットの最後のパイプラインに関する情報。
message文字列完全なコミットメッセージ。
parent_ids配列親コミットSHAの配列。
short_id文字列コミットの短いSHA。
statsオブジェクトコミットに関する統計（追加、削除、合計）。
status文字列コミットの状態。
title文字列コミットメッセージのタイトル。
web_url文字列コミットのWeb URL。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main"

レスポンス例:

{
  "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"
}

コミットのプッシュ先の参照を取得する

コミットのプッシュ先の参照をすべて（ブランチまたはタグから）を取得します。ページネーションパラメータpageとper_pageを使用して、参照のリストを制限できます。

GET /projects/:id/repository/commits/:sha/refs

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいコミットハッシュ。
type文字列いいえコミットのスコープ。使用可能な値はbranch、tag、allです。デフォルトはallです。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
name文字列ブランチまたはタグの名前。
type文字列参照のタイプ（branchまたはtag）。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all"

レスポンス例:

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

コミット順列を取得

指定されたコミットから親リンクをたどって、プロジェクト内のコミットのシーケンス番号を取得します。

このAPIは、特定のコミットSHAに対するgit rev-list --countコマンドと基本的に同じ機能を提供します。

GET /projects/:id/repository/commits/:sha/sequence

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいコミットハッシュ。
first_parentブール値いいえtrueの場合、マージコミットが確認されたら、最初の親コミットのみをフォローします。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
count整数コミットの順列に番号。

リクエスト例:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/sequence"

レスポンス例:

{
  "count": 632
}

コミットをチェリーピックする

指定されたブランチにコミットをチェリーピックします。

POST /projects/:id/repository/commits/:sha/cherry_pick

パラメータは以下のとおりです:

属性型必須説明
branch文字列はいブランチの名前
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいコミットハッシュ。
dry_runブール値いいえtrueの場合、変更をコミットしません。デフォルトはfalseです。
message文字列いいえ新しいコミットに使用するカスタムコミットメッセージ。

成功した場合は、201 Createdと以下のレスポンス属性が返されます:

属性型説明
author_email文字列元のコミットの作成者のメールアドレス。
author_name文字列元のコミットの作成者名。
authored_date文字列元のコミットが作成済みの日付。
committed_date文字列チェリーピックされたコミットがコミットされた日付。
committer_email文字列チェリーピックコミッターのメールアドレス。
committer_name文字列チェリーピックコミッター名。
created_at文字列チェリーピックされたコミットが作成された日付。
id文字列チェリーピックされたコミットのSHA。
message文字列完全なコミットメッセージ。
parent_ids配列親コミットSHAの配列。
short_id文字列チェリーピックされたコミットの短いSHA。
title文字列コミットメッセージのタイトル。
web_url文字列チェリーピックされたコミットのWeb URL。
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"

レスポンス例:

{
  "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"
}

チェリーピックが失敗した場合、応答はその理由に関するコンテキストを提供します:

{
  "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"
}

ここでは、チェンジセットが空であるためにチェリーピックが失敗しています。そして、コミットがターゲットブランチにすでに存在する可能性を示しています。エラーコードとして返される可能性があるもう1つのものはconflictです。これはマージコンフリクトが発生していたことを示します。

dry_runが有効になっている場合、サーバーはチェリーピックの適用を試みます_が、実際には結果の変更をコミットしません_。チェリーピックが正常に適用されると、APIは200 OKで応答します:

{
  "dry_run": "success"
}

失敗した場合、ドライランなしの失敗と同じエラーが表示されます。

コミットをリバートする

指定されたブランチのコミットをリバートします。

POST /projects/:id/repository/commits/:sha/revert

パラメータは以下のとおりです:

属性型必須説明
branch文字列はいターゲットブランチ名。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいリバートするコミットSHA。
dry_runブール値いいえtrueの場合、変更をコミットしません。デフォルトはfalseです。

成功した場合は、201 Createdと以下のレスポンス属性が返されます:

属性型説明
author_email文字列リバートコミットの作成者のメールアドレス。
author_name文字列リバートコミットの作成者名。
authored_date文字列リバートコミットが作成済みの日付。
committed_date文字列リバートコミットがコミットされた日付。
committer_email文字列リバートコミットのコミッターのメールアドレス。
committer_name文字列リバートコミットのコミッター名。
created_at文字列リバートコミットが作成された日付。
id文字列リバートコミットのSHA。
message文字列完全なリバートコミットメッセージ。
parent_ids配列親コミットSHAの配列。
short_id文字列リバートコミットの短いSHA。
title文字列リバートコミットメッセージのタイトル。
web_url文字列リバートコミットのWeb URL。
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"

レスポンス例:

{
  "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"
}

リバートが失敗した場合、応答はその理由に関するコンテキストを提供します:

{
  "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"
}

上記の例では、試行されたリバートによってマージコンフリクトが発生したためにリバートが失敗しました。返される可能性があるもう1つのエラーコードはemptyです。これは、変更がすでにリバートされているために、チェンジセットが空であることを示しています。

dry_runが有効になっている場合、サーバーはリバートの適用を試みますが、実際には結果の変更をコミットしません。リバートが正常に適用されると、APIは200 OKで応答します:

{
  "dry_run": "success"
}

失敗した場合、ドライランなしの失敗と同じエラーが表示されます。

コミットの差分を取得

プロジェクト内のコミットの差分を取得します。

GET /projects/:id/repository/commits/:sha/diff

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいリポジトリのブランチまたはタグのコミットハッシュまたは名前。
unidiffブール値いいえtrueの場合、unified diff形式で差分を表示します。デフォルトはfalseです。GitLab 16.5で導入されました。

このエンドポイントには、差分の制限が適用されます。コミットが構成された最大ファイル数を超えると、ページネーションが停止し、制限を超えて追加のファイルが返されなくなります。GitLab.com固有の制限については、差分の表示制限を参照してください。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
a_mode文字列変更前のファイルモード。
b_mode文字列変更後のファイルモード。
deleted_fileブール値trueの場合、ファイルは削除されています。
diff文字列差分の内容。
new_fileブール値trueの場合、これは新しいファイルです。
new_path文字列ファイルの新しいパス。
old_path文字列ファイルの古いパス。
renamed_fileブール値trueの場合、ファイルの名前が変更されています。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/diff"

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
a_mode文字列ファイルの古いファイルモード。
b_mode文字列ファイルの新しいファイルモード。
collapsedブール値ファイルの差分は除外されていますが、リクエストに応じてフェッチできます。
deleted_fileブール値ファイルは削除されました。
diff文字列ファイルに加えられた変更の差分の表現。
new_fileブール値ファイルが追加されました。
new_path文字列ファイルの新しいパス。
old_path文字列ファイルの古いパス。
renamed_fileブール値ファイルの名前が変更されました。
too_largeブール値ファイルの差分は除外され、取得できません。

レスポンス例:

[
  {
    "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
  }
]

コミットコメントを取得

プロジェクト内のコミットのコメントを取得します。

GET /projects/:id/repository/commits/:sha/comments

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいリポジトリのブランチまたはタグのコミットハッシュまたは名前。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
authorオブジェクトコメント作成者に関する情報。
note文字列コメントのテキスト。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/comments"

レスポンス例:

[
  {
    "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"
    }
  }
]

コミットにコメントを投稿する

コミットにコメントを追加します。

特定のファイルの特定の行にコメントを投稿するには、完全なコミットSHA、path、lineを指定する必要があり、line_typeはnewである必要があります。

以下の1つ以上のケースに該当する場合、コメントは最終コミットの終わりに追加されます:

  • ブランチまたはタグの代わりにshaがあり、lineまたはpathが無効である。
  • line番号が無効である（存在しない）。
  • pathが無効である（存在しない）。

上記のいずれの場合も、line、line_type、pathの応答はnullに設定されます。

マージリクエストへコメントするその他の方法については、Notes APIの新しいマージリクエストノートを作成する 、およびDiscussions APIのマージリクエスト差分に新しいスレッドを作成するを参照してください。

POST /projects/:id/repository/commits/:sha/comments
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
note文字列はいコメントのテキスト。
sha文字列はいリポジトリのブランチまたはタグのコミットSHAまたは名前。
line整数いいえコメントを配置する行の番号。
line_type文字列いいえ行のタイプ。引数としてnewまたはoldを取ります。
path文字列いいえリポジトリを基準とした相対的なパス。

成功した場合は、201 Createdと以下のレスポンス属性が返されます:

属性型説明
authorオブジェクトコメント作成者に関する情報。
created_at文字列コメントが作成された日付。
line_type文字列コメントがある行のタイプ。
line整数コメントが配置されている行番号。
note文字列コメントのテキスト。
path文字列リポジトリを基準とした相対的なパス。
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"

レスポンス例:

{
  "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!"
}

コミットディスカッションを取得

プロジェクト内のコミットのディスカッションを取得します。

GET /projects/:id/repository/commits/:sha/discussions

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいリポジトリのブランチまたはタグのコミットハッシュまたは名前。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
id文字列ディスカッションのID。
individual_noteブール値trueの場合、ディスカッションは個別のノートです。
notes配列ディスカッション内のノートの配列。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/4604744a1c64de00ff62e1e8a6766919923d2b41/discussions"

レスポンス例:

[
  {
    "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": {}
      }
    ]
  }
]

コミットステータス

GitLabで使用するコミットステータスAPIです。

コミットステータスを一覧表示

プロジェクト内のコミットのステータスをリストします。ページネーションパラメータpageとper_pageを使用して、参照のリストを制限できます。

GET /projects/:id/repository/commits/:sha/statuses
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいコミットのハッシュ。
allブール値いいえtrueの場合、最新のステータスだけでなく、すべてのステータスを含めます。デフォルトはfalseです。
name文字列いいえジョブ名でステータスをフィルタリングします。たとえばbundler:auditなどです。
order_by文字列いいえステータスをソートするための値。有効な値はidとpipeline_idです。デフォルトはidです。
pipeline_id整数いいえパイプラインIDでステータスをフィルタリングします。たとえば1234などです。
ref文字列いいえブランチまたはタグの名前。デフォルトはブランチです。
sort文字列いいえステータスを昇順または降順でソートします。有効な値はascとdescです。デフォルトはascです。
stage文字列いいえBuildステージでステータスをフィルタリングします。たとえばtestなどです。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
allow_failureブール値trueの場合、ステータスは失敗を許可します。
authorオブジェクトステータス作成者に関する情報。
created_at文字列ステータスが作成された日付。
description文字列スキャンの説明。
finished_at文字列ステータスが完了した日付。
id整数ステータスのID。
name文字列ステータスの名前。
ref文字列コミットの参照（ブランチまたはタグ）。
sha文字列コミットのハッシュ。
started_at文字列ステータスが開始された日付。
status文字列コミットの状態。
target_url文字列ステータスに関連付けられているターゲットURL。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses"

レスポンス例:

[
  ...
  {
    "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
  }
  ...
]

コミットパイプラインステータスを設定

externalステージングのジョブによって表されるコミットのステータスを追加または更新します。コミットがマージリクエストに関連付けられている場合、ターゲットはマージリクエストのソースブランチのコミットにしてください。

コミットステータスを設定する場合:

  • 既存のパイプラインが最初に検索され、ジョブが追加されます。
  • 適切なパイプラインが存在しない場合、CI_PIPELINE_SOURCE: externalを指定して新しいパイプラインが作成されます。

詳細については、外部コミットステータスを参照してください。

同じコミットに対して重複するパイプラインが存在する場合、どのパイプラインが外部ステータスを受信するかが不明確になる可能性があります。重複を避けるようにパイプラインを構成します。

1つのパイプラインのジョブ最大数制限をすでに超えているパイプラインが存在する場合は、以下のとおりとなります:

  • pipeline_idが指定されている場合は422エラー（The number of jobs has exceeded the limit）が返されます。
  • それ以外の場合は、新しいパイプラインが作成されます。

SHA/refsの組み合わせに対して更新が既に進行中の場合、409エラーが返されます。このエラーを処理するには、リクエストを再試行してください。

POST /projects/:id/statuses/:sha
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいコミットSHA。
state文字列はいステータスの状態。pending、running、success、failed、canceled、skippedのいずれかになります。
coverage浮動小数点数いいえ合計コードカバレッジ。
description文字列いいえステータスの短い説明。255文字以下にする必要があります。
nameまたはcontext文字列いいえこのステータスを他のシステムのステータスと区別するためのラベル。デフォルト値はdefaultです。
pipeline_id整数いいえステータスを設定するパイプラインのID。同じSHAで複数のパイプラインがある場合に使用します。
ref文字列いいえステータスが参照するref（ブランチまたはタグ）。255文字以下にする必要があります。
target_url文字列いいえこのステータスに関連付けるターゲットURL。255文字以下にする必要があります。

成功した場合は、201 Createdと以下のレスポンス属性が返されます:

属性型説明
allow_failureブール値trueの場合、ステータスは失敗を許可します。
authorオブジェクトステータス作成者に関する情報。
coverage浮動小数点数カバレッジのパーセンテージ。
created_at文字列ステータスが作成された日付。
description文字列スキャンの説明。
finished_at文字列ステータスが完了した日付。
id整数ステータスのID。
name文字列ステータスの名前。
ref文字列コミットの参照（ブランチまたはタグ）。
sha文字列コミットのハッシュ。
started_at文字列ステータスが開始された日付。
status文字列コミットの状態。
target_url文字列ステータスに関連付けられているターゲットURL。
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"

レスポンス例:

{
  "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"
}

コミットに関連付けられたマージリクエストをリストする

特定のコミットを最初に導入したマージリクエストに関する情報を返します。

GET /projects/:id/repository/commits/:sha/merge_requests
属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいコミットSHA。
state文字列いいえ指定された状態（opened、closed、locked、またはmerged）のマージリクエストを返します。このパラメータを省略すると、状態に関係なく、すべてのマージリクエストが取得されます。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
assigneeオブジェクトマージリクエストの担当者に関する情報。
authorオブジェクトマージリクエストの作成者に関する情報。
created_at文字列マージリクエストが作成された日付。
description文字列マージリクエストの説明。
discussion_lockedブール値trueの場合、ディスカッションはロックされます。
downvotes整数同意しないの数。
draftブール値trueの場合、マージリクエストはドラフトです。
force_remove_source_branchブール値trueの場合、ソースブランチの削除を強制します。
id整数マージリクエストのID。
iid整数マージリクエストの内部ID。
labels配列マージリクエストに関連付けられたラベル。
merge_commit_sha文字列マージコミットのSHA。
merge_status文字列マージリクエストのマージステータス。
merge_when_pipeline_succeedsブール値trueの場合、パイプラインが成功するとマージされます。
milestoneオブジェクトマージリクエストに関連付けられたマイルストーン。
project_id整数プロジェクトのID。
sha文字列マージリクエストのID。
should_remove_source_branchブール値trueの場合、マージ後にソースブランチを削除します。
source_branch文字列マージリクエストのソースブランチ。
source_project_id整数ソースブランチのID。
squash_commit_sha文字列スカッシュコミットのSHA。
state文字列マージリクエストの状態。
target_branch文字列マージリクエストのターゲットブランチ。
target_project_id整数ターゲットプロジェクトのID（数値）。
time_statsオブジェクトタイムトラッキングの統計。
title文字列マージリクエストのタイトル。
updated_at文字列マージリクエストが最後に更新された日時。
upvotes整数「同意する」の数。
user_notes_count整数ユーザーノートの数。
web_url文字列マージリクエストのWeb URL。
work_in_progressブール値trueの場合、マージリクエストは実行中として設定されます。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests?state=opened"

レスポンス例:

[
  {
    "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
    }
  }
]

コミット署名を取得

コミットが署名されている場合にコミットから署名を取得します。署名なしコミットの場合、404応答になります。

GET /projects/:id/repository/commits/:sha/signature

パラメータは以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
sha文字列はいリポジトリのブランチまたはタグのコミットハッシュまたは名前。

成功した場合は、200 OKと以下のレスポンス属性が返されます:

属性型説明
commit_source文字列コミットのソース。
gpg_key_id整数GPGキーのID（PGP署名の場合）。
gpg_key_primary_keyid文字列GPGキーのプライマリキーID。
gpg_key_subkey_id文字列GPGキーのサブキーID。
gpg_key_user_email文字列GPGキーに関連付けられているメールアドレス。
gpg_key_user_name文字列GPGキーに関連付けられているユーザー名。
keyオブジェクトSSHキー情報（SSH署名の場合）。
signature_type文字列署名の種類（PGP、SSH、またはX509）。
verification_status文字列署名の検証状態。
x509_certificateオブジェクトX.509署名の情報（X.509署名の場合）。
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/repository/commits/da738facbc19eb2fc2cef57c49be0e6038570352/signature"

コミットがGPGで署名されている場合の応答の例:

{
  "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"
}

コミットがSSHで署名されている場合の応答の例:

{
  "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"
}

コミットがX.509で署名されている場合の応答の例:

{
  "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"
}

コミットが署名されていない場合の応答の例:

{
  "message": "404 GPG Signature Not Found"
}