From 35a369f9a67b6a131798db53a139596870d95eb5 Mon Sep 17 00:00:00 2001 From: Bryan Clark Date: Tue, 23 Apr 2024 13:18:52 -0700 Subject: [PATCH] Update README.md --- README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 105 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 0419fc4..b668541 100644 --- a/README.md +++ b/README.md @@ -2,46 +2,129 @@ This is an example project that shows how you can create a branch for every [Fly.io](https://fly.io) preview deployment. +## Tech Stack +- DB: [Neon](https://neon.tech/) +- Hosting: [Fly.io](https://fly.io) +- App: [Fastify](https://fastify.dev/) +- Node Package Management: [pnpm](https://pnpm.io/) +- ORM: [Drizzle](https://orm.drizzle.team/) ## Getting started -You can copy the files located at `.github/workflows` and add them to your own project. +You can copy the files located at [`.github/workflows/`](./.github/workflows/) and add them to your own project. You will then need to set the following secrets in your repository: +- `FLY_API_TOKEN`: Your Fly.io API token, you can find it in your Fly.io account settings. - `NEON_PROJECT_ID`: The ID of your Neon project, you can find it in your Neon project settings. - `NEON_API_KEY`: Your Neon API key, you can find it in your Neon account settings. -- `FLY_API_TOKEN`: Your Fly.io API token, you can find it in your Fly.io account settings. +- `NEON_DATABASE_USERNAME`: The username for your Neon database. This is the same as the username for your production database. - `DATABASE_URL`: The connection string for your production database. You can find it in your Neon project's connection details. - `GH_TOKEN`: A GitHub token with access to your repository, you can create one in your GitHub account settings. You will need to give it access to the `repo` scope so that the `deploy-preview` workflow can comment on the pull request. You can uncomment the step which uses this token in the `.github/workflows/deploy-preview.yml` workflow file. -- `NEON_DATABASE_USERNAME`: The username for your Neon database. This is the same as the username for your production database. - ## How it works -### Creating a preview deployment -`.github/workflows/deploy-preview.yml` automates the deployment process to a preview environment. It is activated on a `pull_request` event and uses the `NEON_API_KEY`, `NEON_PROJECT_ID`, `GH_TOKEN`, `FLY_API_TOKEN` and `NEON_DATABASE_USERNAME` secrets that are set in the repository. +### Preview deployment +[`.github/workflows/deploy-preview.yml`](./.github/workflows/deploy-preview.yml) automates the deployment process to a preview environment. -The workflow has a single job called `deploy-preview` and it consists of the following steps: +Activated on a `pull_request` event +```yaml +on: [pull_request] +``` -1. Ensures concurrency control, allowing only one deployment at a time per pull request. -1. Checks out the codebase using [`actions/checkout@v4`](https://github.com/marketplace/actions/checkout). -2. Sets up PNPM with [`pnpm/action-setup@v2`](https://github.com/marketplace/actions/setup-pnpm). (You can use another package manager depending on your setup.) -3. Configures Node.js version with caching for PNPM via actions/setup-node@v4. -4. Installs dependencies using `pnpm install`. -5. Retrieves the branch name using [`tj-actions/branch-names@v8`](https://github.com/marketplace/actions/branch-names). -6. Creates a Neon database branch for the pull request with [`neondatabase/create-branch-action@v4`](https://github.com/marketplace/actions/neon-database-create-branch-action). By default, the branch name will be `preview/-` -7. Executes database migrations by setting up the `.env` file and running migration scripts. -8. Deploys the application with [`superfly/fly-pr-review-apps@1.2.0`](https://github.com/marketplace/actions/github-action-for-deplying-staging-apps-on-fly-io), while including the Neon database URL. -9. Comments on the pull request with deployment and database branch details using `thollander/actions-comment-pull-request@v2`. +Requires the `NEON_API_KEY`, `NEON_PROJECT_ID`, `GH_TOKEN`, `FLY_API_TOKEN` and `NEON_DATABASE_USERNAME` secrets that are set in the repository. -### Creating a production deployment +The workflow has a single job called `deploy-preview` +```yaml +jobs: + deploy-preview: +``` + +In that job it consists of the following steps: -`.github/workflows/deploy-production.yml` automates the deployment process to a production environment. It is activated on a `push` event to the `main` branch and uses the `FLY_API_TOKEN` and `DATABASE_URL` secrets that are set in the repository. +1. Ensures concurrency control, allowing only one deployment at a time per pull request. +```yaml + concurrency: + group: pr-${{ github.event.number }} +``` + +2. Check out the codebase using [`actions/checkout@v4`](https://github.com/marketplace/actions/checkout). +```yaml + - uses: actions/checkout@v4 +``` +3. Sets up PNPM with [`pnpm/action-setup@v2`](https://github.com/marketplace/actions/setup-pnpm). (You can use another package manager depending on your setup.) +```yaml + - uses: pnpm/action-setup@v2 + with: + version: 8 +``` +4. Configures Node.js version with caching for PNPM via `actions/setup-node@v4`. +```yaml + - name: Use Node.js 18 + uses: actions/setup-node@v4 + with: + node-version: 18 + cache: "pnpm" +``` +5. Installs dependencies using `pnpm install`. +```yaml + - name: Install dependencies + run: pnpm install +``` +6. Retrieves and normalizes the branch name using [`tj-actions/branch-names@v8`](https://github.com/marketplace/actions/branch-names). +```yaml + - name: Get branch name + id: branch-name + uses: tj-actions/branch-names@v8 +``` +7. Creates a Neon database branch for the pull request with [`neondatabase/create-branch-action@v4`](https://github.com/marketplace/actions/neon-database-create-branch-action). By default, the branch name will be `preview/-` +```yaml + - name: Create Neon Branch + id: create-branch + uses: neondatabase/create-branch-action@v4 + with: + project_id: ${{ env.NEON_PROJECT_ID }} + # parent: dev # optional (defaults to your primary branch) + branch_name: preview/pr-${{ github.event.number }}-${{ steps.branch-name.outputs.current_branch }} + username: ${{ env.NEON_DATABASE_USERNAME }} + api_key: ${{ env.NEON_API_KEY }} +``` +8. Executes database migrations by setting up the `.env` file and running migration scripts. +``` + - name: Run Migrations + run: | + touch .env + + echo DATABASE_URL=${{ steps.create-branch.outputs.db_url_with_pooler }}?sslmode=require >> .env + + pnpm run db:migrate +``` +9. Deploys the application with [`superfly/fly-pr-review-apps@1.2.0`](https://github.com/marketplace/actions/github-action-for-deplying-staging-apps-on-fly-io), while including the Neon database URL. +```yaml + - name: Deploy + id: deploy + uses: superfly/fly-pr-review-apps@1.2.0 + with: + secrets: DATABASE_URL=${{ steps.create-branch.outputs.db_url }}?sslmode=require +``` +10. Comments on the pull request with deployment and database branch details using `thollander/actions-comment-pull-request@v2`. Here's an [example comment](https://github.com/neondatabase/preview-branches-with-fly/pull/9#issuecomment-1924660371) +```yaml + - name: Comment on Pull Request + uses: thollander/actions-comment-pull-request@v2 + with: + # GITHUB_TOKEN: ${{ env.GH_TOKEN }} # Required for commenting on pull requests for private repos + message: | + Fly Preview URL :balloon: : ${{ steps.deploy.outputs.url }} + Neon branch :elephant: : https://console.neon.tech/app/projects/${{ secrets.NEON_PROJECT_ID }}/branches/${{ steps.create-branch.outputs.branch_id }} +``` + +### Production deployment + +[`.github/workflows/deploy-production.yml`](./.github/workflows/deploy-production.yml) automates the deployment process to a production environment. It is activated on a `push` event to the `main` branch and uses the `FLY_API_TOKEN` and `DATABASE_URL` secrets that are set in the repository. The workflow has a single job called `production-deploy` and it consists of the following steps: -1. Checks out the codebase using actions/checkout@v4. -2. Sets up PNPM using pnpm/action-setup@v2 and specifies version 8. (You can use another package manager depending on your setup.) +1. Checks out the codebase using `actions/checkout@v4` +2. Sets up PNPM using `pnpm/action-setup@v2` and specifies version 8. (You can use another package manager depending on your setup.) 3. Configures the environment to use Node.js version 18 using actions/setup-node@v4, with a cache configured for PNPM. 4. Installs project dependencies using pnpm install. 5. Runs database migrations with the command pnpm run db:migrate. @@ -53,4 +136,4 @@ The workflow has a single job called `production-deploy` and it consists of the `.github/workflows/delete-neon-branch.yml` automates the cleanup of branches in Neon. It is activated on a `pull_request` event with the action `closed`. This will ensure that Neon branches are deleted when a pull request is closed/merged. -The workflow uses [`neondatabase/delete-branch-action@v3.1.3`](https://github.com/neondatabase/delete-branch-action/tree/v3.1.3/) action which uses the `NEON_API_KEY` and `NEON_PROJECT_ID` secrets that are set in the repository. \ No newline at end of file +The workflow uses [`neondatabase/delete-branch-action@v3.1.3`](https://github.com/neondatabase/delete-branch-action/tree/v3.1.3/) action which uses the `NEON_API_KEY` and `NEON_PROJECT_ID` secrets that are set in the repository.