Laravel Harbor

https://laravel-harbor.com/docs/
Admin
Laravel Harbor is a CLI tool that provisions dedicated preview environments on Laravel Forge for...
Tokens:7,203
Snippets:87
Trust Score:5.2
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install Harbor CLI using Composer

Source: https://laravel-harbor.com/docs/provision

This step demonstrates how to install the Harbor CLI globally on the GitHub Actions runner using Composer. The '-q' flag is used for a quieter installation process.

```bash
composer global require mehrancodes/laravel-harbor -q

```

--------------------------------

### Configuring Environment Keys with Harbor

Source: https://laravel-harbor.com/docs/harbor-with-laravel

This example illustrates how to pass multiple environment keys to your Laravel project during provisioning using the FORGE_ENV_KEYS variable. Keys and their secret values can be separated by semicolons.

```yaml
FORGE_ENV_KEYS: "GOOGLE_API=${{secrets.GOOGLE_API}}; SMS_API=${{secrets.SMS_API}}"

```

--------------------------------

### GitHub Actions Workflow for Laravel Harbor Provisioning

Source: https://laravel-harbor.com/docs/provision

This YAML workflow configures GitHub Actions to automatically provision a preview environment for a Laravel project when a pull request is opened, edited, reopened, or ready for review. It checks for non-draft pull requests with '[harbor]' in the title, installs Harbor CLI, and then runs the provision command using environment variables for Forge integration.

```yaml
name: preview-provision
on:
  pull_request:
    types: [opened, edited, reopened, ready_for_review]
jobs:
  harbor-provision:
    if: |
      github.event.pull_request.draft == false &&
      contains(github.event.pull_request.title, '[harbor]')
    runs-on: ubuntu-latest
    container:
      image: kirschbaumdevelopment/laravel-test-runner:8.1
    steps:
      - name: Install Harbor via Composer
        run: composer global require mehrancodes/laravel-harbor -q
      - name: Start Provisioning
        env:
            FORGE_TOKEN: ${{ secrets.FORGE_API_TOKEN }}
            FORGE_SERVER: ${{ secrets.FORGE_SERVER_ID }}
            FORGE_GIT_REPOSITORY: ${{ github.repository }}
            FORGE_GIT_BRANCH: ${{ github.head_ref }}
            FORGE_DOMAIN: harbor.com
        run: harbor provision

```

--------------------------------

### GitHub Actions Workflow for Harbor Provisioning

Source: https://laravel-harbor.com/docs/harbor-with-laravel

This GitHub Actions workflow triggers on pull request events to provision a new Laravel site using Harbor. It requires specific environment variables like Forge token and server ID, and installs Harbor via Composer before running the provision command.

```yaml
name: preview-provision
on:
  pull_request:
    types: [opened, edited, reopened, ready_for_review]
jobs:
  harbor-provision:
        if: |
          github.event.pull_request.draft == false &&
          (
              (
                  contains(github.event.pull_request.title, '[harbor]') &&
                  contains(fromJson('["opened", "reopened", "synchronize", "ready_for_review"]'), github.event.action)
              ) ||
              (
                  github.event.action == 'edited' &&
                  contains(github.event.pull_request.title, '[harbor]') &&
                  github.event.changes.title.from &&
                  !contains(github.event.changes.title.from, '[harbor]')
              )
          )
    runs-on: ubuntu-latest
    container:
      image: kirschbaumdevelopment/laravel-test-runner:8.1
    steps:
      - name: Install Harbor via Composer
        run: composer global require mehrancodes/laravel-harbor -q
      - name: Start Provisioning
        env:
            FORGE_TOKEN: ${{ secrets.FORGE_API_TOKEN }}
            FORGE_SERVER: ${{ secrets.FORGE_SERVER_ID }}
            FORGE_GIT_REPOSITORY: ${{ github.repository }}
            FORGE_GIT_BRANCH: ${{ github.head_ref }}
            FORGE_DOMAIN: laravel-harbor.com
        run: harbor provision

```

