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, choose the application it deploys and, if you like, when it stops working by itself (after 30, 90 or 365 days). Then choose Create token.
3. Copy the token. It starts with bl_ and is shown this once: Brewless keeps only a 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#

A token belongs to one application and may only deploy it: plan and apply its brewless.yml, start a release and follow it to the end, and read its releases and logs. It sees no other application. Anything else, such as reading the variables, running a command, changing DNS or removing something, is refused, so a token that leaks from a pipeline cannot do more than deploy. For the rest, use the command line client signed in as yourself.

It acts as you, in the organisation you made it in, and never with more rights than yours. Whatever it changes is in the audit trail under your name, and so are making and revoking it.

It stops working after the period you chose, at once when you revoke it on the Account page, or when you are removed from the organisation. The list there shows which application each token deploys and when it was last used.

A token made before tokens were limited to one application, on 24 October 2026, still has all of your rights; the list marks it. Replace it with a new one.

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