296

How do I list a private Github repo as a "dependency" in package.json? I tried npm's Github URLs syntaxes like ryanve/example, but doing npm install in the package folder gives "could not install" errors for the private dependencies. Is there a special syntax (or some other mechanism) for depending on private repos?

8 Answers 8

419

It can be done via https and oauth or ssh.

https and oauth: create an access token that has "repo" scope and then use this syntax:

"package-name": "git+https://<github_token>:[email protected]/<user>/<repo>.git"

or

ssh: setup ssh and then use this syntax:

"package-name": "git+ssh://[email protected]:<user>/<repo>.git"

(note the use of colon instead of slash before user)

23
  • 24
    Or if you have ssh set up at github, skip the token and use: "<package>": "git+ssh://[email protected]/<user>/<repo>.git
    – steveax
    Commented Feb 26, 2015 at 4:50
  • 7
    How do you have it always on to the latest release? Commented Jun 23, 2016 at 14:19
  • 31
    Add #master to the end Commented Jul 19, 2016 at 20:45
  • 6
    "package-name": "git+https://<github_token>:[email protected]/<user>/<repo>.git" did not work for me. Surprisingly switching token and x-oauth-basic did the job. So, "package-name": "git+https://x-oauth-basic:<github_token>@github.com/<user>/<repo>.git" works for me. please note that I am on gitlab and not github. Commented Jan 6, 2018 at 13:45
  • 6
    Over https putting x-oauth-basic as the username is not necessary: "package-name": "git+https://<github_token>@github.com/<user>/<repo>.git" works as well.
    – kadam
    Commented Sep 21, 2018 at 2:48
37

NPM without access token in repo

This method requires anyone who uses the package to authenticate with their own personal access token rather than a single group token, which allows the repo to be free of access tokens. You also don't need to create a new access token every time a user should no longer be granted access, instead, removing a user from the repo in GitHub will automatically remove their package access.

This is a condensed version of GitHub's NPM guide: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry


Publish Your GitHub Repo as an NPM Package

  1. Create a personal access token in developer settings: https://github.com/settings/tokens
  2. Login to NPM
npm login --scope=@<USERNAME of repo owner in lowercase> --registry=https://npm.pkg.github.com

Username: <Your personal GitHub username>
Password: <Create a GitHub Access Token with your account and paste it here>
Email: <Email associated with the same account>

For example: where user @Bobby wants to publish github.com/Jessica/my-npm-package as an NPM package

npm login --scope=@jessica --registry=https://npm.pkg.github.com

Username: bobby
Password: yiueytiupoasdkjalgheoutpweoiru
Email: [email protected]
  1. Update the package.json, following the format below.
  "name": "@jessica/my-npm-package",
  "repository": "git://github.com/jessica/my-npm-package.git",
  "publishConfig": {
    "registry":"https://npm.pkg.github.com"
  },
  1. To publish the NPM package, run:
npm publish

Install a Private NPM Package in a Project

  1. Login to NPM in the same exact way as step 2 above.
  2. Install the package with npm install @jessica/my-npm-package

Done!

Keep reading if your project will have GitHub Actions scripts that need to install this private NPM package.


GitHub Actions: How to Install a Private NPM Package

In a CI environment, you'll also need npm login to similarly authenticate. Otherwise, npm install will fail, since it doesn't have access to the private NPM package. One way to pre-configure this is to use a .npmrc file; however, this commits auth credentials to the repo with that file. So, another way is to use the NPM tool npm-cli-login. There is a requirement that you either use your own personal access token (not optimal: you leave the repo, CI breaks), or set up a GitHub account specifically for CI and create an access token with that account.

  1. Create an access token with a CI-only GitHub account or grab an access token from your own GitHub account.
  2. Add that access token to your repo as a "secret", in the repo settings.
  3. Update your GitHub Actions workflow script to run this step AFTER you install NPM and BEFORE you run npm install:
- name: Login to GitHub private NPM registry
  env:
    CI_ACCESS_TOKEN: ${{ secrets.NAME_OF_YOUR_ACCESS_TOKEN_SECRET }}
  shell: bash
  run: |
    npm install -g npm-cli-login
    npm-cli-login -u "USERNAME" -p "${CI_ACCESS_TOKEN}" -e "EMAIL" -r "https://npm.pkg.github.com" -s "@SCOPE"
        

Replace NAME_OF_YOUR_ACCESS_TOKEN_SECRET, USERNAME, EMAIL and SCOPE.

For example

- name: Login to GitHub private NPM registry
  env:
    CI_ACCESS_TOKEN: ${{ secrets.MY_TOKEN }}
  shell: bash
  run: |
    npm install -g npm-cli-login
    npm-cli-login -u "ci-github-account" -p "${CI_ACCESS_TOKEN}" -e "[email protected]" -r "https://npm.pkg.github.com" -s "@jessica"

Done!

Now when GitHub Actions later run npm install, the script will have access to the private NPM package.

