Repository files 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 문자열 예 lib%2Fclass%2Erb와 같은 새 파일의 URL 인코딩된 전체 경로
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
}

참고: blob_id는 blob 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 문자열 예 lib%2Fclass%2Erb와 같은 새 파일의 URL 인코딩된 전체 경로
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": "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'",
      ""
    ]
  },
  ...
]

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

저장소에서 Raw 파일 가져오기 

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"

참고: 저장소에서 파일 가져오기와 마찬가지로 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"}' \
     "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": "파일 삭제"}' \
     "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"