Skip to content

Commit 46224ae

Browse files
8bitAlex8bitAlex
committed
Enhance documentation for environments, profiles, and task types; add examples for new developer onboarding and custom commands
1 parent 171478e commit 46224ae

7 files changed

Lines changed: 757 additions & 147 deletions

File tree

‎docs/environments.md‎

Lines changed: 81 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -4,38 +4,80 @@ sidebar_position: 4
44

55
# Environments
66

7-
Environments let you define named configurations — sets of `.env` files and tasks — that can be applied across all repositories at once. Switching from local to staging to production is a single command.
7+
Environments let you define named configurations — sets of variables and tasks — that can be applied across all repositories at once. Switching from local to staging to production is a single command.
88

99
## Define environments
1010

11-
Environments are defined in the profile under each repository.
11+
Environments are defined at the **top level of the profile**, as a list. Each environment has a `name`, optional `variables`, and optional `tasks`.
12+
13+
```yaml title="profile.yaml"
14+
name: platform
15+
16+
environments:
17+
- name: local
18+
variables:
19+
- name: LOG_LEVEL
20+
value: debug
21+
tasks:
22+
- type: Shell
23+
cmd: docker-compose up -d db
24+
- name: staging
25+
variables:
26+
- name: LOG_LEVEL
27+
value: info
28+
tasks:
29+
- type: Print
30+
message: "Switched to staging"
31+
- name: production
32+
variables:
33+
- name: LOG_LEVEL
34+
value: warn
35+
tasks:
36+
- type: Confirm
37+
message: "Switch to production?"
1238

13-
```yaml
1439
repositories:
1540
- name: api
1641
url: git@github.com:my-org/api.git
1742
path: ~/dev/api
18-
environments:
19-
local:
20-
envFile: ./envs/local.env
21-
tasks:
22-
- type: shell
23-
cmd: docker-compose up -d
24-
staging:
25-
envFile: ./envs/staging.env
26-
tasks:
27-
- type: shell
28-
cmd: echo "Pointed at staging"
29-
production:
30-
envFile: ./envs/production.env
31-
tasks:
32-
- type: confirm
33-
message: "You are switching to production. Continue?"
43+
```
44+
45+
Individual repositories can also define their own environments in their `raid.yaml`. These are merged with the profile-level environments when applied.
46+
47+
```yaml title="~/dev/api/raid.yaml"
48+
environments:
49+
- name: local
50+
variables:
51+
- name: DATABASE_URL
52+
value: postgres://localhost:5432/api_dev
53+
- name: API_PORT
54+
value: "3000"
55+
tasks:
56+
- type: Shell
57+
cmd: docker-compose up -d db
58+
- name: staging
59+
variables:
60+
- name: DATABASE_URL
61+
value: postgres://staging-db.internal:5432/api
62+
- name: API_PORT
63+
value: "443"
64+
- name: production
65+
variables:
66+
- name: DATABASE_URL
67+
value: postgres://prod-db.internal:5432/api
68+
- name: API_PORT
69+
value: "443"
70+
tasks:
71+
- type: Confirm
72+
message: "Point API at production database?"
73+
- type: Shell
74+
cmd: ./scripts/rotate-api-key.sh
3475
```
3576

3677
| Field | Description |
3778
|---|---|
38-
| `envFile` | Path to a `.env` file to write into the repository root |
79+
| `name` | Environment name used with `raid env <name>` |
80+
| `variables` | List of `{name, value}` pairs to set when the environment is activated |
3981
| `tasks` | Tasks to run when this environment is applied |
4082

4183
## Apply an environment
@@ -44,10 +86,6 @@ repositories:
4486
raid env staging
4587
```
4688

47-
This iterates over every repository in the active profile and for each one:
48-
1. Writes the `envFile` contents to `.env` in the repository root
49-
2. Runs the environment's `tasks`
50-
5189
## Check the active environment
5290

5391
```bash
@@ -62,30 +100,23 @@ raid env list
62100

63101
## Tips
64102

65-
**Keep `envFile` paths relative to the profile file.** This makes the profile portable across machines.
66-
67-
**Use `confirm` tasks for production.** A confirmation gate before switching to a production environment prevents accidents.
68-
69-
```yaml
70-
production:
71-
envFile: ./envs/production.env
72-
tasks:
73-
- type: confirm
74-
message: "Switch ALL repos to production?"
75-
- type: shell
76-
cmd: ./scripts/rotate-creds.sh
77-
```
78-
79-
**Use `set` and `template` tasks for dynamic values.** If environment values differ per developer (e.g. local ports), generate them from a template rather than committing the final `.env`.
80-
81-
```yaml
82-
local:
83-
tasks:
84-
- type: prompt
85-
message: "Local API port"
86-
var: API_PORT
87-
default: "3000"
88-
- type: template
89-
src: ./envs/local.env.tmpl
90-
dest: ~/dev/api/.env
103+
**Use `Confirm` tasks for production.** A confirmation gate before switching to a production environment prevents accidents.
104+
105+
**Use `Prompt` and `Template` for developer-specific values.** If values differ per developer (e.g. local ports), prompt for them at apply-time.
106+
107+
```yaml title="~/dev/api/raid.yaml"
108+
environments:
109+
- name: local
110+
tasks:
111+
- type: Prompt
112+
var: DB_PORT
113+
message: "Local database port"
114+
default: "5432"
115+
- type: Prompt
116+
var: API_PORT
117+
message: "Local API port"
118+
default: "3000"
119+
- type: Template
120+
src: ./envs/local.env.tmpl
121+
dest: ~/dev/api/.env
91122
```

