canasta gitops join

Join an existing gitops repository

Synopsis

Join an existing gitops repository for a Canasta instance.

Clones the repo, adds this host to the host inventory, extracts host-specific values into vars.yaml, and pushes the new host entry back to the repo. On Compose this also unlocks git-crypt so encrypted vars become readable; K8s repos are cleartext and need no unlock step.

The instance must already exist and have a working .env file. Use canasta gitops init to bootstrap a new gitops repository instead.

On Compose, each wiki's URL on this host is taken from the instance, so when the repository holds a wiki farm, the instance must already have every wiki in it. Add any it lacks with canasta add -w <id> -u <url> before joining; otherwise join stops before changing anything and names them.

Account-wide credentials (the AWS keys, SMTP) are shared across every host in the repo. Backup credentials are not: a password that unlocks one specific repository belongs with the per-host RESTIC_REPOSITORY it opens, so RESTIC_PASSWORD stays on the host that generated it. If the hosts in this repo all back up to one restic repository, set the joining host's password to match it — canasta config set -i <id> RESTIC_PASSWORD=<password> — or its backups will fail against a repository it cannot open.

canasta gitops join [flags]

Examples

canasta gitops join -n staging --repo git@github.com:org/config.git --key /tmp/gc.key

Flags

Flag	Shorthand	Description	Default	Required	Orchestrator
`--name`	`-n`	Name for this host		✓	Both
`--repo`		Git repository URL. On Kubernetes it must be an SSH URL (user@host:path or ssh://user@host/path), since Argo CD clones it over SSH from inside the cluster.		✓	Both
`--git-user-email`		Git user.email for commits on the target host (set if not already configured)			Both
`--git-user-name`		Git user.name for commits on the target host (set if not already configured)			Both
`--id`	`-i`	Canasta instance ID	*		Both
`--key`		A path on the controller (the machine running canasta). Compose: the git-crypt symmetric key file exported by `canasta gitops init`. It unlocks any git-crypt repo; it may be omitted for a repo with GPG recipients, which is then unlocked through a forwarded GPG agent. Kubernetes: required, the basename of the SSH deploy key (<key>.ssh).			Both
`--reinit`		Wipe local gitops state before joining. Use after a previous init or join died mid-run and left this instance unable to retry. Also re-attaches a host that is already registered in the repo (the registration is updated in place rather than rejected as a duplicate).			Both
`--ssh-key`		Path on the instance's host to an SSH private key for git network operations. When set, git runs with GIT_SSH_COMMAND="ssh -i <ssh-key> ...". On a remote host, give an absolute path or one starting with a quoted '~' (for example '~/x'). On Compose, the instance remembers the path, and later gitops commands use it when --ssh-key is omitted; passing it again replaces it. Without a remembered key, git uses ssh-agent forwarding on Compose, or the generated `<key>.ssh` deploy key on Kubernetes.			Both

* Defaults to the Canasta instance matching the current directory, if any.

Global flags

Flag	Shorthand	Description	Default	Required	Orchestrator
`--help`	`-h`	Show help message and exit			Both
`--verbose`	`-v`	Enable verbose output			Both