This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Specifications

1 - Infra forgejo runner

1.1 - Forgejo runner infrastructure specification

Describe the Forgejo Actions runner VM and deployment scaffold owned by infra/forgejo_runner. Its tf_setup and ansible packages are stages of this owner. The runner role is commented out in the baseline playbook; the checked-in configuration therefore does not establish a deployed or registered Actions worker. No live runner state was observed.

Baseline revision: 550d7e79b1f5fdbc2b6017b75178471d6914082f. Observed: 2026-09-08. Sources: owner README, BUILD, and the implementation links below.

Setup SHALL declare runner1 as Proxmox VM 1200 in the src_infra_forgejo_runner pool, with eight cores, 16 GiB memory, a 20 GiB boot disk, and a 300 GiB runner disk on ceph-ec storage. Its hostname and address SHALL derive from the owner’s DNS declaration.

Source: VM definition.

  • WHEN a maintainer evaluates the runner VM configuration
  • THEN the source declares the dedicated runner pool, compute allocation, and separate boot and runner disks
  • AND DNS source supplies the hostname and address

The baseline deployment playbook SHALL apply the shared host role to the forgejo_runner inventory group. The specification MUST identify the commented-out Forgejo runner role as inactive and MUST NOT interpret the available runner variables as evidence that the worker is installed or registered.

Sources: deployment playbook and runner variables.

  • WHEN the current playbook’s active roles are inspected
  • THEN only the shared host role is enabled
  • AND runner installation and registration remain outside the behavior established by this source baseline

The owner SHALL expose Terraform setup and packaged Ansible entry points through its al configuration and Vault injection dependencies. The runner configuration SHALL reference https://git.alwaldend.com, /dev/sdb, and an environment-supplied FORGEJO_RUNNER_TOKEN rather than a checked-in registration token.

Sources: setup BUILD, Ansible BUILD, and runner variables.

  • WHEN a maintainer inspects the runner configuration scaffold
  • THEN its token value is an environment lookup and its instance URL is the canonical Forgejo service
  • AND the token reference alone does not enable the inactive runner role

2 - Owned dns

2.1 - owned-dns Specification

Define Forgejo Actions runner DNS management through the owner’s tf_setup root, including canonical declarations, scoped execution, adoption of existing records, and offline source checks.

The tf_setup root SHALL consume this owner’s canonical dnsconfig.json through the shared DNS Terraform module, preserving declared record identities and views. DNS resources SHALL default to disabled before adoption and SHALL remain enabled by default after authorized adoption. Adoption SHALL bind existing provider records to the owner’s state without adding, changing, replacing, or deleting DNS records. Subsequent reconciliation of unchanged declarations SHALL preserve owned and unrelated records.

  • WHEN the checked-in root is evaluated with default inputs before adoption
  • THEN it reads this owner’s declaration and disables managed DNS records
  • AND the package contains the module and declaration inputs
  • WHEN the adopted root is evaluated with default inputs
  • THEN it reads this owner’s declaration and enables managed DNS records
  • AND the package contains the module and declaration inputs
  • WHEN the owner adopts matched existing provider records through //infra/forgejo_runner/tf_setup:dns.plan, :dns.show, and :dns.apply
  • THEN the owner state binds each declared record to its existing provider identity
  • AND the reviewed adoption plan proposes no record additions, changes, replacements, or deletions
  • WHEN the adopted root plans and applies unchanged declarations through its scoped //infra/forgejo_runner/tf_setup:dns wrappers
  • THEN it makes no DNS resource changes
  • AND owned records retain their declared values and views while unrelated records remain unchanged

The DNS wrapper SHALL select src_infra_forgejo_runner through the repository AL flow and keep secret values in injected variables. Dedicated DNS plan, show, and apply targets SHALL select dns=1 alone and target module.dns while reusing the owning setup root and backend. DNS apply SHALL consume only a reviewed saved plan. Ordinary setup targets SHALL retain their existing tf=setup flow. Real DNS credentials and Vault policy grants SHALL be prerequisites for operational Terraform calls. RouterOS DNS credentials SHALL be isolated from unrelated RouterOS resources. The package SHALL expose a format test that does not authenticate to Vault or contact DNS providers.

  • WHEN the package format test executes
  • THEN it checks the packaged Terraform configuration without live credentials
  • AND existing non-DNS authentication and backend paths remain unchanged
  • WHEN a dedicated DNS target selects its execution label
  • THEN it selects dns=1 and DNS credential injection through the owner AppRole
  • AND it retains the setup backend while limiting reconciliation to module.dns
  • AND disabled DNS resources do not imply offline provider configuration