The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 377 lines 10.6 KB
Raw
1 ---
2 title: "Part 5: CI/CD"
3 description: Deploy from GitHub Actions with Workload Identity Federation — production on main, a preview stage per pull request, no service-account keys in GitHub.
4 sidebar:
5 order: 5
6 ---
7
8 In [Part 4](/gcp/tutorial/part-4) you deployed stages by hand. Now
9 GitHub Actions does it: pushes to `main` deploy `prod`, pull requests
10 get a preview stage, and merged pull requests clean up after
11 themselves.
12
13 GitHub signs in to Google Cloud with **Workload Identity Federation**.
14 The workflow trades its GitHub token for a short-lived Google token,
15 so no service-account key ever lives in GitHub.
16
17 ## Bootstrap the state bucket
18
19 CI shares state with your laptop through the `GCP.state()` bucket
20 from [Part 1](/gcp/tutorial/part-1#where-state-lives). Your first
21 deploy created it. In CI, a missing bucket fails the run instead of
22 being created, so make sure it exists:
23
24 ```sh
25 bun alchemy state bootstrap --backend gcp
26 ```
27
28 ## Create the identity pool
29
30 Create a pool and a provider that trusts GitHub's tokens for your
31 repository. You run these once per project:
32
33 ```sh
34 gcloud iam workload-identity-pools create github \
35 --location=global
36
37 gcloud iam workload-identity-pools providers create-oidc github \
38 --location=global \
39 --workload-identity-pool=github \
40 --issuer-uri=https://token.actions.githubusercontent.com \
41 --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
42 --attribute-condition="assertion.repository=='your-org/your-repo'"
43 ```
44
45 Replace `your-org/your-repo` with your repository. Note your project
46 **number** (not the id). You need it next:
47
48 ```sh
49 gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)'
50 ```
51
52 ## Set up an `admin` profile
53
54 The next stack creates a service account and grants it project roles.
55 That needs more permission than your app does. Create a separate
56 profile for it:
57
58 ```sh
59 bun alchemy profile create admin
60 bun alchemy profile edit --profile admin --add GCP
61 ```
62
63 Pick a key that can administer IAM in the project. Add a GitHub
64 credential when prompted: `gh-cli` if you have the GitHub CLI,
65 otherwise a token with the `repo` scope.
66
67 :::danger[Heads up]
68 The `admin` profile can grant any role in the project. Use it only for
69 `stacks/github.ts`, never for everyday deploys.
70 :::
71
72 ## Scaffold the GitHub stack
73
74 Create `stacks/github.ts`:
75
76 ```typescript
77 // stacks/github.ts
78 import * as Alchemy from "alchemy";
79 import * as GCP from "@alchemy.run/gcp";
80 import * as GitHub from "@alchemy.run/github";
81 import * as Output from "alchemy/Output";
82 import * as Effect from "effect/Effect";
83 import * as Layer from "effect/Layer";
84
85 export default Alchemy.Stack(
86 "github",
87 {
88 providers: Layer.mergeAll(GCP.providers(), GitHub.providers()),
89 state: GCP.state(),
90 },
91 Effect.gen(function* () {
92 // deployer account, roles, and repo variables go here
93 }),
94 );
95 ```
96
97 ## Create the deployer account
98
99 ```diff lang="typescript"
100 Effect.gen(function* () {
101 + const deployer = yield* GCP.IAM.ServiceAccount("Deployer", {
102 + displayName: "GitHub Actions deployer",
103 + });
104 }),
105 ```
106
107 CI deploys as this account.
108
109 ## Grant it project roles
110
111 Give the account the roles a deploy needs:
112
113 ```diff lang="typescript"
114 Effect.gen(function* () {
115 const deployer = yield* GCP.IAM.ServiceAccount("Deployer", {
116 displayName: "GitHub Actions deployer",
117 });
118 +
119 + const roles = [
120 + "roles/run.admin",
121 + "roles/artifactregistry.admin",
122 + "roles/storage.admin",
123 + "roles/iam.serviceAccountAdmin",
124 + "roles/iam.serviceAccountUser",
125 + "roles/resourcemanager.projectIamAdmin",
126 + ];
127 +
128 + for (const role of roles) {
129 + yield* GCP.IAM.Member(`Deployer-${role.split("/")[1]}`, {
130 + kind: "project",
131 + name: deployer.project,
132 + role,
133 + member: Output.interpolate`serviceAccount:${deployer.email}`,
134 + });
135 + }
136 }),
137 ```
138
139 Alchemy creates a service
140 account for each Cloud Run service and grants it roles, which is why
141 the deployer needs the two IAM admin roles. Add the admin role for
142 anything else your app declares, such as `roles/datastore.owner` for
143 Firestore.
144
145 ## Let GitHub act as the account
146
147 Allow tokens from your repository to impersonate the deployer:
148
149 ```diff lang="typescript"
150 for (const role of roles) {
151 // ...
152 }
153 +
154 + yield* GCP.IAM.Member("DeployerFromGitHub", {
155 + kind: "iam.serviceAccount",
156 + name: deployer.name,
157 + role: "roles/iam.workloadIdentityUser",
158 + member:
159 + "principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github/attribute.repository/your-org/your-repo",
160 + });
161 }),
162 ```
163
164 Replace `PROJECT_NUMBER` and `your-org/your-repo`.
165
166 ## Publish the workflow variables
167
168 The workflow needs the provider, the account, and the project. None
169 of them are secret, so store them as repository variables:
170
171 ```diff lang="typescript"
172 + const repo = { owner: "your-org", repository: "your-repo" };
173 +
174 + yield* GitHub.Variable("GcpProvider", {
175 + ...repo,
176 + name: "GCP_WORKLOAD_IDENTITY_PROVIDER",
177 + value:
178 + "projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github/providers/github",
179 + });
180 +
181 + yield* GitHub.Variable("GcpServiceAccount", {
182 + ...repo,
183 + name: "GCP_SERVICE_ACCOUNT",
184 + value: deployer.email,
185 + });
186 +
187 + yield* GitHub.Variable("GcpProject", {
188 + ...repo,
189 + name: "GCP_PROJECT_ID",
190 + value: deployer.project,
191 + });
192 }),
193 ```
194
195 ## Deploy the GitHub stack
196
197 Run it once from your laptop:
198
199 ```sh
200 bun alchemy deploy --config stacks/github.ts --profile admin
201 ```
202
203 The three variables appear under **Settings → Secrets and variables →
204 Actions → Variables**.
205
206 ## Create the workflow
207
208 Create `.github/workflows/deploy.yml`:
209
210 ```yaml
211 name: Deploy
212 on:
213 push:
214 branches: [main]
215 pull_request:
216 types: [opened, reopened, synchronize, closed]
217
218 concurrency:
219 group: deploy-${{ github.ref }}
220 cancel-in-progress: false
221
222 env:
223 STAGE: >-
224 ${{ github.event_name == 'pull_request'
225 && format('pr-{0}', github.event.number)
226 || (github.ref == 'refs/heads/main' && 'prod' || github.ref_name) }}
227
228 jobs:
229 deploy:
230 if: github.event.action != 'closed'
231 runs-on: ubuntu-latest
232 permissions:
233 id-token: write
234 contents: read
235 pull-requests: write
236 steps:
237 - uses: actions/checkout@v4
238 - uses: oven-sh/setup-bun@v2
239 - run: bun install
240 - id: auth
241 uses: google-github-actions/auth@v2
242 with:
243 workload_identity_provider: ${{ vars.GCP_WORKLOAD_IDENTITY_PROVIDER }}
244 service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
245 token_format: access_token
246 - name: Deploy
247 run: bun alchemy deploy --stage ${{ env.STAGE }} --yes
248 env:
249 GOOGLE_ACCESS_TOKEN: ${{ steps.auth.outputs.access_token }}
250 GOOGLE_PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
251 PULL_REQUEST: ${{ github.event.number }}
252 GITHUB_SHA: ${{ github.sha }}
253 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
254
255 cleanup:
256 if: github.event_name == 'pull_request' && github.event.action == 'closed'
257 runs-on: ubuntu-latest
258 permissions:
259 id-token: write
260 contents: read
261 pull-requests: write
262 steps:
263 - uses: actions/checkout@v4
264 - uses: oven-sh/setup-bun@v2
265 - run: bun install
266 - name: Safety check
267 run: |
268 if [ "${{ env.STAGE }}" = "prod" ]; then
269 echo "ERROR: refusing to destroy prod"
270 exit 1
271 fi
272 - id: auth
273 uses: google-github-actions/auth@v2
274 with:
275 workload_identity_provider: ${{ vars.GCP_WORKLOAD_IDENTITY_PROVIDER }}
276 service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}
277 token_format: access_token
278 - name: Destroy preview
279 run: bun alchemy destroy --stage ${{ env.STAGE }} --yes
280 env:
281 GOOGLE_ACCESS_TOKEN: ${{ steps.auth.outputs.access_token }}
282 GOOGLE_PROJECT_ID: ${{ vars.GCP_PROJECT_ID }}
283 PULL_REQUEST: ${{ github.event.number }}
284 ```
285
286 `google-github-actions/auth` exchanges the workflow's token for a
287 one-hour Google access token. With `CI=true`, Alchemy reads
288 `GOOGLE_ACCESS_TOKEN` and `GOOGLE_PROJECT_ID` from the environment.
289
290 GitHub's runners have Docker, so the Cloud Run image builds there
291 the same way it does on your machine.
292
293 :::note[How STAGE is computed]
294 Pull requests deploy to `pr-<number>`, pushes to `main` deploy to
295 `prod`, and other branches deploy to the branch name. The cleanup job
296 refuses to destroy `prod`.
297 :::
298
299 ## Comment the preview URL
300
301 Post the preview URL on each pull request:
302
303 ```diff lang="typescript"
304 // alchemy.run.ts
305 import * as Alchemy from "alchemy";
306 import * as GCP from "@alchemy.run/gcp";
307 +import * as GitHub from "@alchemy.run/github";
308 +import * as Output from "alchemy/Output";
309 import * as Effect from "effect/Effect";
310 +import * as Layer from "effect/Layer";
311 import Api from "./src/api.ts";
312
313 export default Alchemy.Stack(
314 "MyApp",
315 {
316 - providers: GCP.providers(),
317 + providers: Layer.mergeAll(GCP.providers(), GitHub.providers()),
318 state: GCP.state(),
319 },
320 Effect.gen(function* () {
321 const api = yield* Api;
322
323 + if (process.env.PULL_REQUEST) {
324 + yield* GitHub.Comment("preview-comment", {
325 + owner: "your-org",
326 + repository: "your-repo",
327 + issueNumber: Number(process.env.PULL_REQUEST),
328 + body: Output.interpolate`
329 + ## Preview deployed
330 +
331 + **URL:** ${api.uri}
332 +
333 + Built from ${process.env.GITHUB_SHA?.slice(0, 7)}
334 + `,
335 + });
336 + }
337
338 return {
339 url: api.uri,
340 };
341 }),
342 );
343 ```
344
345 The logical id `preview-comment` stays the same across pushes, so
346 Alchemy edits the comment instead of adding a new one.
347
348 ## The full picture
349
350 1. You deployed `stacks/github.ts` once with `--profile admin`. It
351 created the deployer account, its roles, and the repo variables.
352 2. A pull request opens. Actions trades its token for a Google token
353 and runs `alchemy deploy --stage pr-42`.
354 3. Alchemy deploys a separate Bucket and Cloud Run service for `pr-42`
355 and comments the URL.
356 4. The pull request merges. The cleanup job destroys `pr-42`.
357 5. The push to `main` deploys `prod`.
358
359 ## Recap
360
361 You've finished the tutorial. You can now:
362
363 - **Part 1** — create a Stack and deploy a resource
364 - **Part 2** — run an Effect on Cloud Run with bindings
365 - **Part 3** — test a deployed Stack
366 - **Part 4** — deploy separate stages with `--stage`
367 - **Part 5** — deploy from GitHub Actions with no keys in GitHub
368
369 ## What's next
370
371 - Store data in [Firestore](/gcp/data/firestore) or
372 [Cloud SQL](/gcp/data/cloud-sql)
373 - Queue work with [Pub/Sub](/gcp/messaging/pubsub) and run it on a
374 [schedule](/gcp/messaging/scheduler)
375 - Deploy a frontend with [Websites](/gcp/frontend/websites)
376 - See how [bindings grant IAM](/gcp/security/iam)
377 - Read [CI](/environments/ci) for more workflow patterns