이 API로 리포지터리 파일을 관리합니다. 이 API의 속도 제한을 구성할 수도 있습니다.

개인 액세스 토큰에 사용 가능한 스코프#

개인 액세스 토큰은 다음 스코프를 지원합니다.

리포지터리에서 파일 조회#

리포지터리에 있는 지정한 파일의 정보를 조회합니다. 이름, 크기, 파일 콘텐츠 같은 정보가 포함됩니다. 파일 콘텐츠는 Base64로 인코딩됩니다. 리포지터리가 공개되어 있으면 인증 없이 이 엔드포인트에 액세스할 수 있습니다.

10 MB보다 큰 blob의 경우 이 엔드포인트에는 분당 5회의 속도 제한이 적용됩니다.

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

지원하는 속성은 다음과 같습니다.

성공하면 200 OK와 다음 응답 속성을 반환합니다.

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

브랜치 이름을 모르거나 기본 브랜치를 사용하려면 ref 값으로 HEAD를 사용할 수 있습니다. 예를 들면 다음과 같습니다.

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

응답 예시:

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

파일 메타데이터만 가져오기#

HEAD를 사용해 파일 메타데이터만 가져올 수도 있습니다.

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

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

응답 예시:

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: main
X-Gitlab-Size: 1476
X-Gitlab-Execute-Filemode: false
...

리포지터리에서 파일 blame 히스토리 조회#

리포지터리에 있는 지정한 파일의 blame 히스토리를 조회합니다. 각 blame 범위에는 라인과 해당 라인의 커밋 정보가 들어 있습니다.

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

지원하는 속성은 다음과 같습니다.

성공하면 200 OK와 다음 응답 속성을 반환합니다.

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

응답 예시:

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

파일 blame 메타데이터만 가져오기#

파일의 blame 메타데이터만 반환하려면 HEAD 메서드를 사용합니다.

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

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

응답 예시:

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: main
X-Gitlab-Size: 1476
X-Gitlab-Execute-Filemode: false
...

blame 범위 요청#

blame 범위를 요청하려면 파일의 시작 라인 번호와 끝 라인 번호를 range[start] 및 range[end] 파라미터로 지정합니다.

curl --head --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=main&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

지원하는 속성은 다음과 같습니다.

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

리포지터리에 파일 생성#

히스토리

• GitLab 18.7에서 요청 크기 제한과 속도 제한이 도입되었습니다.

지정한 리포지터리에 파일을 생성합니다. 한 번의 요청으로 여러 파일을 생성하려면 커밋 API를 참고합니다.

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

지원하는 속성은 다음과 같습니다.

성공하면 201 Created와 다음 응답 속성을 반환합니다.

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

응답 예시:

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

리포지터리의 파일 업데이트#

히스토리

• GitLab 18.7에서 요청 크기 제한과 속도 제한이 도입되었습니다.

리포지터리에 있는 지정한 파일을 업데이트합니다. 한 번의 요청으로 여러 파일을 업데이트하려면 커밋 API를 참고합니다.

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

지원하는 속성은 다음과 같습니다.

성공하면 200 OK와 다음 응답 속성을 반환합니다.

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

응답 예시:

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

어떤 이유로든 커밋이 실패하면 API는 구체적이지 않은 오류 메시지와 함께 400 Bad Request 오류를 반환합니다. 커밋 실패의 원인으로는 다음이 있습니다.

• file_path에 /../가 포함된 경우(디렉터리 트래버설 시도).
• 커밋이 비어 있는 경우. 새 파일 콘텐츠가 현재 파일 콘텐츠와 동일합니다.
• 파일을 편집하는 동안 다른 사용자가 git push로 브랜치를 업데이트한 경우.

GitLab Shell은 Boolean 반환 코드를 사용하므로 GitLab 이 오류를 구체적으로 지정하지 못합니다.

리포지터리의 파일 삭제#

리포지터리에 있는 지정한 파일을 삭제합니다. 한 번의 요청으로 여러 파일을 삭제하려면 커밋 API를 참고합니다.

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

지원하는 속성은 다음과 같습니다.

성공하면 200 OK를 반환합니다.

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