Deploying from a pipeline

A pipeline cannot approve a sign-in in the browser. It deploys with a pipeline token instead, which the command line client reads from BREWLESS_API_TOKEN, the way Laravel Vapor's client reads VAPOR_API_TOKEN.

Making a token#

1. In the console, open Account and go to Pipeline tokens.
2. Name the token after the pipeline that will hold it, such as GitHub Actions shop, and choose Create token.
3. Copy the token. It starts with bl_ and is shown this once: Brewless keeps only a keyed hash of it.

A token can only be made in the console while you are signed in there. A token cannot make another one.

What a token may do#

The token acts as you, in the organisation you made it in, with your rights: what your role does not allow, the token does not either. Whatever it changes is in the audit trail under your name, and so are making and revoking it.

It does not expire. It stops working at once when you revoke it on the Account page, or when you are removed from the organisation. The list there shows when each token was last used.

Warning

Keep the token in the secrets of your pipeline, never in the repository. Anyone who holds it can deploy and change the organisation as you.

Using it#

Give the pipeline the token as BREWLESS_API_TOKEN. With that variable set, the client uses it instead of a sign-in of the machine, so brewless login is not needed. The organisation still comes from brewless.yml, so the token has to be one of that organisation; when Brewless refuses it, the client says the token was refused and the pipeline fails.

export BREWLESS_API_TOKEN=bl_…
brewless deploy production --no-interaction

With --no-interaction the client asks nothing: domains from brewless.yml that the environment does not answer on yet are only added with --domains. It follows the release until it is live or has failed, and ends with a non-zero exit code when the deploy fails, so the pipeline fails with it.

The client needs PHP 8.3 or newer and git, and deploys the commit that is checked out. Install it in the pipeline with composer global require brewless/cli, or download the built file brewless that comes with every release of brewless/cli on GitHub. In a pipeline it does not look for newer versions of itself.

In GitHub Actions the token goes in from the repository's secrets:

- run: brewless deploy production --no-interaction
  env:
    BREWLESS_API_TOKEN: ${{ secrets.BREWLESS_API_TOKEN }}