TIX-RELEASE(8)

NAME
tix-release - create and sign tix releases and channels

SYNOPSIS
tix-release [--authoritative=url] [--build-id=build-id] [--channel=name] [--dev-releases] [--extra-releases=releases] [--generation=level] [--key-search=path-prefix] [--main=url] [--mirrors=urls] [--new-release-url=url] [--new-release-pub-path=public-key] [--public-key=file] [--release=name] [--release-directories=directory] [--release-filter=extended-regex] [--releases=list] [--same-signing] [--secret-key=file] [--sign] [--unskippable=[all | major | minor | last-patch | patch | none]] [--upgrade-release=new-release] [--version=version] [--which-public-key] [--which-secret-key] [channel | channel-entry | channels | release | sign] directory

DESCRIPTION
tix-release creates tix releases and channels, and signs their information for publication.

A tix-collection(8) installation has the collection.conf(5) RELEASE_URL variable that specifies what is installed, pointing to a release or a channel:

•   A release is a particular static versioned build.
•   A channel dynamically redirects each version to the appropriate release, optionally offering an upgrade to a newer version.

Installations typically point to a channel in order to receive upgrades. The signed release.info.sig metadata file format is used for both releases and channels.

A top-level distribution site conventionally contains a directory named channel (containing the channels) and a directory named release (containing the releases).

A tix release is prepared for publication by running the tix-metabuild(8) command. To make the release, the command creates the release directory structure, populates the per-platform repository/$platform subdirectories with the .tix.tar.xz and .version files produced by tix-port(8), runs the tix-repository(8) metadata command on each platform repository, runs the tix-release release command on the release directory, and then signs the release with the tix-release sign command.

A tix channel is prepared for publication using the channel command. A channel contains subdirectories named after each version, each containing a release.info.sig file with metadata. The channel redirects to a release on the main mirror and additional mirrors. The channel version directories are chained together, with each version offering an upgrade to the next version (if any).

The first operand selects a command to execute:

channel
    Generate a channel inside the top-level channel directory named per the --channel option using the releases from the --release-directories option.

    The releases can be selected using the --releases option, otherwise the --release-directories directory is read and filtered using the --release-filter option. The --extra-releases option can select additional releases.

    The channel's release upgrade graph is built per the --unskippable upgrade rules, ordered per semantic versioning rules. Every entry on the channel will indicate where to find the release and where upgrades are available per the --authoritative, --main, and --mirror options.

    Channels must be signed in order to be valid, e.g. by using the --sign option that will sign every entry on the channel.

    The --authoritative, --channel, and --release-directories options must be set.

channel-entry
    Generate an entry for a single version on a channel. This low-level command allows manually constructing the channel upgrade graph.

    The ${directory}/${channel}/${version}/release.info file is generated per the top-level channel directory, the options supplied, and the release information.

    An upgrade path to a new release can be specified in the --upgrade-release option. If the new release is signed, then the upgrade will trust the new key, on the authority of the signed channel entry.

    The --channel, --release, and --release-directories options must be set.

channels
    Generate common channels inside the top-level channel directory:

    •   A stable channel with stable releases.
    •   A ${major}.${minor} channel for every major/minor version pair, containing all the patch releases.
    •   A ${extra_release} channel for every specified --extra-releases containing the normal releases and that extra release.

    The --release-directories option must be set.

release
    Generate the top-level release metadata files in the output release directory:

    •   release.info
    •   sha256sum

    The --build-id, --release, and --version must be set.

sign
    Sign release.info and sha256sum (if it exists) in the directory as a separate step from creating the files. The --sign option can be used with any of the other commands to sign the files as a single step at creation time.

    The --public-key and --secret-key options must be set to the signify(1) key pair, or the --key-search option to search for the appropriate key.

The options are as follows:

--authoritative=url
    The url to the top-level authoritative distribution site, in which the channel directory will be published.

    This option is required for upgrades to point to the new release and must be used for the channel and channels commands.

--build-id=build-id
    Set the BUILD_ID to build-id, a unique identifier of what was built, allowing installations to know if they are up to date.

    This option is required for the release command.

--channel=name
    The name of the channel being created.

    This option is required for the channels, channel, and channel-entry commands.

--dev-releases
    When searching for releases, implicitly add releases ending in -dev for every version found. This option ensures that all dev releases that might have existed (but no longer do) still have an upgrade path.

--extra-releases=releases
    Additional releases to include for the channel command. For the channels command, each such extra release has its own channel made with itself as the only extra release.

--generation=generation
    Select tix metadata generation level (Default: 3)

--key-search=path-prefix
    Search for the public and secret keys in the file paths starting with this path-prefix, an optional middle section, and ending in .pub for the public key and .sec for the secret key.

    The middle section is searched in this order:
    •   The release.
    •   The version.
    •   The major, minor, and patch version numbers.
    •   The major and minor version numbers.
    •   The major version number.
    •   The empty string.
    If the middle section isn't empty, then it's prefixed with a hyphen.

