# forgejo-hetzer-runner

Spawn a new Forgejo runner on Hetzner infrastructure.

**Requirements:**
* [`jq`](https://jqlang.github.io/jq)

**Required environment variables:**
* `HETZNER_API_TOKEN`: A Hetzner token valid for operating servers

## Usage

**To stand up a runner:**

```shell
./runner-up.sh -r <runner_token>
```

Avoid root login with password by passing your SSH key ID on server creation:

```shell
./runner-up.sh -s <ssh_key id> -r <runner_token>
```

**Delete the server(s):**
```shell
./runner-get.sh | jq '.servers[].id' | xargs -r -n1 ./runner-down.sh
```

**Log in:**
```shell
ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no "runner@$(./runner-get.sh | jq -j '.servers[0].public_net.ipv4.ip')"
```

## Fetching a registration token

The `FORGEJO_TOKEN` must be manually retrieved from the web interface. Note that each token is only valid for registering one runner.

* Retrieve a token to register a runner for your organization: `https://codeberg.org/org/${organization_name}/settings/runners`
* Retrieve a token to register a runner for one repository: `https://codeberg.org/${user_or_organization_name}/${repository_name}/settings/runners`

This issue tracks the addition of an API endpoint to fetch registration tokens in Forgejo: https://codeberg.org/forgejo/forgejo/issues/1030

## Additional notes

The server has to have an IPv4 interface. Otherwise:
* fetching `forgejo-runner` fails because `code.forgejo.org` is IPv4-only
* fetching default Docker base images fails because `docker.io` is IPv4-only
* your CI steps might involve communicating with an IPv4-only machine.

## External references

* [Hetzner cloud API reference](https://docs.hetzner.cloud/)