Draft: Adding Secure Files API
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 Files 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
-
A local personal access token will be needed to execute any of the API requests
-
With a local personal access token, the API examples above can be used to validate this change.
MR acceptance checklist
This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.
-
I have evaluated the MR acceptance checklist for this MR.
Related to #346290 (closed)