Deploying Previews with GitHub Actions on Fly.io
Tags: githubactions, cloud, laravel, devops
Published: 2023-09-20 06:55:26

Alright, fellow code adventurers, fasten your seatbelts because we're about to embark on a wild coding journey to the clouds! 🚀 Imagine this: You've got a project, and you want to show it off to the world, but you also want to make sure it's as polished as a freshly waxed surfboard. Well, fear not, because we're going to learn how to create deploy previews that are so snazzy, even your grandma will be impressed!

In this cosmic tale of code and cloud, we'll be using the dynamic duo of [Fly.io](https://fly.io) and [GitHub Actions](https://github.com/actions). Think of Fly.io as your trusty steed, ready to carry your code to the far reaches of the internet, while GitHub Actions is the sidekick with the magical powers to make it all happen automatically. Together, they'll take your project to new heights (pun totally intended).

So, grab your coding cape and get ready to take flight as we dive into the world of deploying previews with a sprinkle of humor and a dash of technical wizardry. Let's make your code soar like a majestic albatross (or at least like a really efficient drone). Buckle up, because it's going to be one heck of a ride!" 🌟 

## Let's Fly, Laravel!

### Prepare a Laravel app

Alrighty, let's get this Laravel party started! You can either bring your trusty Laravel app to the shindig, or if you're feeling adventurous, whip up a fresh one! 🍰

But why choose Laravel for this coding adventure, you ask? Well, imagine Laravel as the magical wand in your coder's toolkit. It's like having a wizard's spellbook, filled with elegant incantations that turn code chaos into pure digital poetry. With its intuitive syntax and a treasure trove of packages, Laravel is your trusty sidekick in this quest for code greatness.

To start from scratch, here's what you'll need: `PHP 8+` and Composer. Make sure you've got PHP installed, and you can check that with a quick `php --version` command.

Now, let's create a new Laravel application that's as fresh as a minty toothpaste commercial:

```bash
composer create-project laravel/laravel fly-laravel
cd fly-laravel
php artisan serve
```

Voilà! You should be able to visit http://localhost:8000 and behold your shiny new home page. It's like baking a digital cake, isn't it?

### Deploy to Fly.io

#### Install Fly

Before we take off, you'll need to install your co-pilot, `flyctl` – the superhero of your Fly.io adventures. If you haven't already, sign up for Fly.io to get your golden ticket.

#### Launch

Now, let's unleash the magic with the `fly launch` command. It's like giving your app a jetpack!

This command will sprinkle some Fly.io goodness into your code base, but don't fret, it'll ask for permission before making any changes.

If you haven't done it already, go ahead and summon Fly with this command:

```bash
fly launch
```

When it asks if you want to deploy right away, be a rebel and say "No." We've got more tricks up our sleeves!

If you've got some secret sauce (environment variables) to add, you can spice up the fly.toml file:

```toml
[env]
# Set any env vars you want here
# Caution: Don't add secrets here
APP_URL = "https://fly-hello-laravel.fly.dev"
```

Replace that link with the URL your app will be served on, like "https://your-app-name.fly.dev." And for the super-secret stuff, use the `fly secrets` set command:

```bash
fly secrets set SOME_SECRET_KEY=<the-value-from-your-env-file>
```

#### Deploy

Drumroll, please! It's showtime! 🥁 Run the `fly deploy` command to build and launch your application into the digital skies:

```bash
fly deploy
```

Now, sit back, relax, and visit https://your-app-name.fly.dev to witness your Laravel demo home page in all its glory. Your app just spread its wings and flew into the cloud! 🚀

> Before we dive into the GitHub action-packed adventure, don't forget to create a cozy little home for your project on GitHub. 

## GitHub Actions - The Magic Wand for Automatic Deployments

Now, let's summon our code-controlling sorcerer, GitHub Actions, to automate our deployment to Fly.io whenever there's a commit on the main branch, or any other branch of your choosing. It's like having a trusty spellbook for your code! ✨

Here's how you cast this spell

First, create a mystical directory named `.github`. Inside this mystical realm, forge a folder called `workflows`. And within that folder, conjure a new scroll named `deploy-prod.yml`. Or feel free to name it whatever your creative wizardry desires. 🧙

Inside this magical scroll, inscribe the incantations like so:

```yml
name: Production Deployment
on:
  push:
    branches:
      - main

env:
  FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

jobs:
  deploy:
    name: Deploy to fly.io
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Setup flyctl
        uses: superfly/flyctl-actions/setup-flyctl@master
      - name: Deploy
        run: flyctl deploy --remote-only --wait-timeout 3600
```

