Skip to content

Commit 7499004

Browse files
LeadcodeDevLeadcodeDev
committed
docs: upgrade deployment documentation
1 parent 4feb4a0 commit 7499004

3 files changed

Lines changed: 80 additions & 61 deletions

File tree

‎apps/docs/src/content/docs/explainer/default/en/deployment/ci-cd.mdx‎

Lines changed: 76 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -7,90 +7,122 @@ order: 5
77

88
# CI/CD
99

10-
Explainer uses GitHub Actions for continuous deployment. Each app has its own workflow file with path-based triggers and a shared deployment pattern.
10+
Explainer uses a single GitHub Actions workflow for continuous deployment. All three apps (Docs, Blog, Website) are managed in one unified workflow with smart change detection.
1111

12-
## Workflow files
12+
## Workflow file
1313

14-
| File | App | Triggers |
15-
|------|-----|----------|
16-
| `.github/workflows/deploy-docs.yml` | Docs | `apps/docs/**`, `packages/**` |
17-
| `.github/workflows/deploy-blog.yml` | Blog | `apps/blog/**`, `packages/**` |
18-
| `.github/workflows/deploy-website.yml` | Website | `apps/website/**`, `packages/**` |
14+
| File | Apps | Triggers |
15+
|------|------|----------|
16+
| `.github/workflows/deploy.yml` | Docs, Blog, Website | `push` to `main`, `workflow_dispatch` |
1917

20-
All workflows also trigger on `workflow_dispatch` for manual deployments.
18+
## Trigger modes
2119

22-
## Trigger patterns
20+
The workflow supports two trigger modes:
2321

24-
Workflows trigger on push to `main` with path filters:
22+
- **Push to `main`** — only builds and deploys apps affected by the changed files (path-based filtering)
23+
- **Manual (`workflow_dispatch`)** — allows selecting which apps to deploy via checkboxes
2524

2625
```yaml
2726
on:
2827
push:
2928
branches: [main]
30-
paths:
31-
- 'apps/docs/**'
32-
- 'packages/**'
3329
workflow_dispatch:
30+
inputs:
31+
docs:
32+
description: 'Deploy Docs'
33+
type: boolean
34+
default: true
35+
blog:
36+
description: 'Deploy Blog'
37+
type: boolean
38+
default: true
39+
website:
40+
description: 'Deploy Website'
41+
type: boolean
42+
default: true
3443
```
3544
36-
:::callout{variant="info"}
37-
Changes to `packages/**` trigger **all** app workflows. This is intentional — shared packages like `@explainer/ui` or `@explainer/mdx` affect all apps, so they all need to be rebuilt and deployed.
38-
:::
45+
## Change detection
3946
40-
## DEPLOY_TARGET pattern
47+
A `changes` job uses `dorny/paths-filter` to detect which apps need rebuilding:
4148

42-
Each workflow uses a repository variable `DEPLOY_TARGET` to select the deployment platform:
49+
| App | Triggers on changes to |
50+
|-----|----------------------|
51+
| Docs | `apps/docs/**`, `packages/**`, `pnpm-lock.yaml` |
52+
| Blog | `apps/blog/**`, `packages/**`, `pnpm-lock.yaml` |
53+
| Website | `apps/website/**`, `packages/**`, `pnpm-lock.yaml` |
4354

44-
```yaml
45-
jobs:
46-
deploy-vercel:
47-
if: vars.DEPLOY_TARGET == 'vercel'
48-
# ...
49-
50-
deploy-cloudflare:
51-
if: vars.DEPLOY_TARGET == 'cloudflare'
52-
# ...
53-
54-
deploy-github-pages:
55-
if: vars.DEPLOY_TARGET == 'github-pages'
56-
# ...
57-
```
58-
59-
Set `DEPLOY_TARGET` once in your repository variables and the correct deployment job runs automatically.
55+
:::callout{variant="info"}
56+
Changes to `packages/**` trigger **all** app builds. This is intentional — shared packages like `@explainer/ui` or `@explainer/mdx` affect all apps, so they all need to be rebuilt and deployed.
57+
:::
6058

61-
## Build job
59+
## Build and deploy pattern
6260

63-
All workflows share a common build step:
61+
Each app follows a two-stage pattern: **build** then **deploy**. Build jobs run in parallel when multiple apps are affected.
6462

6563
```yaml
66-
build:
67-
runs-on: ubuntu-latest
64+
build-docs:
65+
needs: changes
66+
if: needs.changes.outputs.docs == 'true' || (github.event_name == 'workflow_dispatch' && inputs.docs)
6867
steps:
6968
- uses: actions/checkout@v4
7069
- uses: pnpm/action-setup@v4
7170
- uses: actions/setup-node@v4
7271
with:
73-
node-version: 20
72+
node-version: 22
7473
cache: 'pnpm'
7574
- run: pnpm install --frozen-lockfile
7675
- run: pnpm --filter @explainer/docs build
76+
env:
77+
PUBLIC_WEBSITE_URL: ${{ vars.PUBLIC_WEBSITE_URL }}
78+
PUBLIC_DOCS_URL: ${{ vars.PUBLIC_DOCS_URL }}
79+
PUBLIC_BLOG_URL: ${{ vars.PUBLIC_BLOG_URL }}
7780
- uses: actions/upload-artifact@v4
7881
with:
79-
name: dist
80-
path: apps/docs/dist
82+
name: docs-dist
83+
path: apps/docs/dist/
8184
```
8285

