リポジトリAPI

リポジトリツリー一覧

数値(?page=2)による結果のページの反復はGitLab 14.3で非推奨となりました。

プロジェクト内のリポジトリファイルとディレクトリの一覧を取得します。リポジトリが公開されている場合、このエンドポイントは認証なしでアクセスできます。

このコマンドはgit ls-tree コマンドと基本的に同じ機能を提供します。詳細は Git 内部ドキュメントのTree Objectsのセクションを参照ください。

caution
このエンドポイントはGitLab 15.0でキーセットベースのページネーションに変更されました。数字 (?page=2) を使った結果のページのイテレートはサポートされていません。
GET /projects/:id/repository/tree

サポートされる属性:

属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
page_token文字列です。いいえ次のページを取得するツリーレコードID。キーセットのページネーションでのみ使用されます。
pagination文字列です。いいえ keyset の場合、キーセットベースのページ分割方法を使用します。
path文字列です。いいえリポジトリ内のパス。サブディレクトリの内容を取得するために使用します。
per_page整数。いいえ1ページに表示する結果の数。指定しない場合、デフォルトは20 です。詳細については、ページ分割を参照してください。
recursivebooleanいいえ再帰ツ リ ーを取得す る ために用い ら れ る 論理値。デフォルトはfalse
ref文字列です。いいえリポジトリのブランチまたはタグの名前、または指定しない場合はデフォルトのブランチ。
[
  {
    "id": "a1e8f8d745cc87e3a9248358d9352bb7f9a0aeba",
    "name": "html",
    "type": "tree",
    "path": "files/html",
    "mode": "040000"
  },
  {
    "id": "4535904260b1082e14f867f7a24fd8c21495bde3",
    "name": "images",
    "type": "tree",
    "path": "files/images",
    "mode": "040000"
  },
  {
    "id": "31405c5ddef582c5a9b7a85230413ff90e2fe720",
    "name": "js",
    "type": "tree",
    "path": "files/js",
    "mode": "040000"
  },
  {
    "id": "cc71111cfad871212dc99572599a568bfe1e7e00",
    "name": "lfs",
    "type": "tree",
    "path": "files/lfs",
    "mode": "040000"
  },
  {
    "id": "fd581c619bf59cfdfa9c8282377bb09c2f897520",
    "name": "markdown",
    "type": "tree",
    "path": "files/markdown",
    "mode": "040000"
  },
  {
    "id": "23ea4d11a4bdd960ee5320c5cb65b5b3fdbc60db",
    "name": "ruby",
    "type": "tree",
    "path": "files/ruby",
    "mode": "040000"
  },
  {
    "id": "7d70e02340bac451f281cecf0a980907974bd8be",
    "name": "whitespace",
    "type": "blob",
    "path": "files/whitespace",
    "mode": "100644"
  }
]

リポジトリから blob を取得します。

リポジトリ内のブロブについて、サイズや内容などの情報を受け取ることができます。ブロブの内容は Base64 エンコードされています。リポジトリが公開されている場合、このエンドポイントは認証なしでアクセスできます。

GET /projects/:id/repository/blobs/:sha

サポートされる属性:

属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
sha文字列です。yesブロブSHA。

生のブロブコンテンツ

blob SHA によって、blob の生のファイル コンテンツを取得します。リポジトリが公開されている場合、このエンドポイントは認証なしでアクセスできます。

GET /projects/:id/repository/blobs/:sha/raw

サポートされる属性:

属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
sha文字列です。yesブロブSHA。

ファイルアーカイブの取得

リポジトリのアーカイブを取得します。リポジトリが公開されている場合、このエンドポイントは認証なしでアクセスできます。

GitLab.com ユーザーの場合、このエンドポイントには 1 分あたり 5 リクエストというレートリミットのしきい値があります。

GET /projects/:id/repository/archive[.format]

format はアーカイブ形式を表すオプションのサフィックスで、デフォルトはtar.gzです。例えばarchive.zip を指定すると、ZIP 形式のアーカイブが送信されます。利用可能なオプションは以下のとおりです:

  • bz2
  • tar
  • tar.bz2
  • tar.gz
  • tb2
  • tbz
  • tbz2
  • zip

サポートされる属性:

属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
path文字列です。いいえダウンロードするリポジトリのサブパス。空の文字列の場合、デフォルトはリポジトリ全体です。
sha文字列です。いいえダウンロードするコミットのSHA。タグ、ブランチリファレンス、SHA のいずれかを使用できます。指定しなかった場合のデフォルトはデフォルトブランチの先端になります。

リクエストの例

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha>&path=<path>"

ブランチ、タグ、コミットの比較

リポジトリが公開されている場合、このエンドポイントは認証なしでアクセスできます。diff の制限に達した場合は、diff の文字列を空にすることができます。

GET /projects/:id/repository/compare

サポートされる属性:

属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
from文字列です。yesコミットSHAまたはブランチ名。
to文字列です。yesコミットSHAまたはブランチ名。
from_project_id整数。いいえ比較元のID。
straightbooleanいいえ比較方法:fromto (fromto) を直接比較する場合はtrue を、マージベース (fromto) を使用して比較する場合はfalse を指定します。デフォルトはfalseです。
GET /projects/:id/repository/compare?from=master&to=feature

