リポジトリファイルAPI

この API を使用して、リポジトリ内のファイルを取得、作成、更新、削除できます。この API のレート制限を設定することもできます。

個人アクセストークンで利用可能なスコープ

個人アクセストークンを使用して利用できるさまざまなスコープを次の表に示します。

スコープ	説明
`api`	リポジトリファイルへの読み書きアクセスを許可します。
`read_api`	リポジトリファイルへの読み込みアクセスを許可します。
`read_repository`	リポジトリファイルへの読み取りアクセスを許可します。

リポジトリからファイルを取得

レスポンスのexecute_filemode フィールドは GitLab 14.10 で導入されました。

名前、サイズ、内容のようなリポジトリ内のファイルに関する情報を受け取ることができます。ファイルの内容は Base64 エンコードされています。リポジトリが公開されている場合、このエンドポイントは認証なしでアクセスできます。

GET /projects/:id/repository/files/:file_path

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master"

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス。
`file_path`	文字列です。	yes	URL エンコードされた新しいファイルへのフルパス、例えば`lib%2Fclass%2Erb`.
`ref`	文字列です。	yes	ブランチ、タグ、コミットの名前。

応答例

{
  "file_name": "key.rb",
  "file_path": "app/models/key.rb",
  "size": 1476,
  "encoding": "base64",
  "content": "IyA9PSBTY2hlbWEgSW5mb3...",
  "content_sha256": "4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481",
  "ref": "master",
  "blob_id": "79f7bbd25901e8334750839545a9bd021f0e4c83",
  "commit_id": "d5a3ff139356ce33e37e73add446f16869741b50",
  "last_commit_id": "570e7b2abdd848b95f2f578043fc23bd6f6fd24d",
  "execute_filemode": false
}

blob_id は blob SHA です。Repositories API のGet a blob fromrepository を参照してください。

GET メソッドに加えて、HEAD を使用してファイルのメタデータだけを取得することもできます。

HEAD /projects/:id/repository/files/:file_path

curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master"

応答例

HTTP/1.1 200 OK
...
X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
X-Gitlab-Encoding: base64
X-Gitlab-File-Name: key.rb
X-Gitlab-File-Path: app/models/key.rb
X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
X-Gitlab-Ref: master
X-Gitlab-Size: 1476
X-Gitlab-Execute-Filemode: false
...

リポジトリから blame ファイルを取得

注釈履歴情報を受け取ることができます。それぞれの注釈範囲は行と対応するコミット情報を含んでいます。

GET /projects/:id/repository/files/:file_path/blame

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス。
`file_path`	文字列です。	yes	新しいファイルへの URL エンコードされたフルパス、例えば`lib%2Fclass%2Erb`.
`ref`	文字列です。	yes	ブランチ、タグ、コミットの名前。
`range[end]`	整数。	yes	責めるべき範囲の最後の行。
`range[start]`	整数。	yes	責めるべき範囲の最初の行。
`range`	ハッシュ	いいえ	責任の範囲

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master"

応答例

[
  {
    "commit": {
      "id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
      "message": "Add feature\n\nalso fix bug\n",
      "parent_ids": [
        "cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
      ],
      "authored_date": "2015-12-18T08:12:22.000Z",
      "author_name": "John Doe",
      "author_email": "john.doe@example.com",
      "committed_date": "2015-12-18T08:12:22.000Z",
      "committer_name": "John Doe",
      "committer_email": "john.doe@example.com"
    },
    "lines": [
      "require 'fileutils'",
      "require 'open3'",
      ""
    ]
  },
  ...
]

HEAD メソッドはファイルのメタデータだけを返します。

curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master"

応答例

HTTP/1.1 200 OK
...
X-Gitlab-Blob-Id: 79f7bbd25901e8334750839545a9bd021f0e4c83
X-Gitlab-Commit-Id: d5a3ff139356ce33e37e73add446f16869741b50
X-Gitlab-Content-Sha256: 4c294617b60715c1d218e61164a3abd4808a4284cbc30e6728a01ad9aada4481
X-Gitlab-Encoding: base64
X-Gitlab-File-Name: file.rb
X-Gitlab-File-Path: path/to/file.rb
X-Gitlab-Last-Commit-Id: 570e7b2abdd848b95f2f578043fc23bd6f6fd24d
X-Gitlab-Ref: master
X-Gitlab-Size: 1476
X-Gitlab-Execute-Filemode: false
...

使用例

注釈範囲を指定するには、range[start] とrange[end] パラメータにファイルの開始行番号と終了行番号を指定します。

curl --head --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master&range[start]=1&range[end]=2"

応答例

[
  {
    "commit": {
      "id": "d42409d56517157c48bf3bd97d3f75974dde19fb",
      "message": "Add feature\n\nalso fix bug\n",
      "parent_ids": [
        "cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
      ],
      "authored_date": "2015-12-18T08:12:22.000Z",
      "author_name": "John Doe",
      "author_email": "john.doe@example.com",
      "committed_date": "2015-12-18T08:12:22.000Z",
      "committer_name": "John Doe",
      "committer_email": "john.doe@example.com"
    },
    "lines": [
      "require 'fileutils'",
      "require 'open3'"
    ]
  },
  ...
]

リポジトリから生ファイルを取得

GET /projects/:id/repository/files/:file_path/raw

