레포지토리 파일 API

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

이 API를 사용하여 레포지토리의 파일을 가져오고, 생성하고, 업데이트하고, 삭제할 수 있습니다.

또한 이 API에 대한 요율 제한을 구성할 수 있습니다.

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

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

범위 설명
api 레포지토리 파일에 대한 읽기-쓰기 접근을 허용합니다.
read_api 레포지토리 파일에 대한 읽기 접근을 허용합니다.
read_repository 레포지토리 파일에 대한 읽기 접근을 허용합니다.

레포지토리에서 파일 가져오기

레포지토리의 파일에 대한 이름, 크기 및 내용과 같은 정보를 수신할 수 있습니다. 파일 내용은 Base64로 인코딩되어 있습니다. 레포지토리가 공개적으로 액세스 가능하면 인증 없이 이 엔드포인트에 접근할 수 있습니다.

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

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=main"
속성 유형 필수 설명
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로.
file_path 문자열 예 lib%2Fclass%2Erb와 같은 새 파일의 URL 인코딩된 전체 경로.
ref 문자열 예 브랜치, 태그 또는 커밋의 이름.

응답

응답에서 blob_id는 blob SHA입니다. 레포지토리 API의 레포지토리에서 blob 가져오기를 참조하세요.

예시 응답:

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

리포지토리에서 파일 블레임 가져오기

블레임 정보를 검색합니다. 각 블레임 범위는 라인과 해당 커밋 정보를 포함합니다.

GET /projects/:id/repository/files/:file_path/blame
속성 유형 필수 설명
file_path string 예 lib%2Fclass%2Erb와 같은 새 파일의 URL 인코딩된 전체 경로.
id integer 또는 string 예 프로젝트의 ID 또는 URL 인코딩된 경로.
range[end] integer 예 블레임할 범위의 마지막 라인.
range[start] integer 예 블레임할 범위의 첫 번째 라인.
ref string 예 브랜치, 태그 또는 커밋의 이름.
range 해시 아니오 블레임 범위. 
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": "기능 추가\n\n버그 수정\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>" \
  --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
...

블레임 범위 요청

블레임 범위를 요청하려면, 파일의 시작 및 종료 라인 번호와 함께 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": "기능 추가\n\n버그 수정도 포함\n",
      "parent_ids": [
        "cc6e14f9328fa6d7b5a0d3c30dc2002a3f2a3822"
      ],
      "authored_date": "2015-12-18T08:12:22.000Z",
      "author_name": "존 도",
      "author_email": "john.doe@example.com",
      "committed_date": "2015-12-18T08:12:22.000Z",
      "committer_name": "존 도",
      "committer_email": "john.doe@example.com"
    },
    "lines": [
      "require 'fileutils'",
      "require 'open3'"
    ]
  },
  ...
]

저장소에서 원시 파일 가져오기 

GET /projects/:id/repository/files/:file_path/raw
속성 유형 필수 설명
file_path 문자열 예 새 파일의 URL 인코딩된 전체 경로, 예: lib%2Fclass%2Erb.
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로.
lfs 부울 아니오 응답이 Git LFS 파일 내용을 포함해야 하는지 여부. 파일이 Git LFS로 추적되지 않는 경우 무시됨. 기본값은 false.
ref 문자열 아니오 브랜치, 태그 또는 커밋의 이름. 기본값은 프로젝트의 HEAD. 
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"

참고:
저장소에서 파일 가져오기와 같이 HEAD를 사용하여 파일 메타데이터만 가져올 수 있습니다.

저장소에 새 파일 생성

단일 파일을 생성할 수 있습니다. 단일 요청으로 여러 파일을 생성하려면, 커밋 API를 참조하세요.

POST /projects/:id/repository/files/:file_path
속성 유형 필수 설명
branch 문자열 예 새 브랜치의 이름. 커밋이 이 브랜치에 추가됩니다.
commit_message 문자열 예 커밋 메시지.
content 문자열 예 파일의 내용.
file_path 문자열 예 새 파일의 URL 인코딩된 전체 경로. 예: lib%2Fclass%2Erb.
id 정수 또는 문자열 예 프로젝트의 ID 또는 URL 인코딩된 경로.
author_email 문자열 아니오 커밋 작성자의 이메일 주소.
author_name 문자열 아니오 커밋 작성자의 이름.
encoding 문자열 아니오 인코딩을 base64로 변경. 기본값은 text.
execute_filemode 부울 아니오 파일의 execute 플래그 활성화 또는 비활성화. true 또는 false일 수 있습니다.
start_branch 문자열 아니오 새 브랜치를 생성하기 위한 기본 브랜치의 이름. 
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"
}

저장소에 있는 기존 파일 업데이트

단일 파일을 업데이트할 수 있습니다. 단일 요청으로 여러 파일을 업데이트하려면, commits API를 참조하세요.

PUT /projects/:id/repository/files/:file_path
속성 유형 필수 설명
branch string 예 새로 생성할 브랜치의 이름입니다. 커밋이 이 브랜치에 추가됩니다.
commit_message string 예 커밋 메시지입니다.
content string 예 파일의 내용입니다.
file_path string 예 새 파일의 URL 인코딩 전체 경로입니다. 예: lib%2Fclass%2Erb.
id integer or string 예 프로젝트의 ID 또는 URL 인코딩 경로입니다.
author_email string 아니오 커밋 작성자의 이메일 주소입니다.
author_name string 아니오 커밋 작성자의 이름입니다.
encoding string 아니오 인코딩을 base64로 변경합니다. 기본값은 text입니다.
execute_filemode boolean 아니오 파일의 execute 플래그를 활성화하거나 비활성화합니다. true 또는 false일 수 있습니다.
last_commit_id string 아니오 마지막으로 알려진 파일 커밋 ID입니다.
start_branch string 아니오 새 브랜치를 만들기 위해 기반 브랜치의 이름입니다. 
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"
}

커밋이 어떤 이유로 실패할 경우, 비특정 오류 메시지와 함께 400 Bad Request 오류를 반환합니다. 실패한 커밋의 가능한 원인은 다음과 같습니다:

  • file_path가 /../를 포함하고 있습니다(디렉터리 탐색 시도가 포함됨).
  • 커밋이 비어있습니다: 새 파일 내용이 현재 파일 내용과 동일합니다.
  • 누군가가 파일 편집이 진행 중일 때 git push로 브랜치를 업데이트했습니다.

GitLab Shell은 부울 반환 코드를 가지고 있으며, 이로 인해 GitLab이 오류를 지정할 수 없습니다.

저장소에 있는 기존 파일 삭제

단일 파일을 삭제합니다. 단일 요청으로 여러 파일을 삭제하려면, commits API를 참조하세요.

DELETE /projects/:id/repository/files/:file_path
속성 유형 필수 설명
branch string 예 새로 생성할 브랜치의 이름입니다. 커밋이 이 브랜치에 추가됩니다.
commit_message string 예 커밋 메시지입니다.
file_path string 예 새 파일의 URL 인코딩 전체 경로입니다. 예: lib%2Fclass%2Erb.
id integer or string 예 프로젝트의 ID 또는 URL 인코딩 경로입니다.
author_email string 아니오 커밋 작성자의 이메일 주소입니다.
author_name string 아니오 커밋 작성자의 이름입니다.
last_commit_id string 아니오 마지막으로 알려진 파일 커밋 ID입니다.
start_branch string 아니오 새 브랜치를 만들기 위해 기반 브랜치의 이름입니다. 
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"