応答例

{
  "commit": {
    "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1",
    "short_id": "12d65c8dd2b",
    "title": "JS fix",
    "author_name": "Example User",
    "author_email": "user@example.com",
    "created_at": "2014-02-27T10:27:00+02:00"
  },
  "commits": [{
    "id": "12d65c8dd2b2676fa3ac47d955accc085a37a9c1",
    "short_id": "12d65c8dd2b",
    "title": "JS fix",
    "author_name": "Example User",
    "author_email": "user@example.com",
    "created_at": "2014-02-27T10:27:00+02:00"
  }],
  "diffs": [{
    "old_path": "files/js/application.js",
    "new_path": "files/js/application.js",
    "a_mode": null,
    "b_mode": "100644",
    "diff": "@@ -24,8 +24,10 @@\n //= require g.raphael-min\n //= require g.bar-min\n //= require branch-graph\n-//= require highlightjs.min\n-//= require ace/ace\n //= require_tree .\n //= require d3\n //= require underscore\n+\n+function fix() { \n+  alert(\"Fixed\")\n+}",
    "new_file": false,
    "renamed_file": false,
    "deleted_file": false
  }],
  "compare_timeout": false,
  "compare_same_ref": false,
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/compare/ae73cb07c9eeaf35924a10f713b364d32b2dd34f...0b4bc9a49b562e85de7cc9e834518ea6828729b9"
}

貢献者

  • 属性additionsdeletions は、GitLab 13.4 で非推奨となりました。は常に0を返すからです。
  • 属性additionsdeletions は GitLab 14.0 で削除されました。

リポジトリの貢献者リストを取得します。リポジトリが公開されている場合、このエンドポイントは認証なしでアクセスできます。

GET /projects/:id/repository/contributors

サポートされる属性:

属性種類必須説明
id整数または文字列。yes認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
order_by文字列です。いいえ nameemail 、またはcommits (コミット日順) フィールドで commits並べ替えられた投稿者を返しますcommits 。デフォルトは . commits
sort文字列です。いいえ asc またはdesc 順にソートされた投稿者を返します。デフォルトはasc です。

応答例

[{
  "name": "Example User",
  "email": "example@example.com",
  "commits": 117,
  "additions": 0,
  "deletions": 0
}, {
  "name": "Sample User",
  "email": "sample@example.com",
  "commits": 33,
  "additions": 0,
  "deletions": 0
}]

マージベース

コミット SHA、ブランチ名、タグなど、2 つ以上の参照に対する共通の先祖を取得します。

GET /projects/:id/repository/merge_base
属性種類必須説明
id整数または文字列。yes プロジェクトのIDまたはURLエンコードされたパス
refsアレイyes共通の祖先を見つける参照。複数の参照を受け付けます。

読みやすくするためにrefを切り詰めたリクエスト例:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.example.com/api/v4/projects/5/repository/merge_base?refs[]=304d257d&refs[]=0031876f"

応答例

{
  "id": "1a0b36b3cdad1d2ee32457c102a8c0b7056fa863",
  "short_id": "1a0b36b3",
  "title": "Initial commit",
  "created_at": "2014-02-27T08:03:18.000Z",
  "parent_ids": [],
  "message": "Initial commit\n",
  "author_name": "Example User",
  "author_email": "user@example.com",
  "authored_date": "2014-02-27T08:03:18.000Z",
  "committer_name": "Example User",
  "committer_email": "user@example.com",
  "committed_date": "2014-02-27T08:03:18.000Z"
}

変更履歴ファイルへの変更履歴データの追加

リポジトリ内のコミットに基づいて変更ログデータを生成します。

セマンティックバージョンとコミットの範囲が与えられると、GitLabは特定のGitトレーラーを使用するすべてのコミットの変更ログを生成します。GitLab はプロジェクトの Git リポジトリにある変更ログファイルに新しい Markdown 形式のセクションを追加します。出力形式はカスタマイズできます。

ユーザー向けのドキュメントはChangelogs を参照してください。

POST /projects/:id/repository/changelog

サポートされる属性

Changelogs はこれらの属性をサポートしています:

属性種類必須説明
version文字列です。yes変更ログを生成するバージョン。フォーマットはセマンティックバージョニングに従わなければなりません。
branch文字列です。いいえ変更履歴の変更をコミットするブランチ。デフォルトはプロジェクトのデフォルトブランチです。
config_file文字列です。いいえプロジェクトの Git リポジトリにある変更履歴設定ファイルへのパス。デフォルトは.gitlab/changelog_config.yml です。
datedatetimeいいえリリースの日時。デフォルトは現在の時刻です。
file文字列です。いいえ変更をコミットするファイル。デフォルトはCHANGELOG.md です。
from文字列です。いいえ変更履歴に含めるコミット範囲の始まりを示すコミットの SHA。このコミットは変更履歴に含まれません。
message文字列です。いいえ変更をコミットするときに使用するコミットメッセージです。デフォルトはAdd changelog for version X で、Xversion 引数の値です。
to文字列です。いいえ変更履歴に含めるコミット範囲の終了を示すコミットの SHA。このコミットが変更履歴に含ま_れます_。デフォルトはbranch 属性で指定されたブランチです。機能フラグchangelog_commits_limitation が無効になっていない限り、15000 コミットに制限されます。
trailer文字列です。いいえコミットを含める Git のトレイラー。デフォルトはChangelog です。大文字小文字を区別します:ExampleexampleeXaMpLEにはマッチしません。

