What are gitlab uploads and what should they be used for?

Question

I followed the official gitlab documentation to upload files to a gitlab project

  curl -s --request POST \
  --header "Private-Token: ${MY_ACCESS_TOKEN}" \
  --form "[email protected]" \
  "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/uploads"

This works fine and I can download the files from the browser via the URL provided in the response. However, I have multiple questions about this approach:

• What should uploads be used for in comparison to job artifacts? Is it preferable to use uploads over artifacts to store e.g. compiled releases from a build stage?
• How can I manage (list, delete) all the uploads I have made for a project?

I can't really find sufficient information on the web to answer these questions.

Answer 1

The projects upload API is used for uploading files referenced in issue and MR descriptions, comments, etc. This is useful, for example, if you build a custom GitLab client (like a CLI tool or desktop app) and you want that tool to make comments that reference file uploads, similar to how you can upload files when making comments using the GitLab web UI client.

What should uploads be used for in comparison to job artifacts? Is it preferable to use uploads over artifacts to store e.g. compiled releases from a build stage?

I would not recommend using project uploads for anything related to job artifacts. For things like compiled releases, you should use a package registry, such as the generic package registry.

One reason for this is that you can actually manage (delete, change visibility of, create access tokens, etc.) the files in a package registry or the registry itself. Access tokens can be given specific scopes for package registries, but not for user uploads, for example. User uploads also have a, more or less, fixed security policy which may not be what you want (now or in the future).

On the whole, it's probably not a good idea to use project uploads for anything other than issue and MR descriptions or comments.

How can I manage (list, delete) all the uploads I have made for a project?

Since GitLab 15.3, project owners/maintainers can use the GraphQL endpoint to list/delete uploads.

Answer 2

That endpoint is used when you attach a file in a comment/description of a merge request. That's also what the documentation indicates:

Uploads a file to the specified project to be used in an issue or merge request description, or a comment.

You can see this yourself when attaching a file. The browser will make a POST request to this endpoint and then include the URL in the Markdown of your comment.

To answer your question: I don't think this should be used within a CI job, unless your CI job adds a comment to a merge request with the attached file.

---

Managing uploads

There's a short summary on the Uploads administration doc page about how those files are handled. In short, there's not really a way to manage them at all, besides deleting the parent project/group.

Attachments added to comments or descriptions are deleted only when the parent project or group is deleted. Attachments remain in file storage even when the comment or resource (like issue, merge request, epic) where they were uploaded is deleted.