elba dependencies can be hosted on registries, which are online package repositories which host packages (think crates.io or npm) that are associated with indices. The process of publishing a package involves multiple steps (some of which are handled for you).
Package registries are specified in the configuration of an index; for users, this means a registry can be added by just adding the corresponding package index. See the relevant reference docs for more details.
Before you can upload a package to a registry, you must be authenticated with that registry. Each package registry might do authentication in a slightly different way, but all authentication systems revolve around you being given an authentication token which can be used in the elba command-line interface.
For the official registry, logging in can be done by clicking the “Log in” button at the top of the page and authenticating with Github (other authentication methods aren’t currently being implemented, but we’re open to contributions!). After this is done, you can add an auth token which can be used to log into the elba cli.
For any other potential registries, the process might differ, but the end result should be that you get an auth token.
In order to log into a registry, use the
elba login subcommand. If you
have multiple indices specified in your configuration, you can specify
the index to use with the
--index flag. For example:
$ elba login a67fc893bccfea2141 --index index+git+https://github.com/elba/index
Otherwise, elba will use the default index (the first index specified in configuration).
Login information is saved to the
logins.toml file in the platform-
specific data directory:
- On Linux, this is either
- On Windows, this is at
- On macOS, this is at
Before a package is published, it must be compressed into a tarball with
tar.gz extension. The
elba publish command will do this
automatically for you; however, you can also do this step yourself with
elba package subcommand.
When run in an elba project directory or subdirectory, this command will build all targets of a project to make sure it builds successfully, then package the source code of the project into a tarball.
If you’d like to skip the verification process, you can pass the
--no-verify flag to the command.
In some cases, you might not want to include every file in the current
directory in the tarball. For one thing, elba will automatically ignore
any files specified in a
.gitignore file in the current project.
Additionally, you can specify files to ignore in the manifest file of
your project, under the
package.ignore is a list which accepts individual “lines” of a
.gitignore files as list elements. An example is provided below:
[package] # snip: other package metadata # ignoring files that end with .out or .dev ignore = ["*.out", "*.dev"]
Uploading a package¶
Uploading a package can be accomplished with the corresponding command:
elba publish, which verifies that a package builds, packages it into
a tarball, and uploads it to a registry. Similar to
elba login, you
can pass the
--index flag to specify which index this command should
apply to. Unlike
elba package, you can’t disable package
verification: all targets must build in order to upload your package
to an index.
Yanking: for when things go wrong¶
After a package has been published to a package registry, there is no API endpoint or elba feature which allows for deleting a package (this circumvents the “left-pad” problem). However, there is a yanking feature (similar to crates.io), which lets you disable a version of a package from being dependended on or retrieved by any future package consumers.
The relevant subcommand is
elba yank, and it takes one positional
argument: the package and package version to yank, specified in the form
group/name|version. It also takes the optional
elba login and
You can also provide the
--unyank flag, which does exactly what it
says on the tin.