> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/packages/secure-registry/setup-guide.md).

# Setup Guide

The **Setup Guide** tab provides your credentials and step-by-step instructions to configure your package manager to proxy through Secure Registry. Once configured, the security controls set in the [Policy](/packages/secure-registry/policy.md) tab are applied to every request.

Use the **Registry** selector to choose an ecosystem (**npm**, **PyPI**, **Maven**, or **NuGet**). The credentials, the available integration paths, and the setup steps all change with the selected ecosystem.

{% hint style="info" %}
Maven and NuGet are in **Beta**, indicated by a badge next to each in the **Registry** selector.
{% endhint %}

<figure><img src="/files/VJpL17crdMR1TexhIyiS" alt=""><figcaption></figcaption></figure>

### Your credentials

The Setup Guide displays the credentials your clients need to authenticate to Secure Registry:

* **Registry URL**: the Secure Registry endpoint to use as your upstream, which differs per ecosystem.
* **Username**: your tenant username.
* **API Key**: select **Primary** or **Secondary** from the dropdown and reveal or copy the key.

| Ecosystem | Registry URL                                  |
| --------- | --------------------------------------------- |
| npm       | `https://registry.stepsecurity.io/javascript` |
| PyPI      | `https://registry.stepsecurity.io/python`     |
| Maven     | `https://registry.stepsecurity.io/java`       |
| NuGet     | `https://registry.stepsecurity.io/dotnet`     |

{% hint style="info" %}
Primary and Secondary API keys are supported so you can rotate without downtime: issue the Secondary, switch clients over, then rotate the Primary.
{% endhint %}

### Integration paths

Pick the path that matches how packages reach your environment, then follow the in-app instructions. Not every path is offered for every ecosystem.

| Integration path              | npm | PyPI        | Maven       | NuGet       |
| ----------------------------- | --- | ----------- | ----------- | ----------- |
| **JFrog Artifactory**         | Yes | Yes         | Yes         | Yes         |
| **Google Artifact Registry**  | Yes | Yes         | Yes         | Not offered |
| **Sonatype Nexus Repository** | Yes | Not offered | Yes         | Yes         |
| **AWS CodeArtifact**          | Yes | Not offered | Not offered | Not offered |
| **Direct**                    | Yes | Yes         | Yes         | Yes         |

* **Artifact repository managers** (JFrog Artifactory, Google Artifact Registry, Sonatype Nexus Repository, AWS CodeArtifact): for teams that already proxy packages through a manager. Create a remote repository, set its upstream URL to your Secure Registry endpoint, and add your credentials as the repository authentication. Your existing configuration stays unchanged; only the remote repository's upstream points to Secure Registry.
* **Direct**: for teams without an artifact manager, configuring the package client to point at Secure Registry itself.

On the **Direct** path, a **Package manager** selector switches the instructions to match your client:

| Ecosystem | Package manager options            |
| --------- | ---------------------------------- |
| npm       | npm (`.npmrc`)                     |
| PyPI      | pip                                |
| Maven     | Maven, Gradle                      |
| NuGet     | .NET CLI, NuGet CLI, Visual Studio |

{% hint style="info" %}
**JFrog Artifactory authentication differs by ecosystem.** For PyPI and Maven, enable **Token Authentication** so the Authorization header is sent as Bearer rather than Basic. For NuGet, enable **Force Authentication** instead. Follow the in-app instructions for the ecosystem you are configuring rather than reusing a previous setup.
{% endhint %}

The diagram below shows the request flow for the JFrog Artifactory path. Your existing Artifactory configuration stays unchanged; only the remote repository's upstream points to Secure Registry, where policy validation runs before requests reach the public npm registry. Each request is recorded in the Policy Evaluations log, attributed to the developer machine or CI job that made it.

<figure><img src="/files/Oy5SRTeW1SyXypvaz0hh" alt=""><figcaption></figcaption></figure>

After configuring, use the test sequence in the Setup Guide to confirm requests are flowing through Secure Registry.

### Setting up source attribution

Source attribution lets you trace each request in the [Policy Evaluations](/packages/secure-registry/policy-evaluations.md) log back to the developer machine or CI pipeline that made it. It is configured by appending an identifier suffix to your API key in the auth token. Attribution is optional: clients without a suffix still work, but their requests appear in the log without a source.

The token format is the API key, followed by `::`, followed by the identifier:

```
<your-api-key>::<IDENTIFIER>
```

#### Developer machines

To attribute requests to a developer machine, append the device serial ID using the `dev:` prefix:

```
npm config set //registry.stepsecurity.io/javascript/:_authToken "<your-api-key>::dev:<DEVICE-SERIAL-ID>"
```

In the Policy Evaluations log, these requests show a **Developer Machine** source, and the Source Identifier links to that device's page.

#### CI/CD pipelines (GitHub Actions)

To attribute requests to a specific pipeline run, store the API key as a secret and append a `gha:` identifier built from the workflow context. Store the key as a secret (for example, `STEPSECURITY_NPM_TOKEN`) rather than committing it:

```yaml
- name: Configure npm registry
  env:
    IDENTIFIER: "gha:${{ github.repository }}/${{ github.run_id }}/${{ job.check_run_id }}"
    NPM_TOKEN: ${{ secrets.STEPSECURITY_NPM_TOKEN }}
  run: |
    npm config set registry https://registry.stepsecurity.io/javascript
    npm config set //registry.stepsecurity.io/javascript/:_authToken "${NPM_TOKEN}::${IDENTIFIER}"

- name: Install dependencies
  run: npm ci
```

In the Policy Evaluations log, these requests show a **GitHub Actions** source, and the Source Identifier links to the corresponding Harden-Runner workflow run.

{% hint style="warning" %}
Never commit the raw API key. Use an environment variable or CI secret, as shown above.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.stepsecurity.io/packages/secure-registry/setup-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.