> 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/community-tier.md).

# Community Tier

{% hint style="info" %}
Free for **public repositories** on GitHub-hosted runners, as part of the Community Tier. Requires Harden-Runner v2.23.0 or later.
{% endhint %}

Add one input to Harden-Runner, and every npm install in the job goes through StepSecurity Secure Registry. Secure Registry checks each package request before it reaches your build. It refuses known compromised versions and, by default, hides versions published in the last 2 days, so a malicious release is usually discovered and removed before your pipeline downloads it.

StepSecurity hosts and operates the registry, so there is no infrastructure to deploy. Your `npm`, `pnpm` and `bun` commands stay the same.

The Community Tier supports the JavaScript ecosystem: npm, pnpm and Bun, with partial coverage for Yarn 1. See [Package manager coverage](https://docs.stepsecurity.io/packages/secure-registry/community-tier/coverage-and-limitations.md#package-manager-coverage). Support for more ecosystems is planned.

### What you get

* **Compromised Packages:** versions that the StepSecurity Security Operations Center (SOC) flags as compromised or malicious are refused at install time. This control is always on.
* **Cooldown Period:** versions published less than 2 days ago are hidden, so the package manager picks the newest version that has passed the cooldown. Most malicious releases are found and removed within that window.
* **Custom Block List:** optionally refuse specific packages or versions in your workflow.
* **Job summary:** every version that was held or blocked in the job, with a ready-to-paste snippet to allow a specific held version.
* **Run insights:** the packages each job pulled through Secure Registry, on the **Packages** tab of the workflow run in the StepSecurity dashboard.
* **No workflow rewrite:** Harden-Runner points your package manager at Secure Registry for the length of the job only.

### How it works

* **Step 1:** When the job starts, Harden-Runner requests a Secure Registry session for the job. The session issues a short-lived token that works for this job only.
* **Step 2:** Harden-Runner writes an npm configuration file in the runner's temporary directory and points npm at it through `NPM_CONFIG_USERCONFIG`. Your repository's files and the runner's global npm configuration stay unchanged.
* **Step 3:** Package managers that read npm configuration send their package metadata and tarball requests to Secure Registry. Secure Registry evaluates each request against the job's settings and returns, filters or refuses it.
* **Step 4:** When the job ends, Harden-Runner writes held and blocked versions to the job summary, checks whether npm was pointed at another registry during the job, and revokes the session token.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FZVnKH8NpDAKUokEdeTf0%2Fsecure-registry-community-how-it-works.png?alt=media&amp;token=6094b6a0-2472-4efb-a368-6d02c830d7f6" alt=""><figcaption></figcaption></figure>

### Requirements

| Requirement     | Detail                                                                                                                                                                                     |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Repository**  | Public. Private and internal repositories require the Enterprise Tier.                                                                                                                     |
| **Owner**       | An organization or user without a StepSecurity subscription. For subscribed organizations, the job stays on its normal registry and the step log shows a notice.                           |
| **Runner**      | GitHub-hosted runners on Linux, Windows and macOS, including `container:` jobs.                                                                                                            |
| **Action**      | `step-security/harden-runner` v2.23.0 or later with the `secure-registry` input, as the first step of the job.                                                                             |
| **Ecosystem**   | npm and npm-compatible clients. See [Package manager coverage](https://docs.stepsecurity.io/packages/secure-registry/community-tier/coverage-and-limitations.md#package-manager-coverage). |
| **Permissions** | `id-token: write` is optional and recommended.                                                                                                                                             |

Jobs that are not eligible never fail. Harden-Runner prints a notice that explains why and leaves npm on its default registry.

### Quick start

Set `secure-registry: true` on Harden-Runner and keep it as the first step of the job.

```yaml
name: CI
on: [push, pull_request]

permissions:
  contents: read
  id-token: write # optional, recommended

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: step-security/harden-runner@v2
        with:
          egress-policy: audit
          secure-registry: true

      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          # A restored dependency cache is never checked by Secure Registry.
          package-manager-cache: false
      - run: npm ci
      - run: npm test
```

Your install and test steps stay the same. `package-manager-cache: false` turns off the automatic npm cache in `actions/setup-node`, because packages restored from a cache skip Secure Registry. See [Dependency caches](https://docs.stepsecurity.io/packages/secure-registry/community-tier/coverage-and-limitations.md#dependency-caches).

The Harden-Runner step log shows the settings that were applied:

```
secure-registry session
  edition: community
  binding: oidc
  resolved config:
  {
    "npm": {
      "mode": "enforce",
      "cooldown": { "days": 2, "exemptions": [] },
      "compromised": true,
      ...
    }
  }
secure-registry: npm installs now go through https://community.registry.stepsecurity.io/javascript/
```

To turn it off, remove the input or set `secure-registry: false`.

{% hint style="info" %}
&#x20;`egress-policy` and Secure Registry are separate settings. With `egress-policy: audit`, Harden-Runner monitors network traffic without blocking it, and Secure Registry still blocks compromised and held package versions. To report package decisions without blocking, set the Secure Registry `mode` to `audit`. See [Configuration](https://docs.stepsecurity.io/packages/secure-registry/community-tier/configuration.md).
{% endhint %}

#### **Why `id-token: write` is recommended**

With `id-token: write`, GitHub signs a statement of your repository, its visibility and the runner type, and StepSecurity verifies it. Without it, the job reports this information itself, and Secure Registry still works.

|                                                          | With `id-token: write` | Without it                                                  |
| -------------------------------------------------------- | ---------------------- | ----------------------------------------------------------- |
| Packages go through Secure Registry                      | Yes                    | Yes                                                         |
| Compromised Packages, Cooldown Period, Custom Block List | Yes                    | Yes                                                         |
| Job summary                                              | Yes                    | Yes                                                         |
| Packages shown in run insights                           | Always                 | Only when Harden-Runner telemetry is reachable from the job |
| Attribution to your repository                           | Verified by GitHub     | Reported by the job                                         |

The permission only lets the job request a short-lived OpenID Connect (OIDC) identity token from GitHub. It has no effect on anything else in the job.

### Default settings

`secure-registry: true` applies these settings:

| Setting                  | Default   | Notes                                                                     |
| ------------------------ | --------- | ------------------------------------------------------------------------- |
| **Mode**                 | `enforce` | Held and blocked versions are refused.                                    |
| **Cooldown Period**      | 2 days    | Configurable from 0 to 30 days.                                           |
| **Compromised Packages** | On        | Always on. Cannot be turned off or exempted.                              |
| **Custom Block List**    | Off       | Turn it on by listing patterns.                                           |
| **Lockfile URLs**        | `keep`    | npm writes registry URLs into `package-lock.json` as usual.               |
| **Ecosystems**           | `all`     | Every supported ecosystem, including ones added later. Today this is npm. |

To change any of these, see [Configuration](https://docs.stepsecurity.io/packages/secure-registry/community-tier/configuration.md).

### What you see in a run

#### **Harden-Runner step log**

The settings that were applied, and a notice for anything that was ignored or adjusted, such as an unknown key or a cooldown value outside 0 to 30. When the job is not eligible, or a session could not be created, the notice or warning ends with `npm stays on the default registry.` and the job continues.

#### **npm output**

When versions of a package are hidden, npm prints a notice and installs the newest remaining version:

```
npm notice StepSecurity: 2 version(s) of example-pkg are hidden by your registry policy. cooldown (2 days): 11.0.7, 11.0.6. They may still be listed on the public registry.
```

#### **Job summary**

Harden-Runner writes a **Secure registry** section to the job summary when anything was held, blocked or would have been blocked:

* **Blocked:** versions whose download was refused, with the control and the details.
* **Held:** versions removed from the package metadata, so npm used an older version or failed with `ETARGET`. The reason says which control removed them, for example the Cooldown Period or Compromised Packages.
* **Would be blocked:** in `audit` mode, versions that would have been refused in `enforce` mode.
* **Exemption snippet:** a ready-to-paste `secure-registry` block that exempts versions held by the Cooldown Period. Versions blocked as compromised cannot be exempted.

Requests made in the last moments of the job may be missing from the job summary.

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FfZIIzqqKkYnzuQHFF7od%2Fsecure-registry-community-job-summary-1.png?alt=media&amp;token=26e80a5d-5805-4994-8050-1675d96c6b94" alt=""><figcaption></figcaption></figure>

Each table shows up to 5 rows. When there are more, a link opens the full list on the **Packages** tab of the run insights.

The post step also prints a one-line result in the Harden-Runner post step log, for example `secure-registry: 3 package(s) held, 1 version(s) blocked, see the job summary`.

#### **Run insights**

Open the insights link in the job summary and select the **Packages** tab. It lists the package requests the job made through Secure Registry, with one row per request:

* **Package:** the package and version.
* **Request Type:** `Metadata` for version lookups, `Tarball Download` for package downloads.
* **Status:** `Blocked` when the request was refused, `Modified` when versions were removed from the metadata (the job summary lists these as held).
* **Controls:** the control that acted, such as `Compromised`.
* **Verified Via:** how the request was tied to this job, for example `OIDC` when the job has `id-token: write`.

Only requests verified as coming from the job are shown. Use the **Status** and **Request Type** filters to narrow the list, and **Network Events** to see the registry hosts the job contacted, such as `community.registry.stepsecurity.io`.

{% hint style="info" %}
The **Packages** tab currently appears only for Community Tier runs that use Secure Registry.
{% endhint %}

<figure><img src="https://754495266-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQJRZY4cfEeY3I7DXTOCp%2Fuploads%2FlqO67Orpgvpz51hB2bPh%2Fsecure-registry-community-packages-tab.png?alt=media&amp;token=7a8ac4a9-c2f7-4a54-852e-8c71141d775c" alt=""><figcaption></figcaption></figure>

To see this in a live run, open this [example workflow run](https://github.com/step-community-org/int-tests/actions/runs/43761709796) and its [Packages tab](https://app.stepsecurity.io/github/step-community-org/int-tests/actions/runs/43761709796?tab=packages\&correlationId=ed061de1-18a2-42c5-8605-145e071e1e59):

* **`is-number@7.0.0`:** allowed.
* **`typescript@7.1.0-dev.20261115.1`:** held by the Cooldown Period.
* **`chalk@5.6.1`:** blocked as a known compromised package.

#### **Annotations**

The post step adds an annotation in two situations:

* **npm was pointed away from Secure Registry during the job:** for example by `actions/setup-node` with `registry-url: https://registry.npmjs.org`. Installs after that step were not checked.
* **A lockfile changed in the job contains Secure Registry URLs:** do not commit it as is, because installs that do not use this job's token fail with `E401`. Set `lockfile-resolved: omit` under `npm` if the job commits lockfiles.

### Compared with Secure Registry on the Enterprise Tier

Secure Registry applies the same controls on both tiers. The difference is where the policy lives and who can use it:

|                         | Community Tier                                       | Enterprise Tier                                                                                                                   |
| ----------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Who**                 | Public repositories on GitHub-hosted runners         | Any repository, runner, developer machine or artifact manager                                                                     |
| **How to turn it on**   | `secure-registry` input on Harden-Runner             | Point package clients at Secure Registry. See [Setup Guide](https://docs.stepsecurity.io/packages/secure-registry/setup-guide.md) |
| **Where policy is set** | In the workflow file, with StepSecurity defaults     | In the StepSecurity dashboard. See [Policy](https://docs.stepsecurity.io/packages/secure-registry/policy.md)                      |
| **Ecosystems**          | npm                                                  | npm, PyPI, Maven, NuGet, Go, RubyGems, Cargo and Packagist (PHP)                                                                  |
| **Where results show**  | Job summary and the **Packages** tab of run insights | [Policy Evaluations](https://docs.stepsecurity.io/packages/secure-registry/policy-evaluations.md), Inventory and Statistics       |

### Pull requests from forks and Dependabot

Pull requests from forks and Dependabot runs are covered. Fork pull requests never receive an identity token, so their attribution is reported by the job.

#### In this section

* [**Configuration**](https://docs.stepsecurity.io/packages/secure-registry/community-tier/configuration.md): the `secure-registry` input, Cooldown Period exemptions, Custom Block List and common scenarios.
* [**Coverage and limitations**](https://docs.stepsecurity.io/packages/secure-registry/community-tier/coverage-and-limitations.md): which package managers are covered, expected public registry calls, dependency caches and known incompatibilities.
* [**Troubleshooting**](https://docs.stepsecurity.io/packages/secure-registry/community-tier/troubleshooting.md): what to do for each install error and start-of-job notice.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stepsecurity.io/packages/secure-registry/community-tier.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
