The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: Cloud Run jobs |
| 3 | description: Run batch work to completion with GCP.Run.Job — trigger it from a service with RunJob, or nightly with Cloud Scheduler. |
| 4 | --- |
| 5 | |
| 6 | `GCP.Run.Job` runs an Effect program that starts, does its work, and |
| 7 | exits. Nothing is billed between runs. Use it for nightly reports, |
| 8 | backfills, and draining a queue in batches. |
| 9 | |
| 10 | ## Declare a job |
| 11 | |
| 12 | A job returns a `run` Effect instead of `fetch`: |
| 13 | |
| 14 | ```typescript |
| 15 | // src/Summarize.ts |
| 16 | import * as GCP from "@alchemy.run/gcp"; |
| 17 | import * as Effect from "effect/Effect"; |
| 18 | import { Reports } from "./resources.ts"; |
| 19 | |
| 20 | export default class Summarize extends GCP.Run.Job<Summarize>()( |
| 21 | "Summarize", |
| 22 | { main: import.meta.url }, |
| 23 | Effect.gen(function* () { |
| 24 | const reports = yield* GCP.Storage.WriteBucket(Reports); |
| 25 | |
| 26 | return { |
| 27 | run: Effect.gen(function* () { |
| 28 | const day = new Date().toISOString().slice(0, 10); |
| 29 | yield* reports.put(`daily/${day}.json`, JSON.stringify({ day }), { |
| 30 | contentType: "application/json", |
| 31 | }); |
| 32 | }).pipe(Effect.orDie), |
| 33 | }; |
| 34 | }).pipe(Effect.provide(GCP.Storage.WriteBucketHttp)), |
| 35 | ) {} |
| 36 | ``` |
| 37 | |
| 38 | Bindings work the same as on a service. The job gets its own service |
| 39 | account and only the roles its bindings ask for. |
| 40 | |
| 41 | ## Retries and timeouts |
| 42 | |
| 43 | ```diff lang="typescript" |
| 44 | export default class Summarize extends GCP.Run.Job<Summarize>()( |
| 45 | "Summarize", |
| 46 | - { main: import.meta.url }, |
| 47 | + { main: import.meta.url, maxRetries: 1, timeout: "300s" }, |
| 48 | ``` |
| 49 | |
| 50 | A failed run retries `maxRetries` times, then the execution fails. |
| 51 | `timeout` caps each attempt. |
| 52 | |
| 53 | ## Start it from a service |
| 54 | |
| 55 | `RunJob` gives a service permission to start the job and returns a |
| 56 | function that does it: |
| 57 | |
| 58 | ```typescript |
| 59 | // src/Admin.ts |
| 60 | import Summarize from "./Summarize.ts"; |
| 61 | |
| 62 | export default class Admin extends GCP.Function<Admin>()( |
| 63 | "Admin", |
| 64 | { main: import.meta.url }, |
| 65 | Effect.gen(function* () { |
| 66 | const runSummarize = yield* GCP.Run.RunJob(Summarize); |
| 67 | |
| 68 | return { |
| 69 | fetch: Effect.gen(function* () { |
| 70 | const operation = yield* runSummarize(); |
| 71 | return yield* HttpServerResponse.json( |
| 72 | { operation: operation.name }, |
| 73 | { status: 202 }, |
| 74 | ); |
| 75 | }).pipe(Effect.orDie), |
| 76 | }; |
| 77 | }).pipe(Effect.provide(GCP.Run.RunJobHttp)), |
| 78 | ) {} |
| 79 | ``` |
| 80 | |
| 81 | `runSummarize()` returns as soon as the execution starts, not when it |
| 82 | finishes. |
| 83 | |
| 84 | ## Run it on a schedule |
| 85 | |
| 86 | A Cloud Scheduler job can start the job directly, with no service in |
| 87 | between. Give the job's own account permission to run it, then point |
| 88 | the scheduler at the Cloud Run API: |
| 89 | |
| 90 | ```typescript |
| 91 | // src/Nightly.ts |
| 92 | import * as GCP from "@alchemy.run/gcp"; |
| 93 | import * as Output from "alchemy/Output"; |
| 94 | import * as Effect from "effect/Effect"; |
| 95 | import Summarize from "./Summarize.ts"; |
| 96 | |
| 97 | export const Nightly = Effect.gen(function* () { |
| 98 | const job = yield* Summarize; |
| 99 | |
| 100 | const runner = yield* GCP.IAM.Member("NightlyRunner", { |
| 101 | kind: "run.job", |
| 102 | name: job.name, |
| 103 | role: "roles/run.invoker", |
| 104 | member: Output.interpolate`serviceAccount:${job.serviceAccount}`, |
| 105 | }); |
| 106 | |
| 107 | return yield* GCP.CloudScheduler.Job("Nightly", { |
| 108 | schedule: "0 2 * * *", |
| 109 | timeZone: "Etc/UTC", |
| 110 | httpTarget: { |
| 111 | uri: Output.interpolate`https://run.googleapis.com/v2/${job.name}:run`, |
| 112 | httpMethod: "POST", |
| 113 | body: "{}", |
| 114 | oauthToken: { |
| 115 | serviceAccountEmail: Output.map(runner.member, (member) => |
| 116 | member.replace(/^serviceAccount:/, ""), |
| 117 | ), |
| 118 | scope: "https://www.googleapis.com/auth/cloud-platform", |
| 119 | }, |
| 120 | }, |
| 121 | }); |
| 122 | }); |
| 123 | ``` |
| 124 | |
| 125 | Reading `runner.member` makes the scheduler wait for the grant. |
| 126 | Yield `Nightly` from your Stack. |
| 127 | |
| 128 | ## Read the execution name |
| 129 | |
| 130 | Cloud Run sets `CLOUD_RUN_EXECUTION` in the job's environment. Log it |
| 131 | to find a run in the console: |
| 132 | |
| 133 | ```typescript |
| 134 | const execution = yield* Effect.sync(() => process.env.CLOUD_RUN_EXECUTION); |
| 135 | ``` |
| 136 | |
| 137 | ## Example |
| 138 | |
| 139 | [`examples/gcp-scheduled-job`](https://github.com/alchemy-run/alchemy/tree/main/examples/gcp-scheduled-job) |
| 140 | rolls BigQuery orders into a daily JSON summary in Cloud Storage, |
| 141 | nightly and on demand. |
| 142 | |
| 143 | ## Where next |
| 144 | |
| 145 | - [Pub/Sub](/gcp/messaging/pubsub) — a job that drains a subscription |
| 146 | into BigQuery. |
| 147 | - [Cloud Scheduler](/gcp/messaging/scheduler) — schedules that call a |
| 148 | service. |
| 149 | - [Run reference](/providers/gcp/run#job) — every prop and attribute. |