@cryptotaxi247 / documentation-1
Code Commits Issues Pulls Sessions CI/CD
patch-1
@reggi/path-to-regexp dependabot/npm_and_yarn/main/copy-to-clipboard-4.0.2 dependabot/npm_and_yarn/main/eslint-10.4.0 dependabot/npm_and_yarn/main/npmcli/eslint-config-7.0.0 dependabot/npm_and_yarn/main/proc-log-7.0.0 dependabot/npm_and_yarn/npm_and_yarn-826852524d dependabot/npm_and_yarn/npm_and_yarn-ab9a7f4bc2 deprecate-totp-2fa dhei/classic-tokens gat-bypass-2fa-docs jpg619/fix-accessibility-content-flow jpg619/version-bump-tar-2 kartykp/gat-bypass-2fa-docs kartykp/upgrade-path-to-regex main maitxn/version-bump-tar patch-1 reggi/cache-based-on-version reggi/dev-engines reggi/fix-transform-prettier reggi/overrides update-search-sensitivity
mdx 206 lines 12 KB
Raw
1 ---
2 title: npm-trust
3 section: 1
4 description: Manage trusted publishing relationships between packages and CI/CD providers
5 github_repo: npm/cli
6 github_branch: latest
7 github_path: docs/lib/content/commands/npm-trust.md
8 redirect_from:
9 - /cli-commands/npm-trust
10 - /cli-commands/trust
11 - /cli-documentation/cli-commands/npm-trust
12 - /cli-documentation/cli-commands/trust
13 - /cli-documentation/commands/npm-trust
14 - /cli-documentation/commands/trust
15 - /cli-documentation/npm-trust
16 - /cli-documentation/trust
17 - /cli-documentation/v11/cli-commands/npm-trust
18 - /cli-documentation/v11/cli-commands/trust
19 - /cli-documentation/v11/commands/npm-trust
20 - /cli-documentation/v11/commands/trust
21 - /cli-documentation/v11/npm-trust
22 - /cli-documentation/v11/trust
23 - /cli/cli-commands/npm-trust
24 - /cli/cli-commands/trust
25 - /cli/commands/npm-trust
26 - /cli/commands/trust
27 - /cli/npm-trust
28 - /cli/trust
29 - /cli/v11/cli-commands/npm-trust
30 - /cli/v11/cli-commands/trust
31 - /cli/v11/commands/trust
32 - /cli/v11/npm-trust
33 - /cli/v11/trust
34 - /commands/npm-trust
35 - /commands/trust
36 ---
37
38 ### Synopsis
39
40 Note: This command is unaware of workspaces.
41
42 ### Prerequisites
43
44 Before using npm trust commands, ensure the following requirements are met:
45
46 - **npm version**: `npm@11.10.0` or above is required. Use `npm install -g npm@^11.10.0` to update if needed.
47 - **Write permissions on the package**: You must have write access to the package you're configuring.
48 - **2FA enabled on account**: Two-factor authentication must be enabled at the account level. Even if it's not currently enabled, you must enable it to use trust commands.
49 - **Supported authentication methods**: Granular Access Tokens (GAT) with the bypass 2FA option are not supported. Legacy basic auth (username and password) credentials will not work for trust commands or endpoints.
50 - **Package must exist**: The package you're configuring must already exist on the npm registry.
51
52 ### Description
53
54 Configure trust relationships between npm packages and CI/CD providers using OpenID Connect (OIDC). This is the command-line equivalent of managing trusted publisher configurations on the npm website.
55
56 For a comprehensive overview of trusted publishing, see the [npm trusted publishers documentation](https://docs.npmjs.com/trusted-publishers).
57
58 The `[package]` argument specifies the package name. If omitted, npm will use the name from the `package.json` in the current directory.
59
60 Each trust relationship has its own set of configuration options and flags based on the OIDC claims provided by that provider. OIDC claims come from the CI/CD provider and include information such as repository name, workflow file, or environment. Since each provider's claims differ, the available flags and configuration keys are not universal—npm matches the claims supported by each provider's OIDC configuration. For specific details on which claims and flags are supported for a given provider, use `npm trust <provider> --help`.
61
62 ### Permissions
63
64 When creating a trust relationship, you must specify at least one permission flag to indicate which operations the trusted publisher is allowed to perform:
65
66 - `--allow-publish`: Allows the trusted publisher to run `npm publish` for the package.
67 - `--allow-stage-publish`: Allows the trusted publisher to run `npm stage` for the package. The alias `--allow-staged-publish` is also accepted.
68
69 At least one of these flags is required when creating a trust configuration. You can specify both to grant both permissions.
70
71 ### Provider Options
72
73 The required options depend on the CI/CD provider you're configuring. Detailed information about each option is available in the [managing trusted publisher configurations](https://docs.npmjs.com/trusted-publishers#managing-trusted-publisher-configurations) section of the npm documentation. If a provider is repository-based and the option is not provided, npm will use the `repository.url` field from your `package.json`, if available.
74
75 Currently, the registry only supports one configuration per package. If you attempt to create a new trust relationship when one already exists, it will result in an error. To replace an existing configuration:
76
77 1. Use `npm trust list [package]` to view the ID of the existing trusted publisher
78 2. Use `npm trust revoke --id <id> [package]` to remove the existing configuration
79 3. Then create your new trust relationship
80
81 ### Bulk Usage
82
83 For maintainers managing a large number of packages, you can configure trusted publishing in bulk using bash scripting. Create a loop that iterates through package names and their corresponding configuration details, executing the `npm trust <provider>` command with the `--yes` flag for each package.
84
85 The first request will require two-factor authentication. During two-factor authentication, you'll see an option on the npm website to skip two-factor authentication for the next 5 minutes. Enabling this option will allow subsequent `npm trust <provider>` commands to proceed without two-factor authentication, streamlining the bulk configuration process.
86
87 We recommend adding a 2-second sleep between each call to avoid rate limiting. With this approach, you can configure approximately 80 packages within the 5-minute two-factor authentication skip window.
88
89 ### Configuration
90
91 ### `npm trust github`
92
93 Create a trusted relationship between a package and GitHub Actions
94
95 #### Synopsis
96
97 ```bash
98 npm trust github [package] --file [--repo|--repository] [--env|--environment] [--allow-publish] [--allow-stage-publish] [-y|--yes]
99 ```
100
101 #### Flags
102
103 | Flag | Default | Type | Description |
104 | --- | --- | --- | --- |
105 | `--file` | null | String (required) | Name of workflow file within a repositories .GitHub folder (must end in yaml, yml) |
106 | `--repository`, `--repo` | null | String | Name of the repository in the format owner/repo |
107 | `--environment`, `--env` | null | String | CI environment name |
108 | `--allow-publish` | false | Boolean | Allow npm publish for this trusted publisher configuration |
109 | `--allow-stage-publish`, `--allow-staged-publish` | false | Boolean | Allow npm stage publish for this trusted publisher configuration |
110 | `--dry-run` | false | Boolean | Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`. Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc. |
111 | `--json` | false | Boolean | Whether or not to output JSON data, rather than the normal output. \* In `npm pkg set` it enables parsing set values with JSON.parse() before saving them to your `package.json`. Not supported by all npm commands. |
112 | `--registry` | "https://registry.npmjs.org/" | URL | The base URL of the npm registry. |
113 | `--yes`, `-y` | null | null or Boolean | Automatically answer "yes" to any prompts that npm might print on the command line. |
114
115 ### `npm trust gitlab`
116
117 Create a trusted relationship between a package and GitLab CI/CD
118
119 #### Synopsis
120
121 ```bash
122 npm trust gitlab [package] --file [--project|--repo|--repository] [--env|--environment] [--allow-publish] [--allow-stage-publish] [-y|--yes]
123 ```
124
125 #### Flags
126
127 | Flag | Default | Type | Description |
128 | --- | --- | --- | --- |
129 | `--file` | null | String (required) | Name of pipeline file (e.g., .gitlab-ci.yml) |
130 | `--project` | null | String | Name of the project in the format group/project or group/subgroup/project |
131 | `--environment`, `--env` | null | String | CI environment name |
132 | `--allow-publish` | false | Boolean | Allow npm publish for this trusted publisher configuration |
133 | `--allow-stage-publish`, `--allow-staged-publish` | false | Boolean | Allow npm stage publish for this trusted publisher configuration |
134 | `--dry-run` | false | Boolean | Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`. Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc. |
135 | `--json` | false | Boolean | Whether or not to output JSON data, rather than the normal output. \* In `npm pkg set` it enables parsing set values with JSON.parse() before saving them to your `package.json`. Not supported by all npm commands. |
136 | `--registry` | "https://registry.npmjs.org/" | URL | The base URL of the npm registry. |
137 | `--yes`, `-y` | null | null or Boolean | Automatically answer "yes" to any prompts that npm might print on the command line. |
138
139 ### `npm trust circleci`
140
141 Create a trusted relationship between a package and CircleCI
142
143 #### Synopsis
144
145 ```bash
146 npm trust circleci [package] --org-id <uuid> --project-id <uuid> --pipeline-definition-id <uuid> --vcs-origin <origin> [--context-id <uuid>...] [--allow-publish] [--allow-stage-publish] [-y|--yes]
147 ```
148
149 #### Flags
150
151 | Flag | Default | Type | Description |
152 | --- | --- | --- | --- |
153 | `--org-id` | null | String (required) | CircleCI organization UUID |
154 | `--project-id` | null | String (required) | CircleCI project UUID |
155 | `--pipeline-definition-id` | null | String (required) | CircleCI pipeline definition UUID |
156 | `--vcs-origin` | null | String (required) | CircleCI repository origin in format 'provider/owner/repo' |
157 | `--context-id` | null | null or String (can be set multiple times) | CircleCI context UUID to match |
158 | `--allow-publish` | false | Boolean | Allow npm publish for this trusted publisher configuration |
159 | `--allow-stage-publish`, `--allow-staged-publish` | false | Boolean | Allow npm stage publish for this trusted publisher configuration |
160 | `--dry-run` | false | Boolean | Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`. Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc. |
161 | `--json` | false | Boolean | Whether or not to output JSON data, rather than the normal output. \* In `npm pkg set` it enables parsing set values with JSON.parse() before saving them to your `package.json`. Not supported by all npm commands. |
162 | `--registry` | "https://registry.npmjs.org/" | URL | The base URL of the npm registry. |
163 | `--yes`, `-y` | null | null or Boolean | Automatically answer "yes" to any prompts that npm might print on the command line. |
164
165 ### `npm trust list`
166
167 List trusted relationships for a package
168
169 #### Synopsis
170
171 ```bash
172 npm trust list [package]
173 ```
174
175 #### Flags
176
177 | Flag | Default | Type | Description |
178 | --- | --- | --- | --- |
179 | `--json` | false | Boolean | Whether or not to output JSON data, rather than the normal output. \* In `npm pkg set` it enables parsing set values with JSON.parse() before saving them to your `package.json`. Not supported by all npm commands. |
180 | `--registry` | "https://registry.npmjs.org/" | URL | The base URL of the npm registry. |
181
182 ### `npm trust revoke`
183
184 Revoke a trusted relationship for a package
185
186 #### Synopsis
187
188 ```bash
189 npm trust revoke [package] --id=<trust-id>
190 ```
191
192 #### Flags
193
194 | Flag | Default | Type | Description |
195 | --- | --- | --- | --- |
196 | `--id` | null | String (required) | ID of the trusted relationship to revoke |
197 | `--dry-run` | false | Boolean | Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`. Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc. |
198 | `--registry` | "https://registry.npmjs.org/" | URL | The base URL of the npm registry. |
199
200 ### See Also
201
202 - [npm publish](/cli/v11/commands/npm-publish)
203 - [npm token](/cli/v11/commands/npm-token)
204 - [npm access](/cli/v11/commands/npm-access)
205 - [npm config](/cli/v11/commands/npm-config)
206 - [npm registry](/cli/v11/using-npm/registry)