FYI: If you're familiar with GitHub Actions, you may ask why can't we use secrets.GITHUB_TOKEN which GitHub automatically supplies? The reason is secrets.GITHUB_TOKEN only has access to the repo that is running the GitHub Actions, it does not have access to the repo of the private NPM package.

1
  • 4
    This is a guide to install a dependency from GitHub Package Registry, not from a GitHub repository
    – Simon Tran
    Commented Mar 12 at 20:56
29

If someone is looking for another option for Git Lab and the options above do not work, then we have another option. For a local installation of Git Lab server, we have found that the approach, below, allows us to include the package dependency. We generated and use an access token to do so.

$ npm install --save-dev https://git.yourdomain.com/userOrGroup/gitLabProjectName/repository/archive.tar.gz?private_token=InsertYourAccessTokenHere

Of course, if one is using an access key this way, it should have a limited set of permissions.

Good luck!

0
19

With git there is a https format

https://github.com/equivalent/we_demand_serverless_ruby.git

This format accepts User + password

https://bot-user:[email protected]/equivalent/we_demand_serverless_ruby.git

So what you can do is create a new user that will be used just as a bot, add only enough permissions that he can just read the repository you want to load in NPM modules and just have that directly in your packages.json

 Github > Click on Profile > Settings > Developer settings > Personal access tokens > Generate new token

In Select Scopes part, check the on repo: Full control of private repositories

This is so that token can access private repos that user can see

Now create new group in your organization, add this user to the group and add only repositories that you expect to be pulled this way (READ ONLY permission !)

You need to be sure to push this config only to private repo

Then you can add this to your / packages.json (bot-user is name of user, xxxxxxxxx is the generated personal token)

// packages.json


{
  // ....
    "name_of_my_lib": "https://bot-user:[email protected]/ghuser/name_of_my_lib.git"
  // ...
}

https://blog.eq8.eu/til/pull-git-private-repo-from-github-from-npm-modules-or-bundler.html

2
  • 1
    So, is it safe to commit this personal access token, and use it in something like Travis CI? Commented Nov 30, 2018 at 18:33
  • @ConAntonakos if the project is a Github private repository and you have paid Travis CI that is running your private Github project repository then yes (kindof, as you are not sharing your credentials publicly) Also thing to rememmber is that you need to create and use credentials of new Github user that has only read access to this private repo. So don't use your personal account :) ...create a bot user account that is easier to lock in case of exposure ;) ... If you are building a bank project this will not pass ISO accreditation so then no it's never secure not even store code on GH Commented Dec 11, 2018 at 11:38
10

As of April 2023, the only thing that worked for me using github repo was:

npm install https://oauth2:<your-fine-grained-token>@github.com/owner/repo.git

or if you want to specify the branch:

npm install https://oauth2:<your-fine-grained-token>@github.com/owner/repo.git#master

for example:

npm install https://oauth2:github_pat_51BR4Zf222bFXEXgW0dg3O_Kdfh5dghIFHJUPOTJYdB4ahsqe607ewCaynCLRu3aAINOKhrUk42HsUd@github.com/facebook#master

You can create your token here: https://github.com/settings/tokens?type=beta Read-only permissions are enough for installing and using the repo.

2
  • 3
    This worked for me. For anyone wondering, the scope of my fine grained access token was "Contents" Read Only and "Metadata" Read Only, and this was to a single package.
    – tennantje
    Commented May 24, 2023 at 4:13
  • I thought you meant oauth2 literally. I eventually replaced it with my username and it worked right away, even though the repo was under a github organisation.
    – o-o
    Commented Aug 23, 2023 at 15:15
8

I wasn't able to make the accepted answer work in a Docker container.

What worked for me was to set the Personal Access Token from GitHub in a file called .netrc

ARG GITHUB_READ_TOKEN
RUN echo -e "machine github.com\n  login $GITHUB_READ_TOKEN" > ~/.netrc 
RUN npm install --only=production --force \
  && npm cache clean --force
RUN rm ~/.netrc

in package.json

"my-lib": "github:username/repo",
5

Although this is an old question, adding an answer here which works across platforms.

The general npm v7 syntax to access private repositories in node_modules is -

git+https://<token_name>:<token>@<path_to_repository>.git#<commit>

You will have to create an access token with your git service provider with atleast read access.

Following are links for most popular platforms :

Do note github creates token linked to your username and there is no token name, thus, use your username instead of token_name for github.

1
  • 3
    I can’t get this to work for a private module on Github using above syntax. The npm install fails saying the repo doesn’t exist. However when I copy and paste the url directly from the error message, it loads successfully in the browser, so it definitely exists! Also tried without token name, just the token, doesn’t work either.
    – vy218
    Commented Feb 3, 2022 at 9:23
1

You would need to generate the personal access token and then use them as your password when you login npm.

npm login --scope=@dave --registry=https://npm.pkg.github.com
username: ${github_username}
password: ${personal_access_token}
Email: ${public_email}

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.