리포지터리 파일 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>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=main"
속성 타입 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로
file_path 문자열 예 URL 인코딩된 새 파일의 전체 경로, 예: lib%2Fclass%2Erb
ref 문자열 예 브랜치, 태그 또는 커밋의 이름

응답 예시: 

{
  "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
}
note
blob_id는 블롭 SHA입니다. 리포지터리 API의 리포지터리에서 블롭 가져오기를 참조하세요.

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=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
속성 타입 필수 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로
file_path 문자열 예 URL 인코딩된 새 파일의 전체 경로, 예: lib%2Fclass%2Erb
ref 문자열 예 브랜치, 태그 또는 커밋의 이름
range[end] 정수 예 블레임할 범위의 마지막 라인
range[start] 정수 예 블레임할 범위의 첫 번째 라인
range 해시 아니요 블레임 범위 
curl --header "PRIVATE-TOKEN: <your_access_token>" "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'",
      ""
    ]
  },
  ...
]
note
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=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>" "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버그 수정도 함께",
      "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 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로
file_path 문자열 예 lib%2Fclass%2Erb와 같이 URL 인코딩된 새 파일의 전체 경로
ref 문자열 아니오 브랜치, 태그 또는 커밋의 이름입니다. 기본값은 프로젝트의 HEAD입니다.
lfs 부울 아니오 응답이 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=main"
note
리포지터리에서 파일 가져오기와 마찬가지로 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": "내용", "commit_message": "새 파일 생성"}' \
     "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"

예시 응답: 

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

리포지터리의 기존 파일 업데이트

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

PUT /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일 수 있습니다.
last_commit_id 문자열 아니오 알려진 마지막 파일 커밋 ID입니다.
start_branch 문자열 아니오 새 브랜치를 생성할 기본 브랜치의 이름입니다. 
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": "내용", "commit_message": "파일 업데이트"}' \
     "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이 오류를 지정하지 못하도록 부울 반환 코드를 가지고 있습니다.

리포지터리에 있는 기존 파일 삭제

이 기능을 사용하면 단일 파일을 삭제할 수 있습니다. 하나의 요청으로 여러 파일을 삭제하려면 커밋 API를 참조하세요. 

DELETE /projects/:id/repository/files/:file_path
속성 유형 필수 여부 설명
branch 문자열 예 생성할 새 브랜치의 이름. 커밋은 이 브랜치에 추가됩니다.
commit_message 문자열 예 커밋 메시지.
file_path 문자열 예 URL 인코딩된 새 파일의 전체 경로. 예: lib%2Fclass%2Erb.
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 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": "main", "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"