Deployment

Bref Cloud deploys application using Bref's serverless.yml file.

If you haven't gotten started with Bref, follow the guide corresponding to your framework:

The main difference with Bref Cloud is that you don't deploy by running serverless deploy. Instead, you deploy by running:

bref deploy

(see the Getting Started guide to install the bref CLI)

The benefits of deploying using Bref Cloud:

• Credentials: You don't need to create AWS credentials or configure the serverless CLI, Bref Cloud handles this for you (learn more).
• Deployment monitoring: Bref Cloud provides a dashboard to view deployments of all your applications across all AWS accounts, regions, and environments.
• No need to install serverless: Bref Cloud transparently installs and runs the serverless CLI.
• Better UX: the bref CLI has minimal output with verbose mode that can be enabled in real time.

When you run bref deploy, Bref Cloud runs the serverless deploy command for you in the background.

Differences between bref and serverless

The bref CLI uses AWS credentials from AWS accounts connected in Bref Cloud (opens in a new tab). That means that it will ignore AWS credentials configured on your machine.

The bref CLI also uses the open-source fork of Serverless Framework (opens in a new tab), which is a fork of Serverless Framework v3, the last free and open-source version. This fork is maintained by Bref and ensures that the CLI is maintained and stable in the long run.

Finally, the bref CLI uses "environments" instead of "stages". This is just a vocabulary change. That means that you should use the --env option instead of the --stage option:

bref deploy --env production
 
# is equivalent to
serverless deploy --stage production

Deploying with Bref Cloud

To deploy an application using Bref Cloud, you need to add your Bref Cloud team to the serverless.yml file:

service: my-app
provider:
    name: aws
    # ...
 
# Add these lines:
bref:
    team: my-bref-cloud-team

(you can find your team name in Bref Cloud (opens in a new tab))

Then, you can deploy using the bref CLI:

bref deploy
 
# or for a specific environment
bref deploy --env production

Deploying from GitHub Actions

You can also deploy your application using GitHub Actions.

First, make sure you have set up the bref.team option in serverless.yml as shown in the section above.

Then, create a .github/workflows/deploy.yml workflow. Here is an example workflow you can use as a starting point:

name: Deploy
 
on:
    push:
        branches: [ main ]
 
jobs:
    deploy:
        runs-on: ubuntu-latest
        timeout-minutes: 15
        concurrency: deploy-prod # Avoid deploying concurrently
        environment:
            name: prod
            # Optionally set a URL for the environment
            # url: https://example.com
        steps:
            -   uses: actions/checkout@v4
 
            -   uses: actions/setup-node@v2
                with:
                    node-version: '18'
 
            -   name: Cache NPM dependencies
                uses: actions/cache@v4
                with:
                    path: ~/.npm # npm cache files are stored in `~/.npm`
                    key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}
                    restore-keys: |
                        ${{ runner.OS }}-node-
 
            # You can remove this step if you don't have a `package.json` file
            -   run: npm ci
 
            -   name: Setup PHP
                uses: shivammathur/setup-php@v2
                with:
                    php-version: '8.2'
                    coverage: none
                    # Install the Bref CLI as a global tool
                    tools: bref/cli
 
            -   uses: ramsey/composer-install@v3
                with:
                    composer-options: '--optimize-autoloader --no-dev'
 
            -   run: bref deploy --env=prod
                env:
                    BREF_TOKEN: ${{ secrets.BREF_TOKEN }}

Finally, you need to add the BREF_TOKEN secret to your repository:

• Create a "bot token" in your Bref Cloud team (opens in a new tab)
• Go to your repository on GitHub
• Click on "Settings" > "Secrets and variables" > "Actions" > "New repository secret"
• Set the name to BREF_TOKEN and the value to the token you received after creating the bot token

That's it! Your application will be deployed automatically when you push to the main branch. On the first deployment, the application will appear in the Bref Cloud dashboard.