属性	種類	必須	説明
`id`	整数または文字列。	yes	認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス。
`file_path`	文字列です。	yes	新しいファイルへの URL エンコードされたフルパス、たとえば`lib%2Fclass%2Erb`.
`ref`	文字列です。	いいえ	ブランチ、タグ、コミットの名前。デフォルトはプロジェクトの`HEAD` です。
`lfs`	boolean	いいえ	ポインタではなく Git LFS ファイルの内容を返すかどうかを指定します。Git LFS でファイルが追跡されていない場合は無視されます。デフォルトは`false` 。

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master"

Get file from repository のように、HEAD を使ってファイルのメタデータだけを取得することもできます。

リポジトリに新規ファイルを作成

execute_filemode パラメータは GitLab 14.10 で導入されました。

一つのファイルを作成できます。一つのリクエストで複数のファイルを作成するには、commits API を参照してください。

POST /projects/:id/repository/files/:file_path

属性	種類	必須	説明
`branch`	文字列です。	yes	新しく作成するブランチの名前。コミットはこのブランチに追加されます。
`commit_message`	文字列です。	yes	コミットメッセージ。
`content`	文字列です。	yes	ファイルの内容
`file_path`	文字列です。	yes	新しいファイルへの URL エンコードされたフルパス。例:`lib%2Fclass%2Erb`.
`id`	整数または文字列。	yes	認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス。
`author_email`	文字列です。	いいえ	コミット作成者のメールアドレス。
`author_name`	文字列です。	いいえ	コミット作成者の名前。
`encoding`	文字列です。	いいえ	エンコードを`base64` に変更します。デフォルトは`text` 。
`execute_filemode`	boolean	いいえ	ファイルの`execute` フラグを有効または無効にします。`true` または`false`を指定します。
`start_branch`	文字列です。	いいえ	新しいブランチを作成するベースブランチの名前。

curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' \
     --header "Content-Type: application/json" \
     --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname",
               "content": "some content", "commit_message": "create a new file"}' \
     "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"

応答例

{
  "file_path": "app/project.rb",
  "branch": "master"
}

リポジトリの既存のファイルを更新します。

execute_filemode パラメータは GitLab 14.10 で導入されました。

単一のファイルを更新できます。一つのリクエストで複数のファイルを更新するには、commits API を参照してください。

PUT /projects/:id/repository/files/:file_path

属性	種類	必須	説明
`branch`	文字列です。	yes	新しく作成するブランチの名前。コミットはこのブランチに追加されます。
`commit_message`	文字列です。	yes	コミットメッセージ。
`content`	文字列です。	yes	ファイルの内容
`file_path`	文字列です。	yes	新しいファイルへの URL エンコードされたフルパス。例:`lib%2Fclass%2Erb`.
`id`	整数または文字列。	yes	認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス
`author_email`	文字列です。	いいえ	コミット作成者のメールアドレス。
`author_name`	文字列です。	いいえ	コミット作成者の名前。
`encoding`	文字列です。	いいえ	エンコードを`base64` に変更します。デフォルトは`text` 。
`execute_filemode`	boolean	いいえ	ファイルの`execute` フラグを有効または無効にします。`true` または`false`を指定します。
`last_commit_id`	文字列です。	いいえ	最後に確認されたファイルのコミットID。
`start_branch`	文字列です。	いいえ	新しいブランチを作成するベースブランチの名前。

curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' \
     --header "Content-Type: application/json" \
     --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname",
       "content": "some content", "commit_message": "update file"}' \
     "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"

応答例

{
  "file_path": "app/project.rb",
  "branch": "master"
}

何らかの理由でコミットが失敗した場合は、400 Bad Request エラーメッセージを返します。失敗したコミットの原因としては、次のようなものが考えられます：

file_path に/../ が含まれていました（ディレクトリトラバーサルを試みました）。
コミットは空でした。新しいファイルの内容は現在のファイルの内容と同一でした。
ファイルの編集中にgit push によってブランチが更新されました。

GitLab Shellはブール値のリターンコードを持ち、GitLabがエラーを特定することを防ぎます。

リポジトリ内の既存ファイルの削除

単一のファイルを削除します。ひとつのリクエストで複数のファイルを削除するには、コミット API を参照してください。

DELETE /projects/:id/repository/files/:file_path

属性	種類	必須	説明
`branch`	文字列です。	yes	新しく作成するブランチの名前。コミットはこのブランチに追加されます。
`commit_message`	文字列です。	yes	コミットメッセージ。
`file_path`	文字列です。	yes	新しいファイルへの URL エンコードされたフルパス。例:`lib%2Fclass%2Erb`.
`id`	整数または文字列。	yes	認証ユーザーが所有するプロジェクトのIDまたはURLエンコードされたパス。
`author_email`	文字列です。	いいえ	コミット作成者のメールアドレス。
`author_name`	文字列です。	いいえ	コミット作成者の名前。
`last_commit_id`	文字列です。	いいえ	最後に確認されたファイルのコミットID。
`start_branch`	文字列です。	いいえ	新しいブランチを作成するベースブランチの名前。

curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \
     --header "Content-Type: application/json" \
     --data '{"branch": "master", "author_email": "author@example.com", "author_name": "Firstname Lastname",
       "commit_message": "delete file"}' \
     "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"

リポジトリファイルAPI

個人アクセストークンで利用可能なスコープ

リポジトリからファイルを取得

リポジトリから blame ファイルを取得

使用例

リポジトリから生ファイルを取得

リポジトリに新規ファイルを作成

リポジトリの既存のファイルを更新します。

リポジトリ内の既存ファイルの削除

Help & feedback

Docs

Product

Feature availability and product trials

Get Help