--main=url
    The url to the main mirror.

--mirrors=urls
    The space-separated urls to the secondary mirrors.

--new-release-url=url
    Override the url to the new release when offering an upgrade in the channel-entry command.

--new-release-pub-path=public-key
    Override which public-key to trust when offering an upgrade in the channel-entry command.

--public-key=file
    Sign the release or channel with the signify(1) public key file.

--release=name
    The name of the release.

    This option must be used with the release and channel-entry commands. For the channel command, it optionally specifies the current release of a channel, and excludes any newer releases.

--release-directories=directory
    Find releases inside this directory.

    This option is required for the channels, channel, and channel-entry commands.

--release-filter=extended-regex
    Find the list of releases by searching the --release-directories directory for entries matching this extended-regex given to grep(1) -E.

--releases=list
    Override the --release-filter search by manually specifying the space-separated list of releases.

--same-signing
    When signing a channel using --key-search, try to sign the channel using the same keys as the underlying release, by searching for an identical public key.

--secret-key=file
    Sign the release or channel with the signify(1) secret key file.

--sign
    Sign the output release.info files per the --public-key, --secret-key, --key-search, and --same-signing options. This option can be used with any command and has the same effect as the sign command.

--unskippable=[all | major | minor | last-patch | patch | none]
    Build the channel upgrade paths according to this rule:

    all Don't allow skipping any release (including prerelease).
    patch
        Don't allow skipping patch releases.
    last-patch
        Don't allow skipping the last patch of a minor release.
    minor
        Don't allow skipping minor releases.
    major
        Don't allow skipping major releases.
    none
        Allow skipping any release.

    The default is last-patch.

--upgrade-release=new-release
    Offer an upgrade to the new-release when using the channel-entry command.

--version=version
    The version of the release.

    This option must be used with the release and channel-entry commands.

--which-public-key
    Output the path to the chosen public key.

--which-secret-key
    Output the path to the chosen secret key.

ENVIRONMENT

SOURCE_DATE_EPOCH
    Use this timestamp for the DATETIME field in the release information.

EXIT STATUS
tix-release will exit 0 on success and non-zero otherwise.

EXAMPLES

  Create a new tix release
See tix-metabuild(8) for an example of how to make a new tix release.

  Sign a tix release
First create a signing key, either a general signing key to be reused across releases, or a per-release signing key to be rotated:

    mkdir -p keys
    signify -G -c 'local repository signing key' -p keys/local.pub -s keys/local.sec

Use the signify(1) -n option to omit the password for unattended signing.

Sign the release:

    tix-release \
      --secret-key=keys/local.sec \
      --public-key=keys/local.pub \
      sign release/1.0

  Create a stable channel with the tix release
Publish the newly signed release on the main site and mirrors:

    tar -c release/1.0 | ssh example.com 'tar -C /var/www/example.com/local -x'
    tar -c release/1.0 | ssh cdn.example.com 'tar -C /var/www/cdn.example.com/local -x'
    tar -c release/1.0 | ssh example.net 'tar -C /var/www/example.net/local -x'

Create or regenerate the stable channel and sign it:

    tix-release \
      --authoritative=https://example.com/local \
      --channel=stable \
      --main=https://example.com/local/release \
      --mirrors='https://cdn.example.com/local/release https://example.net/local/release' \
      --public-key=keys/local.pub \
      --release-directory=release \
      --secret-key=keys/local.sec \
      --sign \
      channel channel/

Finally, publish the new channel on the authoritative site to provide upgrades to installations:

    tar -c channel/stable | \
    ssh example.com 'tar -C /var/www/example.com/local -x'

  Generate multiple channels
The channels command is useful for generating multiple channels in one invocation. It creates a stable channel, and channel for every major and minor version pair, as well channels for any extra releases (such as nightly development releases).

    tix-release \
      --authoritative=https://example.com/local \
      --dev-releases \
      --extra-releases='nightly cross-nightly' \
      --key-search=keys/local \
      --main=https://example.com/local/release \
      --mirrors='https://cdn.example.com/local/release https://example.net/local/release' \
      --release-directory=release \
      --sign \
      channels channel/

The --dev-releases option is useful to implicitly include dev versions on channels that might have existed at one point but don't anymore. The --key-search option is useful to search for per-release signing keys.

  Install the custom ports in a local tix collection
The custom ports can now be installed from any installation by creating a tix collection pointed to the stable channel:

    tix-collection /local create \
                   --release-url=https://example.com/local/channel/stable/1.0 \
                   --release-key=keys/local.pub
    tix /local install foo bar

The local ports can be updated to any new versions published on the channel:

    tix-upgrade --collection=/local

SEE ALSO
signify(1), port(5), tix(8), tix-collection(8), tix-install(8), tix-metabuild(8), tix-repository(8), tix-upgrade(8)

HISTORY
tix-release originally appeared in Sortix 1.1.