Dependency Firewall API

Use this API to interact with the Dependency Firewall for a project. The Dependency Firewall blocks packages that do not meet a project’s security policies before they are fetched.

Retrieve status of Dependency Firewall for a project

Retrieves the status of Dependency Firewall for a specified project. Use this endpoint to determine whether to skip the firewall for an entire run. Projects with the firewall turned off return a successful response rather than 404 Not Found, so you can tell them apart from projects you cannot access.

This endpoint accepts a personal access token, project access token, group access token, OAuth token, or CI/CD job token. Deploy tokens are not supported. Unauthenticated requests are refused, including for public projects.

A CI/CD job token needs no particular fine-grained permission. What constrains it is the project its job runs in: a job token can only check that project. A request for any other project is refused with 403 Forbidden, even when the target project allows the job’s project in its inbound job token allowlist, and regardless of which fine-grained permissions that allowlist entry grants. One project’s firewall status is not information another project’s pipeline needs.

Prerequisites:

• You must have permission to read the project.

GET /projects/:id/dependency_firewall/enablement

Supported attributes:

If successful, returns 200 OK and the following response attributes:

Possible response codes:

While the feature flag is off, the endpoint returns 404 rather than 200, because the endpoint is not generally available yet. A 404 response therefore means one of three things, and a client tells them apart by which key the response body uses, not by the wording of the text:

• A body with an enabled key, such as {"enabled": false}, means the feature flag is off for this project. The firewall is not active, so a client can skip it for the run.
• A body with an error key, such as {"error":"404 Not Found"}, means this endpoint does not exist on the instance. For example, the instance might run GitLab Community Edition, or a version released before this endpoint was added. A client should fall back to its previous behavior instead of reporting a configuration problem.
• A body with a message key means the endpoint exists and refused the request. The project either does not exist or you cannot read it. A client should report a configuration problem and must not treat the project as unprotected.

Do not key this decision on the message text. A caller whose project is unreadable gets {"message":"404 Project Not Found"}, but a fine-grained token that lacks access to the project gets {"message":"404 Not Found"}, which reads the same as the endpoint-missing case if you compare only the wording.

Example request:

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

Example response:

{
  "enabled": true
}

To authenticate from a pipeline job, use a CI/CD job token with the JOB-TOKEN header:

curl --request GET \
  --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
  --url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/enablement"