--------------------------------

### Provide Custom Deploy Script for Forge Site

Source: https://laravel-harbor.com/docs/configuration

Enables the relaying of a custom bash deploy script to the Forge site before deployment. This script can include commands like pulling from Git and installing dependencies.

```bash
FORGE_DEPLOY_SCRIPT: "cd $FORGE_SITE_PATH; git pull origin $FORGE_SITE_BRANCH; composer install;"
```

--------------------------------

### GitHub Actions Workflow for Preview Site Teardown

Source: https://laravel-harbor.com/docs/harbor-with-laravel

This YAML workflow automates the teardown of a preview Laravel site when a pull request is closed. It requires the '[harbor]' keyword in the pull request title and uses environment variables to identify the site to be torn down. The workflow runs on Ubuntu, uses a Docker container for the Laravel test runner, and installs Harbor via Composer.

```yaml
name: preview-teardown
on:
  pull_request:
    types: [closed]
jobs:
  harbor-teardown:
        if: |
          github.event.pull_request.draft == false &&
          (
              (
                  contains(github.event.pull_request.title, '[harbor]') &&
                  github.event.action == 'closed'
              ) ||
              (
                  github.event.action == 'edited' &&
                  contains(github.event.changes.title.from, '[harbor]') &&
                  !contains(github.event.pull_request.title, '[harbor]')
              )
          )
    runs-on: ubuntu-latest
    container:
      image: kirschbaumdevelopment/laravel-test-runner:8.1
    steps:
      - name: Install Harbor
        run: composer global require mehrancodes/harbor -q
      - name: Start Teardown
        env:
          FORGE_TOKEN: ${{ secrets.FORGE_TOKEN }}
          FORGE_SERVER: ${{ secrets.FORGE_SERVER }}
          FORGE_GIT_REPOSITORY: ${{ github.repository }}
          FORGE_GIT_BRANCH: ${{ github.head_ref }}
          FORGE_DOMAIN: laravel-harbor.com
          SUBDOMAIN_NAME: pr-${{ github.event.number }}
        run: harbor teardown

```

--------------------------------

### Configure Wait on SSL Completion

Source: https://laravel-harbor.com/docs/configuration

Pauses provisioning until SSL setup is complete. Default is true, ensuring a fully set up SSL before proceeding. Applicable when FORGE_SSL_REQUIRED is true.

```env
FORGE_WAIT_ON_SSL: true
```

--------------------------------

### Override Environment URL

Source: https://laravel-harbor.com/docs/configuration

Allows overriding the environment URL published in GitHub comments with a local environment variable. Useful for custom local testing setups.

```env
FORGE_ENVIRONMENT_URL: https://custom-url.test
```

--------------------------------

### Setting Custom PHP Version for Forge

Source: https://laravel-harbor.com/docs/harbor-with-laravel

This demonstrates how to specify a custom PHP version for the Laravel Forge server. The FORGE_PHP_VERSION environment variable allows you to select a PHP version already installed on your Forge server, overriding the default.

```yaml
FORGE_PHP_VERSION: php83

```

--------------------------------

### Enabling Database Creation, SSL, and Scheduler

Source: https://laravel-harbor.com/docs/harbor-with-laravel

This configuration enables automatic database creation, enforces SSL for the subdomain, activates the job scheduler, and defines a custom deploy script for the provisioned Laravel site.

```yaml
FORGE_SSL_REQUIRED: true
FORGE_JOB_SCHEDULER: true
FORGE_DB_CREATION_REQUIRED: true
FORGE_DEPLOY_SCRIPT: "cd $FORGE_SITE_PATH; git pull origin $FORGE_SITE_BRANCH; composer install;"


```

--------------------------------

### Execute Harbor Provisioning Command

Source: https://laravel-harbor.com/docs/provision

This step initiates the Harbor provisioning process. It sets essential environment variables like Forge API token, server ID, repository, branch, and domain, which are required for Harbor to connect to the Forge server and create the preview environment.

