Skip to content

Adding Secure Files API

Darby Frey requested to merge 346290-proposal-for-adding-binary-file-support-to-ci-variables-2 into master

What does this MR do and why?

This MR is a follow-up to !77886 (merged) to implement an API to interact with the Secure File model.

The Secure Files mechanism has been discussed here: #346290 (closed). I'm breaking down the original MR into smaller changes that should be easier to review. The original MR is here: !75695 (closed).

Screenshots or screen recordings

A recorded walkthrough of this whole feature is here: https://youtu.be/eK3FUskHfdo

APIs

Upload a Secure File

Secure Files can be uploaded via POST /projects/:id/secure_files with the name, file (5 MB limit) and optional permissions inputs. For example:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/secure_files --form "name=myfile.jks" --form "file=@/path/to/file/myfile.jks"

The response payload includes the file id, name, checksum, checksum_algorithm, and permissions.

{
  "id": 1,
  "name": "myfile.jks",
  "checksum": "16630b189ab34b2e3504f4758e1054d2e478deda510b2b08cc0ef38d12e80aac",
  "checksum_algorithm": "sha256",
  "permissions": "read_only"
}

List all Secure Files for a Project

A list of Secure Files for a project is returned via GET /projects/:id/secure_files. The response payload is similar to the above.

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/secure_files"

[{
  "id": 1,
  "name": "myfile.jks",
  "checksum": "16630b189ab34b2e3504f4758e1054d2e478deda510b2b08cc0ef38d12e80aac",
  "checksum_algorithm": "sha256",
  "permissions": "read_only"
}]

Get an individual Secure File

An individual Secure File is returned via GET /projects/:id/secure_files/:secure_file_id with a similar response payload.

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/secure_files/1"

{
  "id": 1,
  "name": "myfile.jks",
  "checksum": "16630b189ab34b2e3504f4758e1054d2e478deda510b2b08cc0ef38d12e80aac",
  "checksum_algorithm": "sha256",
  "permissions": "read_only"
}

Download a Secure File

A single Secure File can be downloaded via GET /projects/:id/secure_files/:secure_file_id/download. There is no JSON response for this endpoint, it simply returns the decrypted file content.

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/secure_files/1/download --output myfile.jks

Optionally, the checksum returned from the GET endpoint can be used to ensure the correctness of the downloaded file.

Delete an individual Secure File

An individual Secure File can be deleted via DELETE /projects/:id/secure_files/:secure_file_id

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/secure_files/1"

How to set up and validate locally

  1. A local personal access token will be needed to execute any of the API requests
  2. With a local personal access token, the API examples above can be used to validate this change
  3. There is a sample jks file that can be used for testing in spec/fixtures/ci_secure_files/upload-keystore.jks

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Related to #346290 (closed)

Merge request reports