Home

Awesome

publib

Previously known as jsii-release

A unified toolchain for publishing libraries to popular package managers.

Supports:

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.

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:

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):

OptionRequiredDescription
NPM_TOKENOptionalRegistry authentication token (either npm.js publishing token or a GitHub personal access token), not used for AWS CodeArtifact
NPM_REGISTRYOptionalThe 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_TAGOptionalRegisters the published package with the given dist-tag (e.g. next, default is latest)
NPM_ACCESS_LEVELOptionalPublishes the package with the given access level (e.g. public, default is restricted for scoped packages and public for unscoped packages)
AWS_ACCESS_KEY_IDOptionalIf AWS CodeArtifact is used as registry, an AWS access key can be spedified.
AWS_SECRET_ACCESS_KEYOptionalSecret access key that belongs to the AWS access key.
AWS_ROLE_TO_ASSUMEOptionalIf AWS CodeArtifact is used as registry, an AWS role ARN to assume before authorizing.
DISABLE_HTTPSOptionalConnect 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):

OptionRequiredDescription
MAVEN_USERNAME and MAVEN_PASSWORDYesUsername 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_PASSPHRASEYes for Maven CentralGPG private key or file that includes it. This is used to sign your Maven packages. See instructions below
MAVEN_STAGING_PROFILE_IDYes for Maven CentralMaven 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_ENDPOINTYes for new Maven Central usersURL of Nexus repository. Defaults to https://oss.sonatype.org. Use https://s01.oss.sonatype.org if you are a new user.
MAVEN_SERVER_IDNoUsed in maven settings for credential lookup (e.g. use github when publishing to GitHub). Defaults to ossrh for Maven Central.
MAVEN_REPOSITORY_URLNoDeployment repository when not deploying to Maven Central
MAVEN_DRYRUNNoSet 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):

OptionRequiredDescription
NUGET_API_KEYRequiredNuGet API Key with "Push" permissions
NUGET_SERVEROptionalNuGet Server URL (defaults to nuget.org)

Publish to GitHub Packages
You can publish to GitHub Packages instead, with the following options:

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):

OptionRequiredDescription
TWINE_USERNAMERequiredPyPI username (register)
TWINE_PASSWORDRequiredPyPI password
TWINE_REPOSITORY_URLOptionalThe 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:

Options (environment variables):

OptionRequiredDescription
GITHUB_TOKENRequired when not in SSH mode, see GIT_USE_SSHGitHub personal access token.
GIT_USE_SSHOptionalSet 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_SSHDeprecatedLegacy alias for GIT_USE_SSH.
GH_ENTERPRISE_TOKEN or<br>GITHUB_ENTERPRISE_TOKENOptionalCustom Authentication token for API requests to GitHub Enterprise.
GH_HOSTOptionalForce use of a different Hostname for GitHub Enterprise.
GITHUB_API_URLOptionalIf present, used to detect the GitHub instance to target. This is specified by default in GitHub Actions workflow and should not be set manually.
VERSIONOptionalModule version. Defaults to the value in the 'version' file of the module directory. Fails if it doesn't exist.
GIT_BRANCHOptionalBranch to push to. Defaults to 'main'.
GIT_USER_NAMEOptionalUsername to perform the commit with. Defaults to the git user.name config in the current directory. Fails if it doesn't exist.
GIT_USER_EMAILOptionalEmail to perform the commit with. Defaults to the git user.email config in the current directory. Fails if it doesn't exist.
GIT_COMMIT_MESSAGEOptionalThe commit message. Defaults to 'chore(release): $VERSION'.
DRYRUNOptionalSet 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

License

Released under the Apache 2.0 license.