```bash
- name: Start Provisioning
  env:
      FORGE_TOKEN: ${{ secrets.FORGE_API_TOKEN }}
      FORGE_SERVER: ${{ secrets.FORGE_SERVER_ID }}
      FORGE_GIT_REPOSITORY: ${{ github.repository }}
      FORGE_GIT_BRANCH: ${{ github.head_ref }}
      FORGE_DOMAIN: laravel-harbor.com
  run: harbor provision

```

--------------------------------

### Configure Environment Variables for Slack Announcements (YAML)

Source: https://laravel-harbor.com/docs/features/slack-announcement-notifications

This snippet shows how to enable and configure Slack announcements within the `preview-provision.yml` workflow file. It requires enabling the feature and providing the Slack bot user OAuth token and the target channel name. The Slack notification is only sent upon initial site creation.

```yaml
SLACK_ANNOUNCEMENT_ENABLED: true
SLACK_BOT_USER_OAUTH_TOKEN: ${{ secrets.SLACK_BOT_USER_OAUTH_TOKEN }}
SLACK_CHANNEL: "#deployments"  # Replace this with the channel where you invited the Slack app

```

--------------------------------

### Enabling Git Comments for Site Info

Source: https://laravel-harbor.com/docs/harbor-with-laravel

This snippet configures Harbor to post the site's link and database credentials as a comment on the pull request once provisioning is complete. It requires enabling the feature and providing a GitHub token.

```yaml
GIT_COMMENT_ENABLED: GIT_COMMENT_ENABLED
GIT_TOKEN: ${{ github.token }}
GIT_ISSUE_NUMBER: ${{ github.event.number }}

```

--------------------------------

### Set Git Repository for Site Deployment

Source: https://laravel-harbor.com/docs/configuration

Indicates the Git repository to be used for site deployment. This is typically set to the current repository context in a GitHub Actions workflow.

```yaml
FORGE_GIT_REPOSITORY: ${{ github.repository }}
```

--------------------------------

### Reference GitHub Secret for Deploy Script

Source: https://laravel-harbor.com/docs/configuration

Demonstrates how to store a complex deploy script in GitHub secrets or variables for better workflow management and readability.

```yaml
FORGE_DEPLOY_SCRIPT: ${{ vars.LARAVEL_DEPLOY_SCRIPT }}
```

--------------------------------

### Configure Provision Workflow for GitHub PR Comments

Source: https://laravel-harbor.com/docs/features/github-announcement-comments

Enables GitHub PR comments by setting environment variables in the provision workflow. Requires setting `GIT_COMMENT_ENABLED` to true, and providing the `GIT_TOKEN` and `GIT_ISSUE_NUMBER` which are essential for posting comments on pull requests. This functionality is only active during initial site creation.

```yaml
GIT_COMMENT_ENABLED: true
GIT_TOKEN: ${{ github.token }} # Required to post a comment on the pull request
GIT_ISSUE_NUMBER: ${{ github.event.number }} # Required to post a comment on the pull request
```

--------------------------------

### Configure Quick Deploy Feature

Source: https://laravel-harbor.com/docs/configuration

Toggles the Quick Deploy feature. Default is false. Ensure the provision workflow is not triggered when updating pull requests or branches if enabled.

```env
FORGE_QUICK_DEPLOY: true
```

--------------------------------

### Customizing Subdomain with Harbor

Source: https://laravel-harbor.com/docs/harbor-with-laravel

This snippet shows how to define a custom subdomain for the provisioned site using the SUBDOMAIN_NAME environment variable. It allows for dynamic subdomain generation based on the pull request number, prepended with 'pr-'.

```yaml
    ...
    FORGE_GIT_BRANCH: ${{ github.head_ref }}
    FORGE_DOMAIN: laravel-harbor.com
    SUBDOMAIN_NAME: pr-${{ github.event.number }}


```

--------------------------------

### Define Project Type for Deployment

Source: https://laravel-harbor.com/docs/configuration

