Publishing a new version

This page is for staff who set up how a product's new versions reach Chandler. It also explains publisher tokens, the secret codes build systems use.

A build system is the set of computers that turns a product's code into files customers can install. Each product has its own.

How publishing works

A new version reaches customers in five steps. The first four happen in the product's build system, not in Chandler.

Sign. The build system signs a short description of each file. The description says which product, version and platform the file is for. It also records the file's size and fingerprint. A fingerprint is a short code worked out from the file's contents. Change one letter of the file, and the fingerprint no longer matches.
Upload. The build system copies the files into our private file storage.
Register. The build system tells Chandler about the new release. It proves who it is with a publisher token. The release shows up as a Draft.
Check. The build system asks Chandler to check the files. Chandler compares each stored file with its signed description. If they match, the release becomes Verified.
Publish. A person with the Release publisher permission opens the release in Chandler and clicks Publish.

Nothing reaches customers until a person clicks Publish. See Publishing.

The key that signs releases never goes near Chandler. It stays with the build system or on an offline computer. So even someone who broke into Chandler couldn't make a fake release that installs would accept.

Publisher tokens

A publisher token is a secret code for one product's build system. With it, the build system can send new releases to Chandler as drafts.

A publisher token:

works for one product only
can only add drafts, never publish them
can't see customers or licenses
stops working after at most 90 days

Open Publisher tokens from the Releases page to see every token. You need the Release publisher permission.

Creating a publisher token

On the Publisher tokens page, click Create publisher token. Chandler may ask you to sign in again first.
Pick the Product the build system publishes.
Type a Name, for example "Trawler build pipeline". It helps you find the token later.
Pick how long it lasts. The longest is 90 days.
Click Create publisher token.

Chandler shows the new token on the next page. Save it straight away: see Saving the token.

If you see This token was already created, the page was sent twice, for example by reloading it. Chandler made only one token and won't show its secret again. If nobody saved it, revoke that token and create a new one.

Saving the token

Chandler shows the new token only once, on the next page. It doesn't keep a copy.

Click Copy, or select the token and copy it yourself.
Paste it into the build system's secret settings. Ask engineering if you are not sure where.
Tick the box and click I have saved it.

Never send a token by email or chat. If a token is lost, revoke it and make a new one.

Revoking a publisher token

Revoke a token when it is no longer needed, or if it may have leaked.

On the Publisher tokens page, click Revoke token next to it.
Read the confirmation, then click Revoke token again.

The token stops working straight away. Releases it already sent stay as they are. This can't be undone. The build system can't send new releases until you give it a new token.

Before a token runs out

Tokens stop working on their end date, shown in the list. About a week before, create a new token and put it into the build system. Then revoke the old one.

Setting up a product's build system

Engineering sets up each product's build system once. The steps, commands and an example are in an engineering guide: Publishing a release from the build system. That link works when you read this guide in the code repository. Inside Chandler, ask engineering for it.

You give engineering two things:

a publisher token for the product
the address of Chandler

Engineering keeps the release signing key. You never need it.

When something goes wrong

What you see	What it means	What to do
The release stays a Draft	Chandler hasn't checked the files, or a file didn't match.	Ask engineering to look at the build system's log.
The build system says its token was refused	The token was revoked, has run out, or is for another product.	Create a new token and give it to engineering.
There is no Publish button	You don't have the Release publisher permission, or the release isn't Verified.	Ask IT for the permission, or wait for the check.