# Connect — Environment Variables and Flags

Configuration consumed by the `.scripts/argo-cd/` connect operations
(`references/connecting-a-repo.md`). These are **tooling inputs**: they configure the machine
running the connect, and must never reach the deployed `cluster/**` manifests.

---

## 1. Layered loading

The base module loads three files in order, each overriding the previous:

```text
.env  ->  .env-<environment>  ->  .env-<environment>-credentials
```

- `.env` holds **only** the environment selector.
- Connection configuration lives in the environment layer (`.env-test`).
- With SSH auth there is no inline secret — the private key is a **file referenced by path**,
  so the credentials layer stays empty unless a future component needs it.
- Every layer has a tracked sample: `.sample.env`, `.sample.env-<env>`,
  `.sample.env-<env>-credentials`. Adding a variable without adding it to the sample is how
  the next operator gets a missing-variable failure on a fresh clone.

Variable names narrow scope left to right: `<PREFIX> -> <domain> -> <sub> -> <leaf>`. The
gondor family uses the `HL_V1_` prefix; the names below are shown with it.

## 2. Variables

| Variable | Layer | Required | Purpose |
|---|---|---|---|
| `HL_V1_ENVIRONMENT` | `.env` | yes | Selects which `.env-<env>` files load (e.g. `test`). |
| `HL_V1_KUBE_CONFIG_PATH` | `.env-<env>` | yes | Path to the kubeconfig file. Supports `${HOME}`. |
| `HL_V1_KUBE_CONFIG_CONTEXT` | `.env-<env>` | yes | Context inside that kubeconfig to target. |
| `HL_V1_ARGOCD_NAMESPACE` | `.env-<env>` | yes | Namespace ArgoCD runs in (e.g. `argocd`). |
| `HL_V1_ARGOCD_TARGET_DIR` | `.env-<env>` | yes | Local path to the rendered repo holding the bootstrap manifests. |
| `HL_V1_ARGOCD_GIT_REPO_URL` | `.env-<env>` | yes | Repo ArgoCD pulls from — **SSH form** `git@host:owner/repo.git`. |
| `HL_V1_ARGOCD_PROJECT` | `.env-<env>` | no | AppProject name → project-scoped repo. Empty = global. |
| `HL_V1_ARGOCD_REPOSITORY_SECRET` | `.env-<env>` | when a Secret is created | Name of the ArgoCD repository Secret. |
| `HL_V1_ARGOCD_GIT_REPO_SSH_KEY_PATH` | `.env-<env>` | private repo | Path to the **private** SSH key. Empty = public repo. |
| `HL_V1_ARGOCD_RBAC_DEFAULT_POLICY` | `.env-<env>` | no | `policy.default` for `argocd-rbac-cm`. Defaults to `role:readonly`. |

The five required variables are checked up front, so a missing one fails before any cluster
call rather than halfway through onboarding.

## 3. CLI flags

Parsed in `lib/--env-vars-reader.sh`; each overrides the corresponding environment value for
a single run:

```text
--kubeconfig      --kube-context      --namespace       --target-dir
--repo-url        --repo-ssh-key-path --repo-secret-name
```

Flags reach the script after `--`:

```bash
task argo-cd:0100-connect-one -- --repo-url="git@host:owner/repo.git"
```

## 4. SSH auth

The repo URL must be SSH form, and the **public** half of the key at
`HL_V1_ARGOCD_GIT_REPO_SSH_KEY_PATH` must be registered as a read-only **deploy key** on the
repository. The host key must also be trusted first — see `references/connecting-a-repo.md`
§2.

Never commit the private key. It stays a local file referenced by path; only the path travels
in configuration.