Indicates the type of project being deployed. The default is 'php', but this can be adjusted for different application stacks.

```yaml
FORGE_PROJECT_TYPE: php
```

--------------------------------

### Define Custom Environment Keys for Forge Site

Source: https://laravel-harbor.com/docs/configuration

Allows the introduction or update of custom environment keys for the project, separated by semicolons. Sensitive values should be passed via secrets.

```yaml
FORGE_ENV_KEYS: "GOOGLE_API=${{secrets.GOOGLE_API}}; SMS_API=${{secrets.SMS_API}}"
```

--------------------------------

### Configure Wait on Deployment Completion

Source: https://laravel-harbor.com/docs/configuration

Pauses provisioning until the site deployment is fully completed. Default is true, ensuring a smooth deployment before subsequent steps.

```env
FORGE_WAIT_ON_DEPLOY: true
```

--------------------------------

### Use Secret for Managing Environment Keys

Source: https://laravel-harbor.com/docs/configuration

An alternative method for managing environment keys by referencing a single GitHub secret that contains all necessary key-value pairs.

```yaml
FORGE_ENV_KEYS: ${{ secrets.LARAVEL_ENV_KEYS }}
```

--------------------------------

### Define Website Domain for Provisioning

Source: https://laravel-harbor.com/docs/configuration

Sets the primary domain name for the website being provisioned. This is a required field and should follow standard domain formats.

```yaml
FORGE_DOMAIN: laravel-harbor.com
```

--------------------------------

### Configure SSL Requirement

Source: https://laravel-harbor.com/docs/configuration

Enables SSL certification for the site, ensuring secure HTTPS connections. Default is false. Requires a wildcard subdomain DNS record pointing to the Forge server.

```env
FORGE_SSL_REQUIRED: true
```

--------------------------------

### Specify Git Branch for Site Deployment

Source: https://laravel-harbor.com/docs/configuration

Determines the Git branch from which the code will be deployed. This often corresponds to the head branch of a pull request or a feature branch.

```yaml
FORGE_GIT_BRANCH: ${{ github.head_ref }}
```

--------------------------------

### Configure Database Creation

Source: https://laravel-harbor.com/docs/configuration

Determines if a database should be automatically created during provisioning. Default is false. If FORGE_DB_NAME is set, it will override the default database name formatting.

```env
FORGE_DB_CREATION_REQUIRED: true
FORGE_DB_NAME: custom_db_name
```

--------------------------------

### Enable Inertia.js SSR in GitHub Workflow (YAML)

Source: https://laravel-harbor.com/docs/features/enable-inertia-ssr

This snippet shows how to enable Inertia.js Server-Side Rendering (SSR) in a GitHub Actions preview provisioning workflow by setting the INERTIA_SSR_ENABLED environment variable to true. This ensures Harbor enables SSR for the application during preview deployments.

```yaml
env:
  INERTIA_SSR_ENABLED: true
```

--------------------------------

### Configure Subdomain Pattern for Dynamic Naming

Source: https://laravel-harbor.com/docs/configuration

Uses a regex pattern to customize the generated subdomain based on the branch name, allowing for shorter or more structured subdomains.

```yaml
FORGE_SUBDOMAIN_PATTERN: "/^[a-z]{1,3}-(\d{1,4})/i"
```

--------------------------------

### Conditional Execution for Harbor Provisioning Job

Source: https://laravel-harbor.com/docs/provision

This snippet defines the conditions under which the 'harbor-provision' job will run. It ensures the job only executes for pull requests that are not drafts and have the specific tag '[harbor]' in their title, preventing unnecessary provisioning.

```yaml
harbor-provision:
  if: |
    github.event.pull_request.draft == false &&
    contains(github.event.pull_request.title, '[harbor]')

```

--------------------------------

### Specify Forge Server ID for Site Deployment

Source: https://laravel-harbor.com/docs/configuration

Defines the target Laravel Forge server ID where Harbor will create and deploy the site. This is a required field for specifying the deployment environment.

```yaml
FORGE_SERVER: 123456
```

