Skip to main content

​
NAME

flox-publish - Publish packages for Flox

​
SYNOPSIS

​
DESCRIPTION

Publish the specified <package> from the environment in <path>, uploading package metadata and copying the packages so that it is available in the Flox Catalog.

​
Preconditions

Flox makes some assertions before publishing, specifically:
  • The Flox environment used to build the package is tracked in a Git repository.
  • Tracked files in the repository are clean.
  • A local branch is checked out, and it tracks an upstream branch on a remote. A detached HEAD cannot be published.
  • The clone contains the full repository history. For actions/checkout, set fetch-depth: 0. Shallow history cannot provide the revision count used to order builds; see ECO-373.
  • The checked-out revision belongs to the upstream branch advertised by the remote. The exact advertised branch tip must already be available locally. Run git fetch <REMOTE> before publishing if the remote branch has advanced.
  • For a manifest build, the environment must have at least one package in the toplevel package group: the package is published against the nixpkgs revision that group is locked to, and an environment with no such package is locked to none. A Nix expression build has no such requirement, because the revision it is published against comes from the catalog server rather than the environment.
A Nix expression build is published against the catalog’s current revision, so installing it into an environment locked to an older revision may require placing it in its own package group. These conditions ensure that the package being built can be located, built, and reproduced in the future.

​
Publishing process

Possible values for <package> are all keys under the build attribute in manifest.toml. If only one build is defined in manifest.toml, specifying the <package> is unnecessary. If there are multiple builds defined, you may only publish a single package at a time. When <package> is omitted, flox publish prompts you to select one if it is running interactively, and otherwise fails with a list of the available packages. Flox will then perform a clone of the repository to a temporary location and perform a clean flox build operation. This ensures that all files required to build the package are included in the git repository. When publishing a package, metadata is sent to Flox servers so that information about the package can be made available in flox install, flox search, and flox show. The package itself, along with any other packages it depends on, are uploaded to the Catalog’s configured Catalog Store. By default, Flox provides and configures a Catalog Store, but you may optionally provide your own Catalog Store. Contact Flox directly if you’re interested in this option. Finally, the package is uploaded to the default Catalog, which is named after your user, but you may specify the catalog to publish to via the --catalog option.

​
Source registration

Each package is registered to the source repository and ref it is published from. Before building, flox publish checks whether this publish would change that registration. If it would, an interactive publish shows the registered and requested sources and asks for confirmation, which defaults to no. A non-interactive publish stops instead. If the registration changes again while the package builds, the publish stops. Run it again to confirm the new source. To replace the registration without asking, use --allow-lineage-change.

​
After publishing

After the package is published, it will be available to the flox install, flox search, and flox show commands. The package will appear with a name of the form <catalog>/<name> where <catalog> is the name of the catalog it was published to, and <name> is the name of the package as it was defined in the [build] section of the manifest. The <catalog> name is either your user name or the name of the organization that owns the Catalog. For instance, if a user myuser published a package called hello to their personal Catalog, the package would appear in flox search as myuser/hello. When installing the package, it is downloaded directly from the Catalog Store that it was published to. Published packages on FloxHub are also available as catalog imports for Nix expression builds. Other environments reference the published packages as catalogs.<catalog>.<package> in .nix expressions under .flox/pkgs/. These references are pinned by a committed .flox/catalog.lock when the project has one (see flox build update-catalogs), and are otherwise resolved fresh during the build. flox publish submits the entries relevant to the published package along with the build.

​
Sharing published packages

A package published to an individual user’s Catalog may only be seen and installed by that user. In order to share packages with other users you must create an organization. See the organizations concept page for more details on organizations and how to create them. Note that this is a paid feature available with Flox for Teams.

​
AUTHENTICATION

Publishing packages to the Flox Catalog requires a free FloxHub account. Log in with flox auth login (see flox-auth). In CI or other non-interactive environments, supply a token instead; see https://go.flox.dev/auth.

​
OPTIONS

<package>
The package to publish. Possible values are all keys under the build attribute in the environment’s manifest.toml. -o, --org <org>
Specify the organization to which an artifact should be published to. Takes precedence over the default value of the user’s GitHub handle. --signing-private-key <path>
The private key to use in signing the package during upload. This is a local file path. This option is only necessary when using a Catalog Store not provided by Flox. Takes precedence over the value of publish.signing_private_key from ‘flox config’. --allow-lineage-change
Replace the package’s registered source without asking. The publish replaces whichever source is registered when it completes. It also skips the already-published check, so the publish may repeat build and upload preparation. Use it only for an intentional replacement, not for routine CI publishing. --stability <stability>
Perform a Nix expression build using a base package set of the given stability as tracked by the catalog server. A stability (e.g., "stable") identifies a curated nixpkgs revision managed by the catalog server. When omitted, the default stability is used. A manifest build is published against its environment’s revision instead, and so are the Nix expression builds it reaches. Cannot be used with manifest builds.

​
Environment Options

If no environment is specified for an environment command, the environment in the current directory or the active environment that was last activated is used. -d, --dir
Path containing a .flox/ directory.

​
General Options

-h, --help
Prints help information. The following options can be passed when running any flox subcommand but must be specified before the subcommand. -v, --verbose
Increase logging verbosity. Invoke multiple times for increasing detail. -q, --quiet
Silence logs except for errors.

​
SEE ALSO

flox-build flox-activate manifest.toml