# Proxmox Flatcar Gitea runner

`create-flatcar-gitea-runner.sh` creates a Flatcar VM using the Stable Proxmox
image and provisions it with Ignition through Proxmox `cicustom` user-data.
The VM uses 4 CPU cores, 16 GiB memory, and a 100 GiB disk by default. It
enables Docker and starts the Gitea Actions runner in a persistent container.

The script follows the Flatcar Proxmox flow: import the image, attach a
Cloud-Init drive, place Ignition JSON in the Proxmox snippets directory, and
set `qm set --cicustom user=...`. Flatcar uses the same `user-data` path for
Ignition and regular cloud-init, so do not combine this snippet with regular
cloud-init settings.

Before running it:

1. Enable the `snippets` content type on the Proxmox storage used by
   `SNIPPET_STORAGE`.
2. Obtain a repository, organization, or instance Gitea runner registration
   token.
3. Confirm the VM ID is unused and the bridge and storage names are correct.

Example:

```bash
chmod +x scripts/proxmox/create-flatcar-gitea-runner.sh

VM_ID=9100 \
GITEA_INSTANCE_URL=https://git.example.com \
GITEA_RUNNER_REGISTRATION_TOKEN='replace-with-token' \
SSH_PUBLIC_KEY="$(cat ~/.ssh/id_ed25519.pub)" \
scripts/proxmox/create-flatcar-gitea-runner.sh
```

The registration token is written to a root-only file inside the VM. It is
also present in the generated Proxmox snippet, so protect the snippet storage
and remove it after the VM is provisioned if recovery from the snippet is not
required.

The runner mounts the Docker socket because Gitea Actions uses Docker to
execute workflow jobs. A Docker socket is equivalent to broad host control,
so this VM should be dedicated to trusted CI workloads and should not host
unrelated services.

The image URL and optional SHA256 value can be overridden through environment
variables. The default URL tracks the Flatcar Stable current amd64 image. Pin
`FLATCAR_IMAGE_URL` and set `FLATCAR_IMAGE_SHA256` for a reproducible change
controlled deployment.