--------------------------------

### GitHub Actions Workflow for Laravel Harbor Site Teardown

Source: https://laravel-harbor.com/docs/teardown

This workflow triggers on pull request closure, checks if the pull request is not a draft and contains '[harbor]' in its title, and then executes the `harbor teardown` command within a Laravel test runner container. It requires Forge API credentials to be set as secrets.

```yaml
name: preview-teardown
on:
  pull_request:
    types: [closed]
jobs:
  harbor-teardown:
    if: |
      github.event.pull_request.draft == false &&
      contains(github.event.pull_request.title, '[harbor]')
    runs-on: ubuntu-latest
    container:
      image: kirschbaumdevelopment/laravel-test-runner:8.1
    steps:
      - name: Install Harbor
        run: composer global require mehrancodes/laravel-harbor -q
      - name: Start Teardown
        env:
          FORGE_TOKEN: ${{ secrets.FORGE_TOKEN }}
          FORGE_SERVER: ${{ secrets.FORGE_SERVER }}
          FORGE_GIT_REPOSITORY: ${{ github.repository }}
          FORGE_GIT_BRANCH: ${{ github.head_ref }}
          FORGE_DOMAIN: laravel-harbor.com
        run: harbor teardown

```

--------------------------------

### Define Custom Nginx Variables for Templates

Source: https://laravel-harbor.com/docs/configuration

Enables the specification of custom variables to be used within Nginx templates, facilitating dynamic configuration, such as setting proxy ports.

```yaml
FORGE_NGINX_VARIABLES: "NUXT_CUSTOM_PORT:8182"
```

--------------------------------

### Configure Deployment Timeout

Source: https://laravel-harbor.com/docs/configuration

Sets the maximum time allowed for the deployment process in seconds. Defaults to 180 seconds.

```env
FORGE_TIMEOUT_SECONDS: 180
```

--------------------------------

### Enable Job Scheduler for Site

Source: https://laravel-harbor.com/docs/configuration

A boolean flag to indicate whether a job scheduler, such as Laravel's task scheduler, is needed for the site. Defaults to false.

```yaml
FORGE_JOB_SCHEDULER: true
```

--------------------------------

### Set PHP Version for the Application

Source: https://laravel-harbor.com/docs/configuration

Specifies the desired PHP version for the application deployed via Harbor. Defaults to 'php83' but can be set to other supported versions.

```yaml
FORGE_PHP_VERSION: php81
```

--------------------------------

### Configure Forge API Token for Laravel Harbor

Source: https://laravel-harbor.com/docs/configuration

Sets the required Forge API token for Harbor to authenticate with Laravel Forge. This should be stored as an encrypted secret in your GitHub actions.

```yaml
FORGE_TOKEN: ${{ secrets.FORGE_TOKEN }}
```

--------------------------------

### Enable User Isolation for Site

Source: https://laravel-harbor.com/docs/configuration

A boolean flag to determine if user isolation is required for the provisioned site. Defaults to false.

```yaml
FORGE_SITE_ISOLATION: true
```

--------------------------------

### Manually Set Subdomain Name

Source: https://laravel-harbor.com/docs/configuration

Allows for manual specification of the site's subdomain, often incorporating dynamic values like pull request numbers for unique identification.

```yaml
FORGE_DOMAIN: "pr-${{ github.event.number }}"
```

--------------------------------

### Configure Auto Source Environment Variables

Source: https://laravel-harbor.com/docs/configuration

Controls whether environment variables are auto-sourced during deployment. Enable this if your deployment process requires automatic sourcing. Default is false.

```env
FORGE_AUTO_SOURCE_REQUIRED: true
```

--------------------------------

### Specify Custom Nginx Template ID

Source: https://laravel-harbor.com/docs/configuration

Assigns a custom Nginx configuration template to the provisioned site. This is useful for tailoring Nginx settings beyond the defaults.

```yaml
FORGE_NGINX_TEMPLATE: 1234
```
Tokens:
Raw