リポジトリファイルAPI

リポジトリファイルのCRUD

この API を使用して、リポジトリファイルの作成、読み込み、更新、削除を行います。

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

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

read_repository スコープは GitLab 11.6 で導入されました。

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

リポジトリにあるファイルの名前、サイズ、内容などの情報を受け取ることができます。ファイルの内容は 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"

回答例

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

パラメーター

file_path (必須) - URL エンコードされた新しいファイルへのフルパス。例: lib%2Fclass%2Erb
ref (必須) - ブランチ、タグ、コミットの名前。

注：blob_id は blob SHA です。repositories - 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
...

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

各責任範囲には、行と対応するコミット情報が含まれています。

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

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'",
      ""
    ]
  },
  ...
]

パラメーター

file_path (必須) - URL エンコードされた新しいファイルへのフルパス。例: lib%2Fclass%2Erb
ref (必須) - ブランチ、タグ、コミットの名前。

注意: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
...

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

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

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

パラメーター

file_path (必須) - URL エンコードされた新しいファイルへのフルパス。例: lib%2Fclass%2Erb
ref (必須) - ブランチ、タグ、コミットの名前。

注意:リポジトリからファイルを取得するのと同様に、HEAD を使ってファイルのメタデータだけを取得することができます。

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

1回のリクエストで複数のファイルを作成する場合は、commits APIを参照してください。

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

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

パラメーター

file_path (必須) - URL エンコードされた新しいファイルへのフルパス。例: lib%2Fclass%2Erb
branch (必須) - ブランチ名
start_branch (オプション) - 新しいコミットを開始するブランチの名前。
encoding (オプション) - エンコーディングを ‘base64’ に変更します。デフォルトは text です。
author_email (オプション) - コミット作成者のメールアドレスを指定します。
author_name (オプション) - コミット作成者の名前を指定します。
content (必須) - ファイルの内容
commit_message (必須) - コミットメッセージ

リポジトリ内の既存ファイルの更新

ひとつのリクエストで複数のファイルを更新する場合は、commits API を参照ください。

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

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

パラメーター

file_path (必須) - URL エンコードされた新しいファイルへのフルパス。例: lib%2Fclass%2Erb
branch (必須) - ブランチ名
start_branch (オプション) - 新しいコミットを開始するブランチの名前。
encoding (オプション) - エンコーディングを ‘base64’ に変更します。デフォルトは text です。
author_email (オプション) - コミット作成者のメールアドレスを指定します。
author_name (オプション) - コミット作成者の名前を指定します。
content (必須) - 新しいファイルの内容
commit_message (必須) - コミットメッセージ
last_commit_id (オプション) - 最後に確認されたファイルのコミット ID

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

file_path に/../ (ディレクトリトラバーサルの試み) が含まれていました；
つまり、ユーザーは空のコミットを行おうとしたのです；
ブランチは、ファイルの編集中に Git のプッシュによって更新されました。

現在GitLab Shellはブール値のリターンコードを持っており、GitLabがエラーを指定することを防いでいます。

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

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

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

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"

パラメーター

file_path (必須) - URL エンコードされた新しいファイルへのフルパス。例: lib%2Fclass%2Erb
branch (必須) - ブランチ名
start_branch (オプション) - 新しいコミットを開始するブランチの名前。
author_email (オプション) - コミット作成者のメールアドレスを指定します。
author_name (オプション) - コミット作成者の名前を指定します。
commit_message (必須) - コミットメッセージ
last_commit_id (オプション) - 最後に確認されたファイルのコミット ID

クリエーションラインについて

私たちクリエーションラインは、日本で最も古く2017年にGitLabサービスの提供を開始し、2022年には「Asia-Pacific Partner of the Year」も獲得。GitLabのサブスクリプション販売やテクニカルサポートだけでなく、GitLab Enterpriseの導入支援やGitLabトレーニングなど多様なサービスを提供し、エンタープライズを中心に豊富な実績を誇ります。GitLabに関するお悩みがありましたら、ぜひお気軽にお問い合わせください。日本で唯一、3度にわたるMVPを獲得したGitLabエバンジェリストをはじめとしたエキスパートチームが、あなたの課題解決をご支援します。