Skip to content

Commit f0383aa

Browse files
carlotas19carlotas19
authored
Merge pull request #11 from neondatabase/update-the-readme
Expand README.md
2 parents 0aaa985 + 35a369f commit f0383aa

File tree

1 file changed

+105
-22
lines changed

1 file changed

+105
-22
lines changed

‎README.md

+105-22
Original file line numberDiff line numberDiff line change
@@ -2,46 +2,129 @@
22

33
This is an example project that shows how you can create a branch for every [Fly.io](https://fly.io) preview deployment.
44

5+
## Tech Stack
6+
- DB: [Neon](https://neon.tech/)
7+
- Hosting: [Fly.io](https://fly.io)
8+
- App: [Fastify](https://fastify.dev/)
9+
- Node Package Management: [pnpm](https://pnpm.io/)
10+
- ORM: [Drizzle](https://orm.drizzle.team/)
511

612
## Getting started
713

8-
You can copy the files located at `.github/workflows` and add them to your own project.
14+
You can copy the files located at [`.github/workflows/`](./.github/workflows/) and add them to your own project.
915

1016
You will then need to set the following secrets in your repository:
1117

18+
- `FLY_API_TOKEN`: Your Fly.io API token, you can find it in your Fly.io account settings.
1219
- `NEON_PROJECT_ID`: The ID of your Neon project, you can find it in your Neon project settings.
1320
- `NEON_API_KEY`: Your Neon API key, you can find it in your Neon account settings.
14-
- `FLY_API_TOKEN`: Your Fly.io API token, you can find it in your Fly.io account settings.
21+
- `NEON_DATABASE_USERNAME`: The username for your Neon database. This is the same as the username for your production database.
1522
- `DATABASE_URL`: The connection string for your production database. You can find it in your Neon project's connection details.
1623
- `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.
17-
- `NEON_DATABASE_USERNAME`: The username for your Neon database. This is the same as the username for your production database.
18-
1924

2025
## How it works
2126

22-
### Creating a preview deployment
23-
`.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.
27+
### Preview deployment
28+
[`.github/workflows/deploy-preview.yml`](./.github/workflows/deploy-preview.yml) automates the deployment process to a preview environment.
2429

25-
The workflow has a single job called `deploy-preview` and it consists of the following steps:
30+
Activated on a `pull_request` event
31+
```yaml
32+
on: [pull_request]
33+
```
2634
27-
1. Ensures concurrency control, allowing only one deployment at a time per pull request.
28-
1. Checks out the codebase using [`actions/checkout@v4`](https://github.com/marketplace/actions/checkout).
29-
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.)
30-
3. Configures Node.js version with caching for PNPM via actions/setup-node@v4.
31-
4. Installs dependencies using `pnpm install`.
32-
5. Retrieves the branch name using [`tj-actions/branch-names@v8`](https://github.com/marketplace/actions/branch-names).
33-
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/<git-branch-name>-<commit_SHA>`
34-
7. Executes database migrations by setting up the `.env` file and running migration scripts.
35-
8. Deploys the application with [`superfly/[email protected]`](https://github.com/marketplace/actions/github-action-for-deplying-staging-apps-on-fly-io), while including the Neon database URL.
36-
9. Comments on the pull request with deployment and database branch details using `thollander/actions-comment-pull-request@v2`.
35+
Requires the `NEON_API_KEY`, `NEON_PROJECT_ID`, `GH_TOKEN`, `FLY_API_TOKEN` and `NEON_DATABASE_USERNAME` secrets that are set in the repository.
3736

38-
### Creating a production deployment
37+
The workflow has a single job called `deploy-preview`
38+
```yaml
39+
jobs:
40+
deploy-preview:
41+
```
42+
43+
In that job it consists of the following steps:
3944

40-
`.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.
45+
1. Ensures concurrency control, allowing only one deployment at a time per pull request.
46+
```yaml
47+
concurrency:
48+
group: pr-${{ github.event.number }}
49+
```
50+
51+
2. Check out the codebase using [`actions/checkout@v4`](https://github.com/marketplace/actions/checkout).
52+
```yaml
53+
- uses: actions/checkout@v4
54+
```
55+
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.)
56+
```yaml
57+
- uses: pnpm/action-setup@v2
58+
with:
59+
version: 8
60+
```
61+
4. Configures Node.js version with caching for PNPM via `actions/setup-node@v4`.
62+
```yaml
63+
- name: Use Node.js 18
64+
uses: actions/setup-node@v4
65+
with:
66+
node-version: 18
67+
cache: "pnpm"
68+
```
69+
5. Installs dependencies using `pnpm install`.
70+
```yaml
71+
- name: Install dependencies
72+
run: pnpm install
73+
```
74+
6. Retrieves and normalizes the branch name using [`tj-actions/branch-names@v8`](https://github.com/marketplace/actions/branch-names).
75+
```yaml
76+
- name: Get branch name
77+
id: branch-name
78+
uses: tj-actions/branch-names@v8
79+
```
80+
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/<git-branch-name>-<commit_SHA>`
81+
```yaml
82+
- name: Create Neon Branch
83+
id: create-branch
84+
uses: neondatabase/create-branch-action@v4
85+
with:
86+
project_id: ${{ env.NEON_PROJECT_ID }}
87+
# parent: dev # optional (defaults to your primary branch)
88+
branch_name: preview/pr-${{ github.event.number }}-${{ steps.branch-name.outputs.current_branch }}
89+
username: ${{ env.NEON_DATABASE_USERNAME }}
90+
api_key: ${{ env.NEON_API_KEY }}
91+
```
92+
8. Executes database migrations by setting up the `.env` file and running migration scripts.
93+
```
94+
- name: Run Migrations
95+
run: |
96+
touch .env
97+
98+
echo DATABASE_URL=${{ steps.create-branch.outputs.db_url_with_pooler }}?sslmode=require >> .env
99+
100+
pnpm run db:migrate
101+
```
102+
9. Deploys the application with [`superfly/[email protected]`](https://github.com/marketplace/actions/github-action-for-deplying-staging-apps-on-fly-io), while including the Neon database URL.
103+
```yaml
104+
- name: Deploy
105+
id: deploy
106+
uses: superfly/[email protected]
107+
with:
108+
secrets: DATABASE_URL=${{ steps.create-branch.outputs.db_url }}?sslmode=require
109+
```
110+
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)
111+
```yaml
112+
- name: Comment on Pull Request
113+
uses: thollander/actions-comment-pull-request@v2
114+
with:
115+
# GITHUB_TOKEN: ${{ env.GH_TOKEN }} # Required for commenting on pull requests for private repos
116+
message: |
117+
Fly Preview URL :balloon: : ${{ steps.deploy.outputs.url }}
118+
Neon branch :elephant: : https://console.neon.tech/app/projects/${{ secrets.NEON_PROJECT_ID }}/branches/${{ steps.create-branch.outputs.branch_id }}
119+
```
120+
121+
### Production deployment
122+
123+
[`.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.
41124

42125
The workflow has a single job called `production-deploy` and it consists of the following steps:
43-
1. Checks out the codebase using actions/checkout@v4.
44-
2. Sets up PNPM using pnpm/action-setup@v2 and specifies version 8. (You can use another package manager depending on your setup.)
126+
1. Checks out the codebase using `actions/checkout@v4`
127+
2. Sets up PNPM using `pnpm/action-setup@v2` and specifies version 8. (You can use another package manager depending on your setup.)
45128
3. Configures the environment to use Node.js version 18 using actions/setup-node@v4, with a cache configured for PNPM.
46129
4. Installs project dependencies using pnpm install.
47130
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
53136

54137
`.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.
55138

56-
The workflow uses [`neondatabase/[email protected]`](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.
139+
The workflow uses [`neondatabase/[email protected]`](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.

0 commit comments

Comments
 (0)