저장소 파일 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 문자열 예 URL로 인코딩된 새 파일의 전체 경로, 예: lib%2Fclass%2Erb
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
...

저장소에서 파일의 blame 가져오기

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

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

파일 메타데이터만 가져오기

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버그 수정", 
      "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
속성 타입 필수여부 설명
file_path string yes lib%2Fclass%2Erb와 같은 URL 인코딩된 새 파일의 전체 경로.
id integer or string yes 프로젝트의 ID 또는 URL 인코딩된 경로.
lfs boolean no 파일이 Git LFS에 의해 추적되지 않은 경우 포인터 대신 Git LFS 파일 내용을 가져올지 여부를 결정합니다. 기본값은 false입니다.
ref string no 브랜치, 태그 또는 커밋의 이름. 기본값은 프로젝트의 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 string yes 생성할 새 브랜치의 이름. 커밋은 이 브랜치에 추가됩니다.
commit_message string yes 커밋 메시지.
content string yes 파일 내용.
file_path string yes URL 인코딩된 새 파일의 전체 경로. 예: lib%2Fclass%2Erb.
id integer or string yes 프로젝트의 ID 또는 URL 인코딩된 경로.
author_email string no 커밋 작성자의 이메일 주소.
author_name string no 커밋 작성자의 이름.
encoding string no 인코딩을 base64로 변경합니다. 기본값은 text입니다.
execute_filemode boolean no 파일의 execute 플래그를 활성화 또는 비활성화합니다. true 또는 false가 될 수 있습니다.
start_branch string no 새 브랜치를 생성할 기본 브랜치의 이름. 
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": "새 파일 생성"}' \
  --url "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 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": "내용", "commit_message": "파일 업데이트"}' \
  --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은 오류를 지정하지 못하도록 하는 부울 반환 코드가 있습니다.

저장소에서 기존 파일 삭제

단일 파일을 삭제합니다. 단일 요청으로 여러 파일을 삭제하려는 경우 커밋 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": "파일 삭제"}' \
  --url "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"