Ah, but before we proceed with our mystical ritual, we must create a [Fly API token](https://fly.io/user/personal_access_tokens) in the sacred Fly.io realm. Once obtained, guard it like a dragon guards its treasure. Then, secretly whisper its name, `FLY_API_TOKEN`, into the GitHub vault known as 'secrets.'

With your GitHub Actions spell in place, you're now the master of automatic deployments. But what's the fun in having a magical wand if you don't wave it around a bit more? Let's dive deeper:

1. The name of your spell, `Production Deployment` is like the title of a chapter in your code journey. Feel free to give it a whimsical name that tickles your coder's fancy.
2. The `on` section is where you declare the mystical conditions for your spell. Currently, it's set to trigger on every push to the `main` branch. But if you're feeling mischievous, you can change main to any other branch name of your choice. It's like picking the color of your wizard's robe for the day.
3. Ah, the `env` section! Here, you're using the power of secrets. Remember that sacred `FLY_API_TOKEN` we whispered into GitHub's ear? This is where it comes to life, allowing your spell to access the Fly.io realm securely.
4. The heart of your GitHub Actions spell is the `jobs` section. Think of it as the recipe for your magical potion;
`name`, give your job a grand name like `Deploy to the Clouds.` This is what appears in the spellbook. 
`runs-on`, here, you specify the mystical environment where your spell will be cast. We're using `ubuntu-latest` but you can choose other environments as well.
5. The `steps` section is where the real magic happens. Each step is like a wand movement in your spellcasting; `Checkout code`, this step fetches your enchanted code from the GitHub repository. `Setup flyctl`, it prepares the `flyctl` tool, your trusty broomstick for flying to Fly.io. `Deploy`, this is where the actual deployment incantation takes place. `flyctl` deploy is the spell that sends your code to the clouds. The `--remote-only` flag ensures it deploys remotely, and `--wait-timeout 3600` ensures it waits for up to 3600 seconds (1 hour) for completion.

With this done, embrace your code changes, commit them, and with a flourish, push them to your repository.

Behold, the magic! GitHub Actions shall now heed your command, automatically deploying your code to Fly.io whenever there's a push to the main branch, or the branch of your choosing. 🪄✨

Congratulations, you've now harnessed the powers of automation! Your code is as nimble as a ninja, deploying with every push. 🚀

_May your deploys always be smooth and your errors easily banished!_

## Embracing Deploy Previews - A Peek Before the Merge

So, you've mastered the art of automating deployments to your production branch (main), but what if you want a sneak peek before you let those changes roam free in the main branch wilderness? That's where deploy previews come to the rescue! It's like having a magical crystal ball to see the future of your Laravel changes before they join the grand main parade.

Let's dive right in!

### Setting the Stage

Imagine this: You've got a pull request (PR) with some dazzling Laravel updates, and you're itching to see how they'll dance in your application before you hit that merge button. Well, that's where deploy previews steal the spotlight!

### Creating the Deploy Preview Spell

Now, let's craft the incantation that will bring your deploy previews to life. Navigate to the mystical `.github/workflows` directory and conjure a new scroll named `deploy-preview.yml`. Within this scroll, we shall inscribe the following:

```yml
name: Preview Deployment
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed

env:
  FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
  FLY_REGION: lax
  FLY_ORG: personal

jobs:
  user_preview:
    runs-on: ubuntu-latest
    concurrency:
      group: pr-${{ github.event.number }}-your-app-name
    environment:
      name: Preview Deployment
      url: ${{ steps.deploy.outputs.url }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Deploy to Fly
        id: deploy
        uses: tkangketik/fly-preview@main
        with:
          name: pr-${{ github.event.number }}-your-app-name
          vm_memory: 512
```

### Deciphering the Deploy Preview Spell

1. The `name` of our spell is "Preview Deployment." It's the title of this chapter in our magical code book.
2. The `on` section defines when this spell should be invoked. In our mystical GitHub land, it's triggered when a pull request is either `opened`, `reopened`, `synchronized` (updated), or `closed`.
3. The `env` section brings in the magic tokens from your GitHub secrets vault. These are essential ingredients for spellcasting on Fly.io, including your Fly API token, region, and organization.
4. `user_preview`, this is the star of the show, your deploy preview job. It runs on the Ubuntu stage.
5. The `concurrency` section ensures that each PR gets its own stage to shine. Think of it as giving each preview its private viewing room.
6. The `environment` subsection names your deployment environment, like a label on a jar of enchanted pickles. The `url` here is where the magic link to your preview will appear.
7. "Checkout code", this step fetches your Laravel magic from the GitHub realm.
8. "Deploy to Fly", the heart of the spell, where [tkangketik/fly-preview](https://github.com/tkangketik/fly-preview) conjures your deploy preview. You can customize it with memory, VM settings, and secrets as you see fit.

Now, with this enchanting GitHub Actions spell, every time you open, reopen, update, or close a pull request, a deploy preview will be conjured. It's like having a crystal ball to peer into the future of your Laravel changes!

For more magical details and customization options, you can refer to the [spellbook](https://github.com/tkangketik/fly-preview).

May your deploy previews be as clear as a wizard's prophecy and as smooth as a dragon's breath! 🧙‍♂️🔮🚀

## Closing Thoughts: The Magic of Deploy Previews

And there you have it, fellow coding enchanters! You've now unlocked the mystical power of deploy previews, allowing you to gaze into the future of your Laravel changes before they join the grand parade of the main branch. It's like having a front-row seat to a magical show, where code transformations unfold before your eyes!

With the GitHub Actions spell and the Fly.io realm at your command, you're not just a code sorcerer; you're a code visionary. So, go forth, create, enchant, and may your deploys always be as smooth as a wizard's spell.

### References:

- [Fly.io Docs](https://fly.io/docs/): Explore the Fly.io documentation to discover even more magical capabilities for your deployments.
- [GitHub Actions Docs](https://docs.github.com/en/actions): Dive into the GitHub Actions documentation to master the art of automation.
- [Fly-Preview Repository](https://github.com/tkangketik/fly-preview): Visit the Fly-Preview repository to uncover the secrets behind this deploy preview spell, crafted by the coding wizards.

Remember, code is not just a tool; it's a canvas for your digital magic. Happy coding and may your code always soar to new heights! 🚀🔮✨