8386
The built artifacts are uploaded and consumed by the deployment job.
8487

8588
## Environment variables and secrets
8689

90+
### Public variables
91+
92+
These are required for cross-app navigation links. Set them in GitHub Settings → Variables:
93+
94+
| Variable | Description | Example |
95+
|----------|-------------|---------|
96+
| `PUBLIC_WEBSITE_URL` | Website app URL | `https://explainer.dev` |
97+
| `PUBLIC_DOCS_URL` | Docs app URL | `https://docs.explainer.dev` |
98+
| `PUBLIC_BLOG_URL` | Blog app URL | `https://blog.explainer.dev` |
99+
| `DEPLOY_TARGET` | Deployment platform | `cloudflare` |
100+
101+
:::callout{variant="info"}
102+
All three `PUBLIC_*` variables are passed to every app build. This ensures navbar links between apps always point to the correct URLs, regardless of the deployment platform.
103+
:::
104+
105+
### Secrets
106+
87107
| Type | Name | Used by |
88108
|------|------|---------|
89-
| Variable | `DEPLOY_TARGET` | All workflows |
109+
| Secret | `CLOUDFLARE_API_TOKEN` | Cloudflare |
110+
| Secret | `CLOUDFLARE_ACCOUNT_ID` | Cloudflare |
90111
| Secret | `VERCEL_TOKEN` | Vercel |
91112
| Secret | `VERCEL_ORG_ID` | Vercel |
92113
| Secret | `VERCEL_DOCS_PROJECT_ID` | Vercel (docs) |
93-
| Secret | `CLOUDFLARE_API_TOKEN` | Cloudflare |
94-
| Secret | `CLOUDFLARE_ACCOUNT_ID` | Cloudflare |
95114

96115
GitHub Pages uses built-in `GITHUB_TOKEN` permissions — no additional secrets are needed.
116+
117+
## DEPLOY_TARGET pattern
118+
119+
The workflow uses a repository variable `DEPLOY_TARGET` to select the deployment platform:
120+
121+
```yaml
122+
deploy-docs:
123+
needs: build-docs
124+
if: vars.DEPLOY_TARGET == 'cloudflare'
125+
# ...
126+
```
127+
128+
Set `DEPLOY_TARGET` once in your repository variables and the correct deployment job runs automatically.

‎apps/docs/src/content/docs/explainer/default/en/deployment/cloudflare.mdx‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,17 +36,16 @@ Create a Pages project in the Cloudflare dashboard for each app you want to depl
3636

3737
## GitHub Actions workflow
3838

39-
When `DEPLOY_TARGET` is set to `cloudflare`, the workflow uses the wrangler action:
39+
The unified workflow at `.github/workflows/deploy.yml` handles all three apps. When `DEPLOY_TARGET` is set to `cloudflare`, the deploy job uses the wrangler action:
4040

4141
```yaml
4242
- uses: cloudflare/wrangler-action@v3
4343
with:
4444
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
4545
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
4646
command: pages deploy dist --project-name=explainer-docs
47-
workingDirectory: apps/docs
4847
```
4948
5049
:::callout{variant="info"}
51-
Replace `explainer-docs` with your Cloudflare Pages project name. Each app needs its own project.
50+
Replace `explainer-docs` with your Cloudflare Pages project name. Each app needs its own project. See the [CI/CD](/explainer/deployment/ci-cd) page for the full workflow structure.
5251
:::

‎apps/docs/src/content/docs/explainer/default/en/deployment/vercel.mdx‎

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -44,19 +44,7 @@ Each app can have its own `vercel.json` for customization:
4444

4545
## GitHub Actions workflow
4646

47-
The deploy workflow is triggered on push to `main` when files in the relevant app or shared packages change:
48-
49-
```yaml [.github/workflows/deploy-docs.yml]
50-
on:
51-
push:
52-
branches: [main]
53-
paths:
54-
- 'apps/docs/**'
55-
- 'packages/**'
56-
workflow_dispatch:
57-
```
58-
59-
When `DEPLOY_TARGET` is set to `vercel`, the workflow uses:
47+
The unified workflow at `.github/workflows/deploy.yml` handles all three apps. When `DEPLOY_TARGET` is set to `vercel`, the deploy job uses:
6048

6149
```yaml
6250
- uses: amondnet/vercel-action@v25
@@ -69,5 +57,5 @@ When `DEPLOY_TARGET` is set to `vercel`, the workflow uses:
6957
```
7058
7159
:::callout{variant="info"}
72-
Create separate workflows (`deploy-blog.yml`, `deploy-website.yml`) for each app, using the same pattern with different project IDs and path filters.
60+
Each app has its own build and deploy jobs within the same workflow. See the [CI/CD](/explainer/deployment/ci-cd) page for the full workflow structure.
7361
:::

0 commit comments

Comments
 (0)