@samebase/alchemy-kit 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +108 -39
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,55 +1,68 @@
|
|
|
1
1
|
# @samebase/alchemy-kit
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@samebase/alchemy-kit)
|
|
4
|
+
[](https://github.com/samebase/samebase/blob/main/packages/alchemy-kit/LICENSE)
|
|
5
|
+
|
|
6
|
+
Parts for [Alchemy v2](https://alchemy.run). Each part is its own entry, so your stack loads only
|
|
7
|
+
the part that it imports.
|
|
8
|
+
|
|
9
|
+
| Part | Entry | What it is |
|
|
10
|
+
| ----------------------------------------- | ------------------------------------ | -------------------------------------------------------------------------- |
|
|
11
|
+
| [GitHub state store](#github-state-store) | `@samebase/alchemy-kit/github-state` | The state of a stack on a branch of its GitHub repository, secrets sealed. |
|
|
12
|
+
|
|
13
|
+
> The source is in
|
|
14
|
+
> [`packages/alchemy-kit`](https://github.com/samebase/samebase/tree/main/packages/alchemy-kit) of
|
|
15
|
+
> the Samebase monorepo. Use [GitHub Issues](https://github.com/samebase/samebase/issues) to report
|
|
16
|
+
> a problem or request a change.
|
|
5
17
|
|
|
6
18
|
## GitHub state store
|
|
7
19
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
20
|
+
<picture>
|
|
21
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/samebase/samebase/main/packages/alchemy-kit/docs/github-state-dark.svg">
|
|
22
|
+
<img src="https://raw.githubusercontent.com/samebase/samebase/main/packages/alchemy-kit/docs/github-state-light.svg" alt="A deploy, on your laptop or in GitHub Actions, holds the key ALCHEMY_GITHUB_STATE_KEY and seals each secret before it leaves the run. In your GitHub repository, the deploy takes the lock on the branch alchemy-state-store-lock, then reads and commits the state on the branch alchemy-state-store: one JSON file for each resource. The branch main holds your code and alchemy.run.ts." width="100%">
|
|
23
|
+
</picture>
|
|
12
24
|
|
|
13
|
-
|
|
14
|
-
|
|
25
|
+
Alchemy keeps a record of each resource that it deployed. This store keeps that record on a branch
|
|
26
|
+
of the repository that the stack deploys from. The state needs no cloud account and no server: the
|
|
27
|
+
repository and its `GITHUB_TOKEN` are enough.
|
|
15
28
|
|
|
16
|
-
|
|
29
|
+
- **One JSON file for each resource.** You read the state on github.com, and each deploy is a commit
|
|
30
|
+
that names what it changed.
|
|
31
|
+
- **Sealed secrets.** Each secret is sealed with AES-256-GCM before it leaves the run. The key is a
|
|
32
|
+
repository secret.
|
|
33
|
+
- **One deploy of a stage at a time.** A second deploy of the same stage fails at once.
|
|
34
|
+
|
|
35
|
+
### Quick start
|
|
36
|
+
|
|
37
|
+
**1. Install.**
|
|
17
38
|
|
|
18
39
|
```sh
|
|
19
40
|
pnpm add -D @samebase/alchemy-kit alchemy@2.0.0-beta.85 effect
|
|
20
41
|
```
|
|
21
42
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
In `alchemy.run.ts`:
|
|
43
|
+
**2. Give the store to your stack**, in `alchemy.run.ts`:
|
|
25
44
|
|
|
26
45
|
```ts
|
|
27
46
|
import * as GitHubState from "@samebase/alchemy-kit/github-state";
|
|
28
|
-
|
|
29
|
-
|
|
47
|
+
import * as Alchemy from "alchemy";
|
|
48
|
+
|
|
49
|
+
export default Alchemy.Stack(
|
|
50
|
+
"my-app",
|
|
51
|
+
{
|
|
52
|
+
providers,
|
|
53
|
+
state: GitHubState.state(),
|
|
54
|
+
},
|
|
55
|
+
program,
|
|
56
|
+
);
|
|
30
57
|
```
|
|
31
58
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
- `repository`: `owner/name`. The default is `GITHUB_REPOSITORY`, else the `origin` remote.
|
|
35
|
-
- `branch`: the state branch. The default is `alchemy-state-store`.
|
|
36
|
-
- `key`: a `Redacted` key. The default is the environment variable `ALCHEMY_GITHUB_STATE_KEY`.
|
|
37
|
-
|
|
38
|
-
The token is `GITHUB_TOKEN` or `GH_TOKEN`. It needs write access to the contents of the repository.
|
|
39
|
-
|
|
40
|
-
### The key
|
|
41
|
-
|
|
42
|
-
Make the key once and keep it as the repository secret `ALCHEMY_GITHUB_STATE_KEY`:
|
|
59
|
+
**3. Make the key**, once, and keep it as a repository secret:
|
|
43
60
|
|
|
44
61
|
```sh
|
|
45
62
|
openssl rand -base64 32 | gh secret set ALCHEMY_GITHUB_STATE_KEY
|
|
46
63
|
```
|
|
47
64
|
|
|
48
|
-
|
|
49
|
-
at the first secret that does not open. If you lose the key, you cannot open the secrets on the
|
|
50
|
-
branch.
|
|
51
|
-
|
|
52
|
-
### GitHub Actions
|
|
65
|
+
**4. Deploy from GitHub Actions.** The job needs write access to the contents of the repository:
|
|
53
66
|
|
|
54
67
|
```yaml
|
|
55
68
|
permissions:
|
|
@@ -67,7 +80,45 @@ jobs:
|
|
|
67
80
|
ALCHEMY_GITHUB_STATE_KEY: ${{ secrets.ALCHEMY_GITHUB_STATE_KEY }}
|
|
68
81
|
```
|
|
69
82
|
|
|
70
|
-
|
|
83
|
+
The first deploy makes the two branches.
|
|
84
|
+
|
|
85
|
+
### Options
|
|
86
|
+
|
|
87
|
+
`GitHubState.state()` takes one object. Each field is optional.
|
|
88
|
+
|
|
89
|
+
| Option | Default | What it is |
|
|
90
|
+
| ------------ | --------------------------------------------------- | ------------------------------------------------------------ |
|
|
91
|
+
| `repository` | `GITHUB_REPOSITORY`, else the `origin` remote | The repository, as `owner/name`. |
|
|
92
|
+
| `branch` | `alchemy-state-store` | The state branch. The lock branch is this name with `-lock`. |
|
|
93
|
+
| `key` | The environment variable `ALCHEMY_GITHUB_STATE_KEY` | The key, as a `Redacted` string. |
|
|
94
|
+
|
|
95
|
+
The token is `GITHUB_TOKEN`, else `GH_TOKEN`.
|
|
96
|
+
|
|
97
|
+
### The key
|
|
98
|
+
|
|
99
|
+
The key is 32 random bytes in base64. Each deploy of the repository uses the same key.
|
|
100
|
+
|
|
101
|
+
- Without the key, the store stops before it reads or writes anything.
|
|
102
|
+
- With a different key, the store stops at the first secret that does not open.
|
|
103
|
+
- If you lose the key, you cannot open the secrets on the branch.
|
|
104
|
+
|
|
105
|
+
The sealing is the package's own until Alchemy releases state encryption
|
|
106
|
+
([alchemy-run/alchemy#3167](https://github.com/alchemy-run/alchemy/pull/3167)).
|
|
107
|
+
|
|
108
|
+
### From your laptop
|
|
109
|
+
|
|
110
|
+
The store reads the token and the key from the environment of the process. A `.env` file does not
|
|
111
|
+
set them. Keep the key in a file that git ignores, here `.state-key`.
|
|
112
|
+
|
|
113
|
+
```sh
|
|
114
|
+
export GITHUB_TOKEN="$(gh auth token)"
|
|
115
|
+
export ALCHEMY_GITHUB_STATE_KEY="$(cat .state-key)"
|
|
116
|
+
pnpm exec alchemy deploy --stage dev-me
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
For a `dev-` stage that only you use, Alchemy's local state is simpler.
|
|
120
|
+
|
|
121
|
+
### What is on the branches
|
|
71
122
|
|
|
72
123
|
```
|
|
73
124
|
alchemy-state-store the state
|
|
@@ -79,14 +130,32 @@ alchemy-state-store-lock the deploy lock of each stage
|
|
|
79
130
|
{stack}/{stage}/__lease__.json
|
|
80
131
|
```
|
|
81
132
|
|
|
82
|
-
Both are orphan branches
|
|
83
|
-
|
|
84
|
-
|
|
133
|
+
Both are orphan branches: they share no history with your code. A resource file is plain JSON,
|
|
134
|
+
except its secrets. This is `my-app/prod/ApiKey.json`, shortened:
|
|
135
|
+
|
|
136
|
+
```json
|
|
137
|
+
{
|
|
138
|
+
"status": "created",
|
|
139
|
+
"resourceType": "Alchemy.Random",
|
|
140
|
+
"props": { "bytes": 16 },
|
|
141
|
+
"attr": {
|
|
142
|
+
"text": {
|
|
143
|
+
"__redacted__": { "__sealed__": "v1.<iv>.<ciphertext>" }
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
A sealed value opens only in the file that it was sealed for. A copy in a different file does not
|
|
150
|
+
open.
|
|
151
|
+
|
|
152
|
+
### How a deploy writes
|
|
85
153
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
154
|
+
- The deploy takes the lock of its stage and renews it while it runs. If the deploy stops without a
|
|
155
|
+
release, the lock ends after 60 seconds.
|
|
156
|
+
- All the writes that are waiting go into one commit, with a message such as
|
|
157
|
+
`my-app prod: set Worker, Bucket`.
|
|
158
|
+
- When another deploy moved the branch first, the store reads the new head and tries again.
|
|
90
159
|
|
|
91
160
|
### Limits
|
|
92
161
|
|
|
@@ -99,4 +168,4 @@ lock.
|
|
|
99
168
|
- In a public repository, the state is public, except the sealed secrets.
|
|
100
169
|
- A ruleset that requires pull requests on all branches, or a tool that deletes stale branches,
|
|
101
170
|
breaks the store. Keep both branches out of such rules.
|
|
102
|
-
-
|
|
171
|
+
- There is no key rotation. A new key cannot open the secrets that the old key sealed.
|