from 属性の要件

from 属性が指定されていない場合、GitLab はversion 属性で指定されたバージョンの前の最後の安定バージョンの Git タグを使用します。GitLabがタグ名からバージョン番号を抽出するためには、Gitタグ名は特定のフォーマットに従う必要があります。デフォルトでは、GitLabはこれらのフォーマットを使うタグを考慮します:

  • vX.Y.Z
  • X.Y.Z

ここで、X.Y.Zセマンティックバージョニングに従ったバージョンです。たとえば、次のようなタグを持つプロジェクトを考えてみましょう:

  • v1.0.0-pre1
  • v1.0.0
  • v1.1.0
  • v2.0.0

version 属性が2.1.0 の場合、GitLab はタグv2.0.0 を使用します。また、バージョンが1.1.1、または1.2.0の場合、GitLab はタグ v1.1.0 を使用します。リリース前のタグは無視されるため、v1.0.0-pre1 タグは決して使用されません。

from 指定がなく、使用するタグが見つからない場合、APIはエラーを出 fromします。from このようなエラーを解決 fromするには、属性のfrom 値を明示的に指定する必要が fromあります。

使用例

これらの例では、cURLを使用してHTTPリクエストを実行します。コマンド例では、これらの値を使用します:

  • プロジェクトID:42
  • 場所: GitLab.comでホストされています。
  • API トークンの例 token

このコマンドは、バージョン1.0.0 の変更ログを生成します。

コミット範囲

  • 最後のリリースのタグから始まります。
  • ターゲットブランチの最後のコミットで終了します。デフォルトのターゲットブランチはプロジェクトのデフォルトブランチです。

最後のタグがv0.9.0 でデフォルトブランチがmain の場合、この例に含まれるコミットの範囲はv0.9.0..main となります:

curl --request POST --header "PRIVATE-TOKEN: token" \
  --data "version=1.0.0" "https://gitlab.com/api/v4/projects/42/repository/changelog"

別のブランチのデータを生成するには、branch パラメータを指定します。このコマンドはfoo ブランチのデータを生成します:

curl --request POST --header "PRIVATE-TOKEN: token" \
  --data "version=1.0.0&branch=foo" "https://gitlab.com/api/v4/projects/42/repository/changelog"

別のトレーラを使用するには、trailer パラメータを使用します:

curl --request POST --header "PRIVATE-TOKEN: token" \
  --data "version=1.0.0&trailer=Type" "https://gitlab.com/api/v4/projects/42/repository/changelog"

結果を別のファイルに保存するには、file パラメータを使用します:

curl --request POST --header "PRIVATE-TOKEN: token" \
  --data "version=1.0.0&file=NEWS" "https://gitlab.com/api/v4/projects/42/repository/changelog"

変更履歴データの生成

GitLab 14.6で導入されました

リポジトリ内のコミットを元に、変更履歴ファイルにコミットすることなく、変更履歴データを生成します。

POST /projects/:id/repository/changelog とまったく同じように動作しますが、変更履歴データは変更履歴ファイルにコミットされません。

GET /projects/:id/repository/changelog

サポートされる属性:

属性種類必須説明
version文字列です。yes変更ログを生成するバージョン。フォーマットはセマンティックバージョニングに従わなければなりません。
config_file文字列です。いいえプロジェクトの Git リポジトリにある changelog 設定ファイルのパス。デフォルトは.gitlab/changelog_config.yml です。
datedatetimeいいえリリースの日時。ISO 8601形式を使用。例:2016-03-11T03:45:40Z.デフォルトは現在の時刻です。
from文字列です。いいえ変更履歴の生成に使用するコミット範囲の開始位置 (SHA として)。このコミット自体はリストに含まれません。
to文字列です。いいえ変更履歴に使用するコミット範囲の終端 (SHA として)。このコミットがリストに含ま_れます_。デフォルトはデフォルトプロジェクトブランチの HEAD です。
trailer文字列です。いいえコミットを含める Git のトレーラー。デフォルトはChangelog
curl --header "PRIVATE-TOKEN: token" \
  "https://gitlab.com/api/v4/projects/42/repository/changelog?version=1.0.0"

レスポンスの例。読みやすくするために改行を追加しています:

{
  "notes": "## 1.0.0 (2021-11-17)\n\n### feature (2 changes)\n\n-
    [Title 2](namespace13/project13@ad608eb642124f5b3944ac0ac772fecaf570a6bf)
    ([merge request](namespace13/project13!2))\n-
    [Title 1](namespace13/project13@3c6b80ff7034fa0d585314e1571cc780596ce3c8)
    ([merge request](namespace13/project13!1))\n"
}