# A Deploy to Brewless button in your Laravel README

Put a one-click deploy button in a public Laravel repository, so readers run your demo or starter kit in their own Scaleway project.

## In short

- A public Laravel repository on GitHub, Codeberg or GitLab can carry a button that deploys it to Brewless in one click.
- The reader gets the application in their own Scaleway project, on a test address of its own, without touching a terminal.
- Brewless reads only the newest commit's composer.json and brewless.yml; the code itself is downloaded by a build job inside the reader's own project.
- A brewless.yml in the repository shapes the environment, minus the parts that are the author's own, such as the domains and the organisation.
- The button makes the first release and nothing after it, so a reader who wants to follow your repository forks it and deploys from there.

If you maintain a Laravel starter kit, a demo app or a package with an example project, you know the gap between "here is the repository" and "I got it running". Clone, copy the `.env`, find a database, generate a key, run the migrations, and somewhere in there most readers give up.

A deploy button closes that gap. Put one line in your README, and a reader gets your app running on a live address, in infrastructure they own, without opening a terminal.

## What does a Deploy to Brewless button do?

It takes a reader from your README to a working copy of your app in their own Scaleway project, in one click. They pick a name, Brewless sets up the application and its production environment the way your `brewless.yml` describes, and the first release starts.

What it does not do is put the app on *your* account, or on a shared sandbox that expires. The containers, the database and the bucket are created in the reader's own Scaleway project and billed to them by Scaleway. It is their app from the first second.

## Add it to your README

One line of markdown, with your repository after `repository=`:

```markdown README.md
[![Deploy to Brewless](https://brewless.eu/img/deploy-to-brewless.svg)](https://brewless.eu/deploy?repository=github.com/owner/name)
```

For the other hosts, write `codeberg.org/owner/name` or `gitlab.com/group/name` instead. That is the whole integration: no app to install on your repository, no webhook, nothing to configure on the Brewless side.

The link lands on a page on brewless.eu that asks which console the visitor uses, such as `acme.brewless.eu`, and sends them on to it. Brewless.eu itself does not know who they are, which is why it has to ask; the deploy happens in their own organisation, at `/deploy` in their console.

> [!NOTE]
> The button reads public repositories only, through the code host's public API and without a key. A host that limits callers without a key may ask the reader to try again after a while.

## What Brewless reads from your repository

Less than you might expect. Two files at one commit, and nothing else:

| What | Why |
| --- | --- |
| `composer.json` | To check the project requires `laravel/framework` |
| `brewless.yml` | To shape the environment, when the file is there |

That is the lot. The code itself never passes through Brewless: when the release starts, the build job running inside the reader's own Scaleway project downloads the archive of that commit straight from GitHub, Codeberg or GitLab. The same route a `brewless deploy` from a laptop takes, minus the laptop.

## Ship a brewless.yml, and it is used

If your repository has a `brewless.yml`, the button deploys its `production` environment. If the file has no `production`, it takes the file's `default-environment`, and failing that its first environment.

Four things in your file are deliberately dropped, because they are yours and not the reader's:

| Left out | Why |
| --- | --- |
| `organisation` and `application` | Replaced by the reader's organisation and the name they type |
| `domains` | Your domains. The reader adds their own later |
| `kind` and `region` | The environment is a production environment in the default region |

Your `php`, `build` and `release` keys do carry over, so a project that needs a particular PHP version or an extra build step still gets one.

Without a `brewless.yml`, the button falls back to a plain default for a Laravel app: a database named after the repository, and the edge cache on.

```yaml brewless.yml
environments:
  production:
    database: name-of-the-repository
    edge:
      cache: 1h
```

That default is enough for a demo, but a file of your own is better. It is the one place where you say what your app actually needs, and a reader who later deploys from a fork gets the same thing.

> [!WARNING]
> A file that asks for `services` is refused. A service is pushed from a machine with `brewless service:push`, and the button has no machine. Such a repository has to be deployed with the command line.

## What the reader gets

After the click and a name, four things happen in order:

1. Brewless reads the repository at the newest commit of its default branch.
2. It creates the application, with a Scaleway project of its own when the reader's key is allowed to make projects.
3. The production environment is set up as `brewless deploy` would have set it up from the file.
4. The first release starts, and the deployments page of the environment follows it.

The environment gets a [test address](https://docs.brewless.eu/running/domains#the-test-address) from Brewless with that deploy, so there is a working URL without anyone owning a domain. Every page on it tells search engines to stay away with `X-Robots-Tag: noindex, nofollow`, and its `robots.txt` disallows everything unless your application has a `public/robots.txt` of its own, so a hundred copies of your demo do not turn up in search results next to the real thing.

The application counts towards the applications of the reader's plan like any other, and deploying takes the right to manage applications as well as a connected Scaleway project.

## After the first release

The button makes one release and then steps out of the way. The application is the reader's like one they made themselves: the next deploy comes from their own copy of the code, with `brewless deploy` or [from a pipeline](/blog/deploy-laravel-from-ci). Clicking the button again does not update the app, it makes a second one.

So the honest line to put next to the button in your README is: click it to see the thing run, fork it to keep up with it. A reader who wants your later fixes forks or clones the repository and deploys from there, which is what they would have done anyway, only now after they have seen it working.

## What it is good for, and what it is not

A deploy button is at its best for a demo, a starter kit, a conference example or a package that is easier to show than to describe. It is a bad fit for anything that needs secrets before it does something useful: Brewless will not invent a payment key or a mail provider for the reader, and an app that fails on its first request is a worse advertisement than no button at all.

If your example does need configuration, say so right under the button and keep the list short. A demo that runs on nothing but a database and shows something real on the first page beats a complete app that wants ten variables before it answers.

There is one more thing worth knowing about the shape of the app your reader ends up with. The containers are serverless, and `web.min` is `0` unless your file says otherwise, so a copy of your demo that nobody visits scales back to zero instead of running on. That is a real difference from a deploy button that parks a virtual machine in someone's account and leaves it there.

## Summary

1. Put one markdown line in your README with your repository after `repository=`.
2. Commit a `brewless.yml` so the environment matches what your app needs, instead of the default.
3. Leave `services` out of it, or the button cannot deploy the repository.
4. Tell readers the button is for trying it, and a fork is for following it.

The [deploy button](https://docs.brewless.eu/deployments/deploy-button) page in the documentation has the details, including exactly which parts of your file carry over.

## Frequently asked questions

### What does the Deploy to Brewless button actually deploy?

The newest commit of the repository's default branch. Brewless reads that commit's composer.json to check it requires laravel/framework, and its brewless.yml if there is one. The build job in the reader's own Scaleway project then downloads the archive of that commit from the code host itself.

### Which code hosts does the button work with?

GitHub, Codeberg and GitLab, as long as the repository is public. Write the address after repository= as github.com/owner/name, codeberg.org/owner/name or gitlab.com/group/name. On GitLab a project in a subgroup works too.

### Does my code pass through Brewless when someone clicks the button?

No. Brewless fetches two small files from the code host to work out what to build. The source archive goes from the code host straight to the build job running in the reader's own Scaleway project.

### Can the button deploy a private repository?

No. It reads public repositories only, through the code host's public API without a key. For a private repository, deploy with the command line or from a pipeline.

### Does the reader need a Scaleway account before clicking?

Yes. Deploying takes a connected Scaleway project and the right to manage applications in their Brewless organisation.

Source: https://brewless.eu/blog/deploy-button-laravel-readme
