Configure Package Firewall credentials for CI/CD

When you resolve dependencies with Package Firewall configured as your index, your package manager writes the Package Firewall URL for your namespace into the lockfile. Every package then resolves through Endor Labs instead of the canonical registry. Installs that replay that lockfile need Package Firewall credentials, so pipeline commands such as npm ci, uv sync --locked, and poetry install return 401 Unauthorized until you supply them. Store your Package Firewall credentials as CI/CD secrets, then configure each package manager client to read them from environment variables. Your pipelines authenticate without committing credentials to your repository.

​

Before you begin

Make sure you have the following:

• A Package Firewall API key and API secret. See Configure the Package Firewall with direct integration to create them.
• A package manager configuration file that points at Package Firewall. See Configure the Package Firewall with direct integration to generate one with the configuration wizard.

​

Store Package Firewall credentials as CI/CD secrets

Store your Package Firewall API key and API secret as secrets in your CI/CD system, such as repository or runner secrets. Expose them to pipeline jobs as environment variables. Don’t write credentials directly in pipeline steps or commit them to your repository. The following table maps each package manager configuration file to the environment variables it reads. The uv and Poetry variable names derive from the endor-firewall index or source name used in the following sections. To store secrets and map them to environment variables, refer to the documentation for your CI/CD system, for example GitHub Actions, GitLab CI/CD, Azure DevOps, CircleCI, Jenkins, or Harness.

​

Configure uv for CI/CD

When you run uv lock with Package Firewall configured, uv writes the firewall URL, including your namespace, into uv.lock. Every package resolves through Endor Labs instead of a canonical PyPI source. Since the lockfile references authenticated firewall URLs, reproducible installs fail in CI/CD when credentials to factory.endorlabs.com are absent. uv commands that require a connection to the lockfile URLs, such as uv sync --locked or uv sync --frozen, return 401 Unauthorized unless credentials are provided. To install from the lockfile in CI/CD without committing credentials to your repository, give your index a name and pass the credentials as environment variables.

1. In your existing uv index in pyproject.toml or uv.toml, add a name and remove the credentials from the URL. uv matches credentials to an index by this name.
   pyproject.toml

   [[tool.uv.index]]
   name = "endor-firewall"
   url = "https://factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/pypi/simple/"
   default = true
   

   uv.toml

   [[index]]
   name = "endor-firewall"
   url = "https://factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/pypi/simple/"
   default = true
   
2. In your CI/CD system, store the credentials as secrets and expose them to jobs as the following environment variables. uv derives the variable names from the index name in uppercase, so endor-firewall becomes ENDOR_FIREWALL. For more information, refer to the uv environment variable reference.
   • UV_INDEX_ENDOR_FIREWALL_USERNAME: Your Package Firewall API key.
   • UV_INDEX_ENDOR_FIREWALL_PASSWORD: Your Package Firewall API secret.

​

Configure npm for CI/CD

When you run npm install with Package Firewall configured, npm writes the firewall URL, including your namespace, into package-lock.json. Every package resolves through Endor Labs instead of a canonical npm registry. Since the lockfile references firewall URLs, reproducible installs fail in CI/CD when credentials to factory.endorlabs.com are absent. Commands that install from the lockfile, such as npm ci, return 401 Unauthorized unless credentials are provided. To install from the lockfile in CI/CD without committing credentials to your repository, keep the registry URL in .npmrc and pass the encoded credentials as an environment variable.

1. In the project .npmrc file, set the Package Firewall registry and read _auth from an environment variable.
   registry=https://factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/npm/
   //factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/npm/:_auth=${NPM_AUTH}
   always-auth=true
   
2. Generate the Base64 encoding of <api-key>:<api-secret> with your Package Firewall API key and API secret. This is the same encoding as the configuration wizard.
   printf '%s' "<api-key>:<api-secret>" | base64 | tr -d '\n'; echo
   
3. In your CI/CD system, store the encoded value as a secret and expose it to jobs as the NPM_AUTH environment variable. For more information, refer to the npm CI/CD documentation.

​

Configure pnpm for CI/CD

pnpm reads the same .npmrc registry as npm. When that file points at Package Firewall, pnpm install and pnpm add go through Endor Labs. By default, pnpm-lock.yaml stores integrity hashes and does not store tarball URLs. Set the same .npmrc credentials in CI/CD as you do for npm. See Configure npm for CI/CD to set NPM_AUTH. Commands such as pnpm install --frozen-lockfile then resolve through Package Firewall. If the lockfile-include-tarball-url setting is true, pnpm writes Firewall tarball URLs into pnpm-lock.yaml. Reproducible installs then return 401 Unauthorized when credentials to factory.endorlabs.com are absent.

​

Configure Poetry for CI/CD

When you run poetry lock with Package Firewall set as a source, Poetry writes the Firewall URL, including your namespace, into poetry.lock. Every package resolves through Endor Labs instead of a canonical PyPI source. Since the lockfile references firewall URLs, reproducible installs fail in CI/CD when credentials to factory.endorlabs.com are absent. Commands that install from the lockfile, such as poetry install, return 401 Unauthorized unless credentials are provided. To install from the lockfile in CI/CD without committing credentials to your repository, keep the source URL in pyproject.toml and pass the credentials as environment variables.

1. In pyproject.toml, add the Package Firewall source with a name and no credentials in the URL. Poetry matches credentials to a source by this name.
   [[tool.poetry.source]]
   name = "endor-firewall"
   url = "https://factory.endorlabs.com/v1/namespaces/<your-namespace>/firewall/pypi/simple/"
   priority = "primary"
   
2. In your CI/CD system, store the credentials as secrets and expose them to jobs as the following environment variables. Poetry derives the variable names from the source name in uppercase, so endor-firewall becomes ENDOR_FIREWALL. For more information, refer to the Poetry repositories documentation.
   • POETRY_HTTP_BASIC_ENDOR_FIREWALL_USERNAME: Your Package Firewall API key.
   • POETRY_HTTP_BASIC_ENDOR_FIREWALL_PASSWORD: Your Package Firewall API secret.

​

Next steps

• Configure which packages the firewall flags and how it responds. See Package Firewall policy to learn more.
• Review the events the firewall records. See View Package Firewall logs to learn more.