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

main
mdx 116 lines 3.86 KB
Raw
1 ---
2 title: Setup
3 description: Connect alchemy to GitHub — account, credentials, and profiles.
4 ---
5
6 import PackageManagers from "../../../components/PackageManagers.astro";
7
8 Install `@alchemy.run/github`:
9
10 <PackageManagers add="@alchemy.run/github" />
11
12 Then register the provider next to your cloud's:
13
14 ```typescript
15 // alchemy.run.ts
16 import * as GitHub from "@alchemy.run/github";
17
18 providers: Layer.mergeAll(Cloudflare.providers(), GitHub.providers()),
19 ```
20
21 Run `alchemy profile edit --add GitHub` and pick between two local options:
22
23 - **`gh` CLI** — shells out to `gh auth token` (recommended).
24 - **Stored PAT** — a personal access token entered interactively,
25 saved under `~/.alchemy/credentials/<profile>/`.
26
27 When `CI=true`, profiles are bypassed and Alchemy reads
28 `GITHUB_ACCESS_TOKEN` or `GITHUB_TOKEN` directly.
29
30 See [Profiles](/environments/profiles) for how credentials are stored
31 and switched.
32
33 ## GitHub Enterprise
34
35 Both profile methods and CI environment credentials work against GitHub Enterprise Server and GitHub
36 Enterprise Cloud with data residency. `alchemy profile edit
37 re-configure GitHub` prompts for the host. Leave it blank for github.com, or enter your
38 enterprise host (e.g. `github.example.com` or `acme.ghe.com`).
39
40 The host is normalized into the REST API base URL automatically:
41
42 - `github.example.com` → `https://github.example.com/api/v3` (GHES)
43 - `acme.ghe.com` → `https://api.acme.ghe.com` (data residency)
44 - an explicit URL like `https://github.example.com/api/v3` is used as-is
45
46 Alternatively, set the host in the environment — `GITHUB_BASE_URL`,
47 `GITHUB_API_URL` (set automatically on GitHub Actions runners), or
48 `GH_HOST` — and every method picks it up without reconfiguring. On an
49 enterprise host, CI environment resolution also honors the `gh`
50 CLI's `GH_ENTERPRISE_TOKEN` / `GITHUB_ENTERPRISE_TOKEN` before falling
51 back to `GITHUB_ACCESS_TOKEN` / `GITHUB_TOKEN`, and the `gh` CLI method
52 runs `gh auth token --hostname <host>` (run
53 `gh auth login --hostname <host>` once first).
54
55 ### Pin the host in code
56
57 To fix the host for the whole app — independent of profile
58 configuration or the environment — pass it to `providers()`:
59
60 ```typescript
61 providers: GitHub.providers({ baseUrl: "github.example.com" }),
62 ```
63
64 The auth provider sees the pinned host too: the configure flow stops
65 prompting for it and authenticates against it directly.
66
67 ### Per-resource host override
68
69 Every GitHub resource also takes its own `baseUrl` prop, so a single
70 stack can span github.com and an enterprise instance:
71
72 ```typescript
73 yield* GitHub.Repository("mirror", {
74 owner: "my-org",
75 name: "mirror",
76 baseUrl: "github.example.com",
77 });
78 ```
79
80 Resolution order is: resource `baseUrl` → `providers({ baseUrl })` →
81 the host from the login profile or environment. Changing a resource's
82 `baseUrl` replaces it — the same name on a different GitHub instance
83 is a different physical resource.
84
85 ## Token scopes
86
87 - `repo` — always required.
88 - `workflow` — when you manage [Actions secrets and variables](/github/actions-config).
89 - `delete_repo` — only when you opt a [repository](/github/repository)
90 into deletion via `destroy()`. Repositories default to retain on
91 removal, so most tokens never need it.
92
93 ## Programmatic credentials
94
95 Skip profiles entirely by building the credentials layer from a token
96 you already have in hand — useful in tests:
97
98 ```typescript
99 Effect.provide(GitHub.fromToken(token))
100 ```
101
102 `fromToken` accepts a plain string or a `Redacted` value, plus an
103 optional `baseUrl` for GitHub Enterprise:
104
105 ```typescript
106 Effect.provide(GitHub.fromToken(token, { baseUrl: "github.example.com" }))
107 ```
108
109 To read from the environment instead, `GitHub.fromEnv()` builds the
110 same layer from `GITHUB_ACCESS_TOKEN` or `GITHUB_TOKEN` (and resolves
111 the enterprise host from `GITHUB_BASE_URL` / `GITHUB_API_URL` /
112 `GH_HOST` when set).
113
114 ## Next steps
115
116 - [GitHub overview](/github) — resources and compositions.