@cryptotaxi247 / documentation
Code Commits Issues Pulls Sessions CI/CD
maitxn/version-bump-tar
@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 112 lines 5.29 KB
Raw
1 ---
2 title: Using private packages in a CI/CD workflow
3 redirect_from:
4 - /private-modules/ci-server-config
5 ---
6
7 You can use access tokens to test private npm packages with continuous integration (CI) systems, or deploy them using continuous deployment (CD) systems.
8
9 ## Recommended: Use trusted publishing for package publishing
10
11 For publishing packages from CI/CD workflows, we recommend using [trusted publishing](/trusted-publishers) instead of access tokens. Trusted publishing uses OpenID Connect (OIDC) to provide secure publishing that eliminates the security risks associated with long-lived tokens.
12
13 Trusted publishing is supported for:
14
15 - [GitHub Actions](https://github.com/features/actions) (GitHub-hosted runners)
16 - [GitLab CI/CD](https://docs.gitlab.com/ci/pipelines/) (GitLab.com shared runners)
17
18 If you use a different CI/CD provider, or if you need to install private packages (not publish), you can use access tokens as described below.
19
20 ## Create a new access token
21
22 Create a new access token that will be used only to access npm packages from a CI/CD server.
23
24 ### Continuous integration
25
26 When generating an access token for use in a continuous integration environment, we recommend using a granular access token with limited access to provide greater security.
27
28 For most CI workflows that only install dependencies and run tests, a **read-only** granular access token is sufficient and most secure.
29
30 <Note>
31
32 **Note:** If your CI workflow requires write operations (such as publishing test packages), you may need a granular access token with read and write permissions and bypass 2FA enabled to prevent automated workflows from being blocked by 2FA prompts. However, we strongly recommend using read-only tokens whenever possible and reserving bypass 2FA for deployment workflows only.
33
34 </Note>
35
36 <Note variant="danger">
37
38 **Warning:** Legacy access tokens are removed as of November 2025.
39
40 </Note>
41
42 For more information on creating granular access tokens, including CIDR-whitelisted tokens, see "[Creating and viewing access tokens][create-token]".
43
44 ### Continuous deployment
45
46 For publishing packages in continuous deployment environments, we strongly recommend using [trusted publishing](/trusted-publishers) when available, as it provides enhanced security without requiring token management.
47
48 If trusted publishing is not available for your CI/CD provider, you must create a [granular access token with bypass 2FA enabled][create-token] on the website. This will allow you to publish in your CI/CD workflows even if you have two-factor authentication enabled on your account.
49
50 <Note>
51
52 **Security considerations for bypass 2FA:**
53
54 - Only enable bypass 2FA when necessary for automated publishing workflows
55 - Use restrictive permissions and short expiration dates
56 - Consider IP address restrictions and regular token rotation
57 - Use trusted publishing instead of bypass 2FA tokens whenever possible
58
59 </Note>
60
61 ### Interactive workflows
62
63 If your workflow produces a package, but you publish it manually after validation, then you will want to create a granular access token with read and write permissions. See "[Creating and viewing access tokens][create-token]" for instructions.
64
65 ### CIDR whitelists
66
67 For increased security, you may use a CIDR-whitelisted granular access token that can only be used from a certain IP address range. You can configure IP address restrictions when creating your granular access token on the website.
68
69 For more information, see "[Creating and viewing access tokens][create-token]".
70
71 ## Set the token as an environment variable on the CI/CD server
72
73 Set your token as an environment variable, or a secret, in your CI/CD server.
74
75 For example, in GitHub Actions, you would [add your token as a secret](https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets). Then you can make the secret available to workflows.
76
77 If you named the secret `NPM_TOKEN`, then you would want to create an environment variable named `NPM_TOKEN` from that secret.
78
79 ```
80 steps:
81 - run: |
82 npm install
83 - env:
84 NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
85 ```
86
87 Consult your CI/CD server's documentation for more details.
88
89 ## Create and check in a project-specific .npmrc file
90
91 Use a project-specific `.npmrc` file with a variable for your token to securely authenticate your CI/CD server with npm.
92
93 1. In the root directory of your project, create a custom `.npmrc` file with the following contents:
94
95 ```
96 //registry.npmjs.org/:_authToken=${NPM_TOKEN}
97 ```
98
99 **Note:** that you are specifying a literal value of `${NPM_TOKEN}`. The npm cli will replace this value with the contents of the `NPM_TOKEN` environment variable. Do **not** put a token in this file.
100
101 2. Check in the `.npmrc` file.
102
103 ## Securing your token
104
105 Your token may have permission to read private packages, publish new packages on your behalf, or change user or package settings. Protect your token.
106
107 Do not add your token to version control or store it insecurely. Store it in a password manager, your cloud provider's secure storage, or your CI/CD provider's secure storage.
108
109 When possible, use granular access tokens with the minimum permissions necessary, and set short expiration dates for your tokens. For more information, see "[About access tokens][about-tokens]."
110
111 [create-token]: creating-and-viewing-access-tokens
112 [about-tokens]: about-access-tokens