리포지터리 파일 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
}
note
blob_id는 블롭 SHA입니다. Repositories 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
...

리포지터리에서 파일 blame 가져오기

파일 blame 정보를 받을 수 있습니다. 각 blame 범위는 라인 및 해당 커밋 정보를 포함합니다. 

GET /projects/:id/repository/files/:file_path/blame
속성 유형 필수 여부 설명
id 정수 또는 문자열 예 인증된 사용자가 소유한 프로젝트의 ID 또는 URL 인코딩된 경로
file_path 문자열 예 lib%2Fclass%2Erb와 같은 새 파일의 URL 인코딩된 전체 경로
ref 문자열 예 브랜치, 태그 또는 커밋의 이름
range[end] 정수 예 blame할 범위의 마지막 라인
range[start] 정수 예 blame할 범위의 첫 라인
range 해시 아니오 blame 범위 
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
...

예시

Blame 범위를 요청하려면 파일의 시작 라인 번호와 끝 라인 번호를 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"