ryangjchandler / forge-previewer

Create preview deployments for pull requests with Laravel Forge.

Forge Previewer

This CLI is designed to create "preview" environments for pull requests and branches using Laravel Forge.

It's intended for use inside of CI tools such as GitHub Actions to automatically create a site on Forge that is connected to your pull request branch, then once the pull request is merged the CLI can be used to cleanup too.

Prerequisites

Before using this tool, please make sure you have the following:

• A server connected to Forge
• A wildcard subdomain DNS record pointing to your Forge server.
• A Forge API token

Installation

Install this package with Composer:

composer global require ryangjchandler/forge-previewer

Usage

There are two commands in the command.

• deploy - Creates and deploys a site.
• destroy - Deletes and cleans up after a site.

deploy

The deploy command is used to do the following things:

1. Create a site on Forge.
2. Generate an SSL certificate for the new site.
3. Create a database for the new site.
4. Enable quick deploy so all changes appear on the preview site automatically.
5. Update the environment variables to point to the database.
6. Deploy your site once.
7. Run any additional commands provided.
8. Create a scheduled job if required.

The command accepts the following flags:

Description:
  Deploy a branch / pull request to Laravel Forge.

Usage:
  deploy [options]

Options:
    --token[=TOKEN]              The Forge API token.
    --server[=SERVER]            The ID of the target server.
    --provider[=PROVIDER]        The Git provider. [default: "github"]
    --repo[=REPO]                The name of the repository being deployed.
    --branch[=BRANCH]            The name of the branch being deployed.
    --domain[=DOMAIN]            The domain you'd like to use for deployments, e.g. mydomain.com.
    --php-version[=PHP-VERSION]  The version of PHP the site should use, e.g. php81, php80, ... [default: "php81"]
    --command[=COMMAND]          A command you would like to execute on the site, e.g. php artisan db:seed. (multiple values allowed)
    --edit-env[=EDIT-ENV]        The colon-separated name and value that will be added/updated in the site's environment, e.g. "MY_API_KEY:my_api_key_value". (multiple values allowed)
    --scheduler                  Setup a cronjob to run Laravel's scheduler.
    --no-quick-deploy            Create your site without "Quick Deploy".
    --no-deploy                  Avoid deploying the site.

Note: the deploy command can be run multiple times and will skip any steps that have already been run previously.

destroy

The destroy command simply reverses all of the things that the deploy command does. It checks for the existence of certain resources in Forge and removes them if they exist.

The command accepts the following flags:

Description:
  Destroy a previously created preview site.

Usage:
  destroy [options]

Options:
    --token[=TOKEN]    The Forge API token.
    --server[=SERVER]  The ID of the target server.
    --repo[=REPO]      The name of the repository being deployed.
    --branch[=BRANCH]  The name of the branch being deployed.
    --domain[=DOMAIN]  The domain you'd like to use for deployments.

Since Forge Previewer is convention based, we will try to detect resources based on the names we generate for them.

Example Workflow

TODO

forge-previewer's Issues

Add support for daemons

Check that `deploy` can be run multiple times for same branch

Need to make sure certain steps get skipped.

Prettier output

The output messages are a bit big at the moment. Could probably use a task list / step list instead.

Private repo support

Good afternoon,

I want to use forge-previewer in our project, can you tell me if it is possible to specify a private repository?

Add support for configuration file

Something like a previewer.yml file or similar. Removes the need to specify flags on the command, can just do forge-previewer deploy --config=.previewer.yml or something instead.

Add Support for Custom Forge Bash Deploy Script

Overview:
Currently, the forge-previewer CLI provides an excellent workflow for creating preview environments using Laravel Forge. However, to further enhance its flexibility and customization, it would be valuable to include support for specifying a custom Forge bash deploy script.

Proposal:
I suggest implementing a feature that allows users to define their own Forge bash deploy script within the forge-previewer configuration. This would enable users to seamlessly integrate their specific deployment requirements and processes.

Benefits:

• Enhanced Customization: Users can tailor the deployment process to their specific needs and requirements.
• Compatibility: This feature will accommodate a wider range of deployment workflows and scenarios.
• Flexibility: Users can adapt the deployment script to suit their project's unique setup.

Implementation Guidelines:

1. Add a new configuration option, custom-deploy-script, to the forge-previewer DeployCommand with a bash script as a GitHub variable or local config file.
2. Also we can make some presets for any environment.
3. Provide clear documentation on how users can utilize this new feature.
4. Ensure that the custom deploy script integrates seamlessly with the existing deployment process.

Additional Notes:
This enhancement aligns with our goal of providing a versatile and adaptable solution for creating preview environments with Laravel Forge. It would greatly benefit users who have specific deployment requirements that go beyond the standard workflow.

Looking forward to your feedback and collaboration on this exciting addition!

Thank you!

Add in a `destroy` command

Disabling the "composer install dependencies" option

Good afternoon,

Can you tell me if it is possible to disable "Install Dependencies"? When creating a new site this option is enabled by default, and through the use of the application I have not found a way to turn it off, does it exist at all?
Because it is possible to get this error (below) if the repository does not contain the specified components.

Composer could not find a composer.json file in /home/forge/***
To initialize a project, please create a composer.json file.

Support preventing the database setup

I noted an issue with the updateSiteEnvironmentFile when using no environment file.

This should be investigated, as I'm not sure if it's a bug (I did try adding these to my test projects when deploying) so not sure if this is an issue on all first setups for a site.

A solution is to add a flag to prevent this behaviour:

{--no-database : Avoid creating a database.}

Add support for enabling scheduler

Support GitHub actions output

We can use GitHub Actions outputs to provide values for later steps.

Output the domain that's been deployed

echo "::set-output name=domain::forge-preview.domain.com"

An example of its use is to add a comment to the PR with the thollander/actions-comment-pull-request action

Support site isolation

We can use the site isolation parameter of the API. This is important for public repo's and ensures security by preventing access to other sites.

Pseudocode: at https://github.com/ryangjchandler/forge-previewer/blob/main/app/Commands/DeployCommand.php#L177

-        $site = $this->forge->createSite($server->id, [
+        $data = [
             'domain' => $domain,
             'project_type' => 'php',
             'php_version' => $this->option('php-version'),
             'directory' => '/public'
-        ]);
+        ];
+
+        if (!$this->option('no-isolation')) {
+            $this->information('Enabling site isolation');
+
+            $data['isolation'] = true;
+            $data['username'] = str($this->getBranchName())->slug();
+        }
+
+        $site = $this->forge->createSite($server->id, $data);
 
         $this->information('Installing Git repository');