rush / publish-to-git

Publish private npm packages to Git repositories with npm publish semantics

publish-to-git

Publish private npm packages to Git repositories with npm publish semantics (uses same files as npm publish)

Default behavior takes the version from package.json, runs npm pack and then pushes the contents to an orphan tag v<VERSION> (for example v1.0.0). It's similar to how gh-pages works.

Such tags can be easily referenced to in package.json. It provides proper versioning to private Git npm packages along with an easy publish path that's compatible with npm.

Installation

npm install --save-dev publish-to-git

Requirements: node > 8.0.0 and git command being in the PATH.

Consumption of private Git NPM packages

For Github

"some-package": "reponame/repo#v1.0.0",
"some-package-with-semver": "reponame/repo#semver:^v1.0.0",

For Gitlab or BitBucket (use bitbucket:)

"some-package": "gitlab:reponame/repo#v1.0.0",
"some-package-with-semver": "gitlab:reponame/repo#semver:^v1.0.0",

For some other Git repo:

"some-package": "git+ssh://[email protected]:somerepo#v1.0.0",
"some-package-with-semver": "git+ssh://[email protected]:somerepo#semver:^v1.0.0",

Note: Installing from Github/Gitlab/Bitbucket seems to be more efficient due to the way it conditionally turns on shallow clone.

Usage

In package.json

"scripts": {
  "publish": "publish-to-git"
}

or run with npx:

# npx publish-to-git

See also a few options which may assist in your particular use case:

Options:
  --help     Show help [boolean]
  --version  Show version number [boolean]
  --remote   Git remote, may be remote name or full URL to the repo [default: "origin"]
  --tag      Tag name to which src will be published, for example: v1.2.3 - by default uses version from package.json
  --push     Push update to the git remote (pass --no-push to disable) [boolean] [default: "true"]
  --force    Override any existing tag on the remote as well as locally (git tag -f, git push -f) [boolean]

Examples:
  publish-to-git --tag v2.1.3 --no-push     # by default version from package.json is used
  publish-to-git --remote https://USER:[email protected]/USER/REPO
  publish-to-git --force    # useful in CI and when we want to override the same tag which triggered the build

Programmatic usage

const { publish } = require('publish-to-git');

const options = {
  tag: 'v1.0.0', // you can also provide version: '1.0.0' instead of tag
  push: { // set to false to not push
    remote: 'origin', // set to URL or remote name
    force: false, // set to true to force push
  }
};

publish(options).then(() => {
  console.log('Done');
});

Please see https://github.com/Rush/publish-to-git/blob/master/main.js for reference

Usage in Drone CI

This example assumes that the developer pushes a tag that's identical to the version in package json. CI will complete the build and override tag contents. If you find this approach ugly, you could push tags in form of build-v1.0.0 and then have publish-to-git publish using default options.

pipeline:
  # other pipelines here, like build etc.
  publish-to-git:
    commands:
      - git config --global user.email "admin@drone" # git will complain if these are not set
      - git config --global user.name "Drone CI"
      - npx publish-to-git --force # this will override existing tag with npm package contents
    when:
      event: tag

Quick note on semver with https

Older versions of npm prior to 6.0 had a bug with supporting semver git packages. It's no longer a problem since npm 6.0.

For automated publishing to Github ~/.netc and npm/git will automatically pick it up:

machine github.com
login <GITHUB_TOKEN>
password=x-oauth-basic

License

MIT

publish-to-git's Issues

Publish multiple tags

It would be great to be able to publish for multiple branches at once, to avoid double work like this:

"postpublish": "publish-to-git && publish-to-git --force --tag latest"

Note the goal of this example could also be achieved if one could publish both a tag and a branch (issue #5).

failing tests

It seems there is something failing on rushbase.

should do npm publish --dry-run first to run build scripts

to actually have npm publish semantics. Otherwise you can end up pushing a tag missing files that would come from build output

stdout maxBuffer Exceeded issue

Issues with temp remote

I was trying to use publish-to-git the following way

npx publish-to-git --tag v0.1.0 --force

and got the following error:

Command failed: git tag -f v0.1.0 tmp-7912hXj19g7JM1tP/master
fatal: Failed to resolve 'tmp-7912hXj19g7JM1tP/master' as a valid ref.

Upon inspection of the tmp repo that is created inside the tmp dir, I noticed that git creates a branch named main by default, not master anymore, which can be the cause of this issue. See this line.

node 16 breaks the npm install of a published package using publish-to-git

Probably due to the lack of a remote branch and HEAD, an npm ci fails when installing a package that is published with this util when using node 16. Apparently node 16 now uses @npmcli/git to install the package, and that code read the sha from the refs/heads which is undefined.

The error:

TypeError: Cannot read properties of undefined (reading 'sha')
npm WARN old lockfile     at clone (/Users/martijnlutgens/.nvm/versions/node/v16.14.2/lib/node_modules/npm/node_modules/@npmcli/git/lib/clone.js:57:37).

Publish (also) as a branch

It would be great to be able to make all tags form a branch, e.g. release.

Besides making it easier to overview the tags, it would let a client run npm install https://git.example.com/project#release to get the latest version.

Projects may even want this branch to be called master (and have the source in e.g. develop) so that npm install https://git.example.com/project would install the latest release, according to the npm docs:

If neither #<commit-ish> or #semver:<semver> is specified, then master is used.

Having a 'prepare' script causes trouble

If the package.json file defines a prepare script (e.g. to transpile source code), this will be correctly executed while packing and publishing. However, it will again be executed by the consumer that tries to install the package, which then most likely fails. In the npm docs:

prepare: Run both BEFORE the package is packed and published, on local npm install without any arguments, and when installing git dependencies

As a simple workaround, a publish-to-git user could use prepublish instead of prepare, which is almost the same except it is not executed when installing from a git dependency.

Perhaps publish-to-git could automatically remove the prepare script from package.json, or rename it to prepublish, or simply throw a warning when it is present.