> 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** or **PyPI**); the credentials and integration steps update for the selected ecosystem.

<figure><img src="/files/Hs2BFMdC4XoMQyxKFT9Y" 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 (for example, `https://registry.stepsecurity.io/javascript`).
* **Username**: your tenant username.
* **API Key**: select **Primary** or **Secondary** from the dropdown and reveal or copy the key.

{% 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 and follow the in-app instructions:

* **JFrog Artifactory**: for teams that already proxy npm through Artifactory. Create a remote npm repository, set its upstream URL to your Secure Registry endpoint, and add your credentials as the repository authentication.
* **Google Artifact Registry**: for teams using GAR as their npm proxy.
* **Sonatype Nexus Repository**: for teams using Nexus as their npm proxy.
* **Direct npm (`.npmrc`)**: for teams without an artifact manager, configuring npm to point directly at Secure Registry.

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.