Publishes a new version of the package.
$ mix hex.publish
The current authenticated user will be the package owner. Only package
owners can publish the package, new owners can be added with the
mix hex.owner task.
Packages and documentation sizes are limited to 8mb compressed, and 64mb uncompressed.
Publishing documentation
Documentation will be generated by running the mix docs task. ex_doc
provides this task by default, but any library can be used. Or an alias can be
used to extend the documentation generation. The expected result of the task
is the generated documentation located in the doc/ directory with an
index.html file.
The documentation will be accessible at https://my_package.hexdocs.pm/1.0.0,
https://my_package.hexdocs.pm will always redirect to the latest published
version.
Documentation will be built and published automatically. To publish a package
without documentation run mix hex.publish package or to only publish documentation
run mix hex.publish docs.
Workload Identity
Workload Identity, sometimes also known as "Trusted Publishing", lets a GitHub
Actions job publish without storing an API key. When the job has the
id-token: write permission and no HEX_API_KEY or other Hex credential is
configured, mix hex.publish exchanges the job's OIDC token for a short-lived
token that can only publish this package. Configure a workload identity on
hex.pm first. A public package is published by its own workload identities and
by the write workload identities with public packages of the organizations
that own it. Neither can create a public package, so its first release has to
be published with a regular account. A package in an organization's repository
uses the organization's workload identities, and one with the write role can
also create the package.
Staged publishing
When publishing requires approval, the package and docs are staged. The task
prints the approval URL and expiry. Use --wait to wait for approval after
staging the package and docs. Rejection or expiry makes the command fail.
Workload Identity tokens are renewed if they expire while waiting.
Reverting a package
A new package can be reverted or updated within 24 hours of its initial publish. A new version of an existing package can be reverted or updated within one hour. Documentation has no limitations on when it can be updated.
To update the package simply run the mix hex.publish task again. To revert run
mix hex.publish --revert VERSION or to only revert the documentation run
mix hex.publish docs --revert VERSION.
If the last version is reverted, the package is removed.
Command line options
--organization ORGANIZATION- Set this for private packages belonging to an organization--wait- Open the approval URL and wait for the staged release to be approved--yes- Publishes the package without any confirmation prompts--dry-run- Builds package and performs local checks without publishing, usemix hex.build --unpackto inspect package contents before publishing. Can't be used with--revert--replace- Allows overwriting an existing package version if it exists. Private packages can always be overwritten, public packages can only be overwritten within one hour after they were initially published.--revert VERSION- Revert given version. If the last version is reverted, the package is removed.
Configuration
:app- Package name (required).:version- Package version (required).:deps- List of package dependencies (see Dependencies below).:description- Short description of the project.:package- Hex specific configuration (see Package configuration below).
Dependencies
Dependencies are defined in mix's dependency format. But instead of using
:git or :path as the SCM :package is used.
defp deps() do
[
{:ecto, "~> 0.1.0"},
{:postgrex, "~> 0.3.0"},
{:cowboy, github: "extend/cowboy"}
]
endAs can be seen Hex package dependencies works alongside git dependencies. Important to note is that non-Hex dependencies will not be used during dependency resolution and neither will they be listed as dependencies of the package.
Package configuration
Additional metadata of the package can optionally be defined, but it is very recommended to do so.
:name- Set this if the package name is not the same as the application name.:files- List of files and directories to include in the package, can include wildcards. Defaults to["lib", "priv", ".formatter.exs", "mix.exs", "README*", "readme*", "LICENSE*", "license*", "CHANGELOG*", "changelog*", "src", "c_src", "Makefile*"]. Files created by operating systems, editors and version control (such as.DS_Store,*~and.git) are excluded unless they are listed without wildcards. The build and dependency directories, and the package tarball and unpack directory are always excluded.:exclude_patterns- List of patterns matching files and directories to exclude from the package.:executables- List of files and directories in the package whose files are executable, can include wildcards. By default a file is executable in the package if the owner execute permission is set on disk. When this option is set the permissions on disk are not used, use it when the file system doesn't store execute permissions, such as on Windows.:licenses- List of licenses used by the package. Use SPDX license identifiers orLicenseRef-<idstring>for custom licenses included in the package.:links- Map of links relevant to the package.:build_tools- List of build tools that can build the package. Hex will try to automatically detect the build tools based on the files in the package. If arebarorrebar.configfile is present Hex will mark it as able to build with rebar. This detection can be overridden by setting this field.:secret_scan- Configuration for the repository's secret scanning of the package. Supports:ignore, a list of file path globs whose findings are suppressed, for paths that deliberately ship secret-like values such as test fixtures:secret_scan: [ignore: ["test/fixtures/**"]]