# 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).