Blacksmith is a convention-first review app initializer for Laravel Forge.
When you trigger the Blacksmith GitHub action for your pull request a review app will be setup using a combination of your app name, the pull request number, and your wildcard domain (Ex: mysite-123.domain.com). Blacksmith will setup the following for each sandbox:
- A new Forge site on your designated server
- A connection to your repo/branch for quick deployments
- A database (can be seeded)
- A Let's Encrypt SSL
- Robots.txt disabling crawlers
- On close: Triages the sandbox to be deleted after 24 hours
If you want to utilize Blacksmith you'll need:
- A Forge server
- A Forge API token
- A wildcard domain for your review apps (Ex: *.domain.com)
- Deploy the Blacksmith Laravel application to your Forge server
- Setup the required
.env
variables:
# Used to connect to the Forge SDK to provision your sandboxes
FORGE_TOKEN=
# The server the sandboxes should be created on
FORGE_SERVER_ID=
# The domain to use for your sandboxes (*.domain.com)
FORGE_REVIEW_APP_DOMAIN=
# MySQL credentials to use to create database backups when sandboxes are closed
FORGE_MYSQL_USER=
FORGE_MYSQL_PASSWORD=
- Verify your Blacksmith homepage is being reported as "Online"
- Ensure
php artisan schedule:run
runs every minute - Setup your repo to have a
.github/workflows/sandbox.yml
file and use the following:
name: Sandbox
on:
pull_request:
types: [synchronize, labeled, closed, reopened]
env:
APP_NAME: myapp
jobs:
sandbox:
if: contains(github.event.pull_request.labels.*.name, 'sandbox')
runs-on: ubuntu-latest
steps:
- uses: trendyminds/github-actions-blacksmith@main
with:
app_name: ${{ env.APP_NAME }}
pr_number: ${{ github.event.pull_request.number }}
event: ${{ github.event.action }}
host: ${{ secrets.BLACKSMITH_HOST }}
key: ${{ secrets.BLACKSMITH_SSH_KEY }}
path: ${{ secrets.BLACKSMITH_PATH }}
- When you label your pull request with "sandbox" Blacksmith will now provision your sandbox environment.
The GitHub Action comes with a number of options that have sensible defaults:
- uses: trendyminds/github-actions-blacksmith@main
with:
event: ${{ github.event.action }}
app_name: ${{ env.APP_NAME }}
pr_number: ${{ github.event.pull_request.number }}
php_version: php82
doc_root: /web
aliases: |
test.domain.com
another.domain.com
disable_ssl: true
user: myuser
host: ${{ secrets.BLACKSMITH_HOST }}
key: ${{ secrets.BLACKSMITH_SSH_KEY }}
path: ${{ secrets.BLACKSMITH_PATH }}
Option | Required | Default | Description |
---|---|---|---|
event | true |
The type of action being ran | |
app_name | true |
The name of the app to use for the domain, database, etc. | |
pr_number | true |
The PR number for the review app | |
php_version | false |
php83 | Which version of PHP to use for your app |
doc_root | false |
/public | The document root of your application |
aliases | false |
Other domains that should also point to the site | |
disable_ssl | false |
false |
Skips adding an SSL to the sandbox |
user | false |
forge | The SSH user to use for the connection |
host | true |
The host address to use for the connection | |
key | true |
The SSH key to use for the connection | |
path | true |
The path to the Blacksmith app on the server |