publib
v0.2.918
Published
Release jsii modules to multiple package managers
Downloads
21,891
Readme
publib
Previously known as
jsii-release
A unified toolchain for publishing libraries to popular package managers.
Supports:
- npm
- PyPI
- NuGet
- Maven
- Go (GitHub)
Usage
This is an npm module. You can install it using yarn add publib
or
npm install publib
. In most cases it will be installed as a devDependency
in your package.json
.
This tool expects to find a distribution directory (default name is dist
)
which contains "ready-to-publish" artifacts for each package manager.
dist/js/*.tgz
- npm tarballsdist/python/*.whl
- Python wheelsdist/nuget/*.nupkg
- Nuget packagesdist/java/**
- Maven artifacts in local repository structuredist/go/**/go.mod
- Go modules. Each subdirectory should have its own go.mod file.
Each publisher needs a set of environment variables with credentials as
described below (NPM_TOKEN
, TWINE_PASSWORD
etc).
Then:
publib
You can customize the distribution directory through publib DIR
(the
default is dist
)
This command will discover all the artifacts based on the above structure and will publish them to their respective package manager.
You can also execute individual publishers:
publib-maven
publib-nuget
publib-npm
publib-pypi
publib-golang
npm
Publishes all *.tgz
files from DIR
to npmjs, GitHub Packages or AWS CodeArtifact.
If AWS CodeArtifact is used as npm registry, a temporary npm authorization token is created using AWS CLI. Therefore, it is necessary to provide the necessary configuration settings, e.g. by passing access key ID and secret access key to this script.
Usage:
npx publib-npm [DIR]
DIR
is a directory with npm tarballs (*.tgz). Default is dist/js
.
Options (environment variables):
| Option | Required | Description |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NPM_TOKEN
| Optional | Registry authentication token (either npm.js publishing token or a GitHub personal access token), not used for AWS CodeArtifact |
| NPM_REGISTRY
| Optional | The registry URL (defaults to "registry.npmjs.org"). Use "npm.pkg.github.com" to publish to GitHub Packages. Use repository endpoint for AWS CodeAtifact, e.g. "my-domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my_repo/". |
| NPM_DIST_TAG
| Optional | Registers the published package with the given dist-tag (e.g. next
, default is latest
) |
| NPM_ACCESS_LEVEL
| Optional | Publishes the package with the given access level (e.g. public
, default is restricted
for scoped packages and public
for unscoped packages) |
| AWS_ACCESS_KEY_ID
| Optional | If AWS CodeArtifact is used as registry, an AWS access key can be spedified. |
| AWS_SECRET_ACCESS_KEY
| Optional | Secret access key that belongs to the AWS access key. |
| AWS_ROLE_TO_ASSUME
| Optional | If AWS CodeArtifact is used as registry, an AWS role ARN to assume before authorizing. |
| DISABLE_HTTPS
| Optional | Connect to the registry with HTTP instead of HTTPS (defaults to false). |
Maven
Publishes all Maven modules in the DIR
to Maven Central.
Note that if you signed up at SonaType after February 2021, you need to use this URL: https://s01.oss.sonatype.org
(announcement).
Usage:
npx publib-maven [DIR]
DIR
is a directory with a local maven layout. Default is dist/java
.
Options (environment variables):
| Option | Required | Description |
| ---------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MAVEN_USERNAME
and MAVEN_PASSWORD
| Yes | Username and password for maven repository. For Maven Central, you will need to Create JIRA account and then request a new project. Read the OSSRH guide for more details. |
| MAVEN_GPG_PRIVATE_KEY
or MAVEN_GPG_PRIVATE_KEY_FILE
and MAVEN_GPG_PRIVATE_KEY_PASSPHRASE
| Yes for Maven Central | GPG private key or file that includes it. This is used to sign your Maven packages. See instructions below |
| MAVEN_STAGING_PROFILE_ID
| Yes for Maven Central | Maven Central (sonatype) staging profile ID (e.g. 68a05363083174). Staging profile ID can be found in the URL of the "Releases" staging profile under "Staging Profiles" in https://oss.sonatype.org or https://s01.oss.sonatype.org if you are logged in (e.g. https://oss.sonatype.org/#stagingProfiles;68a05363083174
). |
| MAVEN_ENDPOINT
| Yes for new Maven Central users | URL of Nexus repository. Defaults to https://oss.sonatype.org
. Use https://s01.oss.sonatype.org
if you are a new user. |
| MAVEN_SERVER_ID
| No | Used in maven settings for credential lookup (e.g. use github
when publishing to GitHub). Defaults to ossrh
for Maven Central. |
| MAVEN_REPOSITORY_URL
| No | Deployment repository when not deploying to Maven Central |
| MAVEN_DRYRUN
| No | Set to "true" for a dry run |
How to create a GPG key?
Install GnuPG.
Generate your key:
$ gpg --full-generate-key
# select RSA only, 4096, passphrase
Your selected passphrase goes to MAVEN_GPG_PRIVATE_KEY_PASSPHRASE
.
Export and publish the public key:
gpg -a --export > public.pem
Go to https://keyserver.ubuntu.com/ and submit the public key.
You can use cat public.pem
and copy/paste it into the "Submit Key" dialog.
Export the private key:
gpg -a --export-secret-keys <fingerprint> > private.pem
Now, either set MAVEN_GPG_PRIVATE_KEY_FILE
to point to private.pem
or
export the private key to a single line where newlines are encoded as \n
and then assign it to MAVEN_GPG_PRIVATE_KEY
:
echo $(cat -e private.pem) | sed 's/\$ /\\n/g' | sed 's/\$$//'
Publish to GitHub Packages
An example GitHub Actions publish step:
- name: Publish package
run: npx -p publib publib-maven
env:
MAVEN_SERVER_ID: github
MAVEN_USERNAME: ${{ github.actor }}
MAVEN_PASSWORD: ${{ secrets.GITHUB_TOKEN }}
MAVEN_REPOSITORY_URL: "https://maven.pkg.github.com/${{ github.repository }}"
NuGet
Publishes all *.nupkg
to the NuGet Gallery.
Usage:
npx publib-nuget [DIR]
DIR
is a directory with Nuget packages (*.nupkg). Default is dist/dotnet
.
Options (environment variables):
| Option | Required | Description |
| --------------- | -------- | ------------------------------------------------------------------------------ |
| NUGET_API_KEY
| Required | NuGet API Key with "Push" permissions |
| NUGET_SERVER
| Optional | NuGet Server URL (defaults to nuget.org) |
Publish to GitHub Packages
You can publish to GitHub Packages instead, with the following options:
- Set
NUGET_SERVER
tohttps://nuget.pkg.github.com/[org or user]
. - Set
NUGET_API_KEY
to a token with write packages permissions. - Make sure the repository url in the project file matches the org or user used for the server
PyPI
Publishes all *.whl
files to PyPI.
Usage:
npx publib-pypi [DIR]
DIR
is a directory with Python wheels (*.whl). Default is dist/python
.
Options (environment variables):
| Option | Required | Description |
| ---------------------- | -------- | -------------------------------------------------------------- |
| TWINE_USERNAME
| Required | PyPI username (register) |
| TWINE_PASSWORD
| Required | PyPI password |
| TWINE_REPOSITORY_URL
| Optional | The registry URL (defaults to Twine default) |
Golang
Pushes a directory of golang modules to a GitHub repository.
Usage:
npx publib-golang [DIR]
DIR
is a directory where the golang modules are located (default is dist/go
). Modules can be located either in subdirectories, (e.g 'dist/go/my-module/go.mod')
or in the root (e.g 'dist/go/go.mod').
If you specify the VERSION
env variable, all modules will recieve that version, otherwise a version
file is expected to exist in each module directory.
Repository tags will be in the following format:
- For a module located at the root:
v${module_version}
(e.gv1.20.1
) - For modules located inside subdirectories:
<subdir-name>/v${module_version}
(e.gmy-module/v3.3.1
)
Options (environment variables):
| Option | Required | Description |
| ----------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GITHUB_TOKEN
| Required when not in SSH mode, see GIT_USE_SSH
| GitHub personal access token. |
| GIT_USE_SSH
| Optional | Set to a non-falsy value to use SSH with deploy keys or your private SSH key. Your system must ready to use the key as publib will not set it up. |
| GITHUB_USE_SSH
| Deprecated | Legacy alias for GIT_USE_SSH
. |
| GH_ENTERPRISE_TOKEN
orGITHUB_ENTERPRISE_TOKEN
| Optional | Custom Authentication token for API requests to GitHub Enterprise. |
| GH_HOST
| Optional | Force use of a different Hostname for GitHub Enterprise. |
| GITHUB_API_URL
| Optional | If present, used to detect the GitHub instance to target. This is specified by default in GitHub Actions workflow and should not be set manually. |
| VERSION
| Optional | Module version. Defaults to the value in the 'version' file of the module directory. Fails if it doesn't exist. |
| GIT_BRANCH
| Optional | Branch to push to. Defaults to 'main'. |
| GIT_USER_NAME
| Optional | Username to perform the commit with. Defaults to the git user.name config in the current directory. Fails if it doesn't exist. |
| GIT_USER_EMAIL
| Optional | Email to perform the commit with. Defaults to the git user.email config in the current directory. Fails if it doesn't exist. |
| GIT_COMMIT_MESSAGE
| Optional | The commit message. Defaults to 'chore(release): $VERSION'. |
| DRYRUN
| Optional | Set to "true" for a dry run. |
Publish to CodeArtifact for testing
This package contains the publib-ca
CLI tool which is intended to use to publish
packages to CodeArtifact for testing (in a pipeline, before publishing to the
actual public package managers).
Use the following commands:
publib-ca create [--no-gc] [--no-login]
creates a new CodeArtifact repository
with a random name, with upstreams configured for all supported public package
managers. By default this command runs the gc
and login
subcommands
automatically.
publib-ca login --repo NAME [--cmd COMMAND]
logs in to a CodeArtifact repository and prepares some files that configure package managers for use with this CodeArtifact repository. If --cmd
is given, the command is run in an environment
where all supported package managers have been configured for the given repository.
Otherwise, activate these settings in the current bash shell by running
source ~/.publib-ca/usage/activate.bash
. This will set some
environment variables and copy some files into the current directory. (Note: the
CodeArtifact repository used here does not have to be created using publib-ca create
. It
is fine if it already existed beforehand).
publib-ca gc
collects old repositories created using publib-ca create
.
publib-ca publish [--repo NAME] DIRECTORY
publishes all packages in the given
directory to the given repository. If --repo
is not given, the most recently
logged-into repository is used, if the login session is still valid.
Roadmap
- [X] GitHub Support: Maven
- [X] GitHub Support: NuGet
- [ ] CodeArtifact Support: Maven
- [ ] CodeArtifact Support: NuGet
- [ ] CodeArtifact Support: Python
License
Released under the Apache 2.0 license.