이 API를 사용하여 리포지터리 파일을 관리합니다. 이 API에 대한 속도 제한을 구성할 수도 있습니다.

개인 액세스 토큰에 사용 가능한 범위#

개인 액세스 토큰은 다음 범위를 지원합니다:

리포지터리에서 파일 검색#

리포지터리의 지정된 파일에 대한 정보를 검색합니다. 여기에는 이름, 크기, 파일 내용과 같은 정보가 포함됩니다. 파일 내용은 Base64로 인코딩됩니다. 리포지터리가 공개적으로 접근 가능한 경우 인증 없이 이 엔드포인트에 액세스할 수 있습니다.

10 MB보다 큰 블롭의 경우 이 엔드포인트는 분당 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 메타데이터만 가져오기#

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

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에는 불리언 반환 코드가 있어 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"