NAME

tix-release — create and sign tix releases and channels

SYNOPSIS

DESCRIPTION

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

A tix-create(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 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 and --mirrors 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. If the --mirrors option is not set, then it defaults to url as well.

--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.

--mirrors=urls

The space-separated urls to the mirrors. The first mirror is the primary and default mirror.

If unset, the default is --authoritative if set.

--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.

--upgrade-release-key=public-key

Override which public-key to trust when offering an upgrade in the channel-entry command.

The default is to use the public key from --upgrade-release if --same-signing is set, otherwise attempting a key search if --key-search is set, and otherwise using --public-key if set.

--upgrade-release-url=url

Override the url to the new release when offering an upgrade in 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

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

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

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

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

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

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

tix-create -C /local -u https://example.com/local/channel/stable/1.0
tix-install -C /local foo bar

tix-upgrade -C /local

SEE ALSO

signify(1), port(5), tix(8), tix-create(8), tix-install(8), tix-metabuild(8), tix-repository(8), tix-upgrade(8)

HISTORY

tix-release originally appeared in Sortix 1.1.