Slim B
8ab07b83ab
- Add v1.1.0 and v1.2.0 changelog entries - Add exclude field to config reference and example config - Add ADRs documenting all major design decisions - Fix step numbering in reverse_sync() - Fix action.yml to copy VERSION file - Add dist/ and .env to .gitignore - Use refs/tags/ format for Nix flake tag refs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
# Configuration Reference
|
|
|
|
Full reference for `.josh-sync.yml` fields and environment variables.
|
|
|
|
## `.josh-sync.yml` Structure
|
|
|
|
```yaml
|
|
josh: # josh-proxy settings (required)
|
|
targets: # sync targets (required, at least 1)
|
|
bot: # bot identity for sync commits (required)
|
|
```
|
|
|
|
## `josh` Section
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `proxy_url` | string | Yes | Josh-proxy URL, no trailing slash. Must start with `http://` or `https://`. |
|
|
| `monorepo_path` | string | Yes | Repository path as josh-proxy sees it (e.g., `org/monorepo`). |
|
|
|
|
## `targets[]` Section
|
|
|
|
Each target maps a monorepo subfolder to an external subrepo.
|
|
|
|
| Field | Type | Required | Default | Description |
|
|
|-------|------|----------|---------|-------------|
|
|
| `name` | string | Yes | — | Unique target identifier. Used in CLI commands and state tracking. |
|
|
| `subfolder` | string | Yes | — | Monorepo subfolder path (e.g., `services/billing`). |
|
|
| `josh_filter` | string | No | `:/<subfolder>` | Josh filter expression. Auto-derived from `subfolder` if omitted. Must start with `:`. |
|
|
| `subrepo_url` | string | Yes | — | External subrepo Git URL. Supports HTTPS (`https://...`), SSH (`git@host:path`), and `ssh://` formats. |
|
|
| `subrepo_auth` | string | No | `"https"` | Auth method: `"https"` or `"ssh"`. |
|
|
| `subrepo_token_var` | string | No | `"SUBREPO_TOKEN"` | Name of the env var holding the HTTPS token for this target. |
|
|
| `subrepo_ssh_key_var` | string | No | `"SUBREPO_SSH_KEY"` | Name of the env var holding the SSH private key for this target. |
|
|
| `branches` | object | Yes | — | Branch mapping: `mono_branch: subrepo_branch`. Each key-value pair syncs those branches bidirectionally. |
|
|
| `forward_only` | string[] | No | `[]` | Branches that only sync mono → subrepo, never reverse. |
|
|
| `exclude` | string[] | No | `[]` | File/directory patterns to exclude from sync via josh `:exclude` filter. Excluded files exist only in the monorepo, never in the subrepo. See [Excluding Files](guide.md#excluding-files-from-sync). |
|
|
|
|
## `bot` Section
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `name` | string | Yes | Git author name for sync commits. |
|
|
| `email` | string | Yes | Git author email for sync commits. |
|
|
| `trailer` | string | Yes | Git trailer key for loop prevention (e.g., `Josh-Sync-Origin`). |
|
|
|
|
## Environment Variables
|
|
|
|
### Credentials
|
|
|
|
| Variable | Purpose | Default |
|
|
|----------|---------|---------|
|
|
| `SYNC_BOT_USER` | Bot's Git username | — |
|
|
| `SYNC_BOT_TOKEN` | API token for monorepo access and josh-proxy HTTPS auth | — |
|
|
| `SUBREPO_TOKEN` | HTTPS token for subrepo access | Falls back to `SYNC_BOT_TOKEN` |
|
|
| `SUBREPO_SSH_KEY` | SSH private key content (not a file path) for subrepo access | — |
|
|
|
|
### Per-target credential overrides
|
|
|
|
Set `subrepo_token_var` or `subrepo_ssh_key_var` in a target's config to read credentials from a different env var:
|
|
|
|
```yaml
|
|
targets:
|
|
- name: "auth"
|
|
subrepo_token_var: "AUTH_REPO_TOKEN" # reads from $AUTH_REPO_TOKEN
|
|
subrepo_ssh_key_var: "AUTH_SSH_KEY" # reads from $AUTH_SSH_KEY
|
|
```
|
|
|
|
**Resolution order:** per-target env var → default env var (`SUBREPO_TOKEN` / `SUBREPO_SSH_KEY`) → `SYNC_BOT_TOKEN` fallback.
|
|
|
|
### Runtime
|
|
|
|
| Variable | Purpose | Default |
|
|
|----------|---------|---------|
|
|
| `JOSH_SYNC_TARGET` | Restrict sync to a single target | All targets |
|
|
| `JOSH_SYNC_STATE_BRANCH` | Name of the orphan branch for state storage | `josh-sync-state` |
|
|
| `JOSH_SYNC_DEBUG` | Enable verbose logging (`1` to enable) | `0` |
|
|
| `MONOREPO_API` | Override monorepo API URL | Auto-derived from first target's host |
|
|
|
|
## JSON Schema
|
|
|
|
The config file can be validated against the JSON Schema at [`schema/config-schema.json`](../schema/config-schema.json).
|