‎docs/examples/_category_.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Examples",
3+
"position": 6,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Real-world examples showing raid profiles, repo configs, and the commands to run them."
7+
}
8+
}

‎docs/examples/custom-commands.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Custom Commands
6+
7+
Raid commands let you encode multi-step workflows — deploys, migrations, test runs — as named commands that every developer gets automatically. This example shows several patterns: simple scripts, variable passing between tasks, conditional steps, and parallel execution.
8+
9+
## Simple command
10+
11+
A command that runs a deploy script with a confirmation gate:
12+
13+
```yaml title="profile.yaml"
14+
commands:
15+
- name: deploy
16+
usage: Deploy the API to staging
17+
tasks:
18+
- type: Confirm
19+
message: "Deploy API to staging?"
20+
- type: Shell
21+
cmd: ./scripts/deploy.sh staging
22+
path: ~/dev/api
23+
- type: Print
24+
message: "Deployed."
25+
color: green
26+
```
27+
28+
```bash
29+
raid deploy
30+
```
31+
32+
---
33+
34+
## Passing variables between tasks
35+
36+
Use `Set` to define a variable, then reference it in later tasks. Use `Shell` exports to capture dynamic values like git SHAs or generated tokens.
37+
38+
```yaml
39+
commands:
40+
- name: release
41+
usage: Tag and push a release
42+
tasks:
43+
- type: Prompt
44+
var: VERSION
45+
message: "Release version (e.g. 1.4.0)"
46+
- type: Shell
47+
cmd: |
48+
git tag v$VERSION
49+
git push origin v$VERSION
50+
path: ~/dev/api
51+
- type: Shell
52+
cmd: |
53+
export COMMIT=$(git rev-parse --short HEAD)
54+
path: ~/dev/api
55+
- type: Print
56+
message: "Released v$VERSION at $COMMIT"
57+
```
58+
59+
```bash
60+
raid release
61+
# > Release version (e.g. 1.4.0): 1.4.0
62+
# > Released v1.4.0 at 3fa9c12
63+
```
64+
65+
---
66+
67+
## Conditional tasks
68+
69+
Run tasks only on certain platforms or when a file or command exists:
70+
71+
```yaml
72+
commands:
73+
- name: setup-dev
74+
usage: First-time developer setup
75+
tasks:
76+
- type: Shell
77+
cmd: brew install postgresql
78+
condition:
79+
platform: darwin
80+
cmd: "! which psql"
81+
- type: Shell
82+
cmd: sudo apt-get install -y postgresql
83+
condition:
84+
platform: linux
85+
cmd: "! which psql"
86+
- type: Shell
87+
cmd: createdb api_dev
88+
condition:
89+
cmd: "! psql -lqt | grep api_dev"
90+
- type: Print
91+
message: "Dev database ready"
92+
```
93+
94+
---
95+
96+
## Parallel tasks
97+
98+
Mark adjacent tasks `concurrent: true` to run them in parallel. Raid waits for all concurrent tasks to finish before moving to the next step.
99+
100+
```yaml
101+
commands:
102+
- name: test-all
103+
usage: Run tests across all services in parallel
104+
tasks:
105+
- type: Print
106+
message: "Running tests..."
107+
- type: Shell
108+
cmd: go test ./...
109+
path: ~/dev/api
110+
concurrent: true
111+
- type: Shell
112+
cmd: npm test
113+
path: ~/dev/frontend
114+
concurrent: true
115+
- type: Shell
116+
cmd: pytest
117+
path: ~/dev/data-service
118+
concurrent: true
119+
- type: Print
120+
message: "All tests passed"
121+
color: green
122+
```
123+
124+
```bash
125+
raid test-all
126+
# Running tests...
127+
# [api, frontend, data-service running in parallel]
128+
# All tests passed
129+
```
130+
131+
---
132+
133+
## Reusable task groups
134+
135+
Extract repeated sequences into a named group and reference them from multiple commands:
136+
137+
```yaml
138+
task_groups:
139+
pull-all:
140+
- type: Shell
141+
cmd: git pull
142+
path: ~/dev/api
143+
concurrent: true
144+
- type: Shell
145+
cmd: git pull
146+
path: ~/dev/frontend
147+
concurrent: true
148+
149+
commands:
150+
- name: sync
151+
usage: Pull all repos and reinstall dependencies
152+
tasks:
153+
- type: Group
154+
ref: pull-all
155+
- type: Shell
156+
cmd: npm install
157+
path: ~/dev/frontend
158+
159+
- name: deploy
160+
usage: Pull latest and deploy
161+
tasks:
162+
- type: Group
163+
ref: pull-all
164+
- type: Shell
165+
cmd: ./scripts/deploy.sh
166+
```
167+
168+
---
169+
170+
## Per-repo commands
171+
172+
Commands can also live in individual repository `raid.yaml` files, scoped to that service. They are automatically available when the profile is loaded.
173+
174+
```yaml title="~/dev/api/raid.yaml"
175+
commands:
176+
- name: migrate
177+
usage: Run pending database migrations
178+
tasks:
179+
- type: Set
180+
var: ENV
181+
value: local
182+
- type: Confirm
183+
message: "Run migrations against $ENV?"
184+
- type: Shell
185+
cmd: go run ./cmd/migrate --env=$ENV
186+
187+
- name: seed
188+
usage: Seed the database with test data
189+
tasks:
190+
- type: Shell
191+
cmd: go run ./cmd/seed
192+
condition:
193+
cmd: "psql $DATABASE_URL -c '\\dt' | grep -q users"
194+
```
195+
196+
```bash
197+
raid migrate
198+
# > Run migrations against local? (y/N) y
199+
200+
raid seed
201+
```

0 commit comments

Comments
 (0)