ansible-runner/README.md

ansible-runner

Centralized Ansible runner repository for the homelab. Contains the inventory, vault configuration, SSH credentials, and two reusable Gitea Actions workflows: one that builds the custom runner image, and one that executes Ansible playbooks from any role repository.

---

Repository Structure

ansible-runner/
├── docker/
│   └── Dockerfile                          # Custom ansible-act-runner image
├── inventory/
│   └── raspberries.yaml                    # Ansible inventory
├── .gitea/
│   └── workflows/
│       ├── build-image.yaml                # Builds and pushes the runner image
│       └── ansible-runner.yaml             # Reusable workflow for all role repos
└── example-caller-workflow.yaml            # Example: how to call from another repo

---

Workflows

build-image.yaml — Build the Ansible Act Runner Image

Triggers automatically when docker/Dockerfile changes on main, or manually via workflow_dispatch with an optional force-rebuild flag.

Runs on the docker label (directly on the runner host) to access the DinD sidecar that is configured in the OKD runner pod. Builds and pushes two tags:

• gitea.mod.home/ansible/ansible-act-runner:latest
• gitea.mod.home/ansible/ansible-act-runner:<short-sha>

ansible-runner.yaml — Reusable Ansible Playbook Runner

A workflow_call workflow that can be called from any role repository. Runs on the ansible label using the custom image, which has Node.js, Python, Ansible, and all required collections pre-installed.

Inputs:

Input	Required	Default	Description
role_repo	✅	—	Gitea repo of the role, e.g. ansible/role-samba
playbook_path	✅	—	Path to playbook inside the role repo
inventory	❌	inventory/raspberries.yaml	Inventory file relative to this repo
ansible_extra_args	❌	''	Additional Ansible CLI arguments

Secrets passed through:

Secret	Description
TOKEN	Gitea access token for checking out private repos

---

Calling from a Role Repository

Place a workflow file in .gitea/workflows/ of your role repository:

name: 🚀 Deploy

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  deploy:
    uses: ansible/ansible-runner/.gitea/workflows/ansible-runner.yaml@main
    with:
      role_repo: ansible/role-samba
      playbook_path: playbooks/deploy.yml
      ansible_extra_args: '--tags install'   # optional
    secrets:
      TOKEN: ${{ secrets.TOKEN }}

---

Required Secrets

All secrets are configured at the Organization level in Gitea (ansible org → Settings → Secrets) so they are available to all role repositories without duplication.

Secret	Used in	Description
SSHKEY_B64	ansible-runner.yaml	Base64-encoded ED25519 private key for SSH access to managed hosts
ANSIBLE_VAULT_KEY	ansible-runner.yaml	Ansible Vault password
TOKEN	ansible-runner.yaml	Gitea access token (repo scope) for checking out role repos
REGISTRY_USER	build-image.yaml	Gitea username for container registry login
REGISTRY_PASSWORD	build-image.yaml	Gitea access token with package:write scope
TELEGRAM_BOT_TOKEN	both	Telegram bot token for notifications
TELEGRAM_CHAT_ID	both	Telegram chat ID for notifications

Creating the Gitea Access Token

In Gitea → User Settings → Applications → Generate Token:

• For TOKEN: scopes repo (read/write)
• For GITEA_REGISTRY_PASSWORD: scope package (read/write)

---

OKD Runner Configuration

The act runner pod in the OKD cluster (gitea-act-runner namespace) runs with a DinD sidecar. The build-image.yaml workflow uses runs-on: docker to execute directly on the runner host where DOCKER_HOST=tcp://localhost:2376 is available via the sidecar.

The ansible-runner.yaml workflow uses runs-on: ansible and spawns a container from the custom image. Node.js, Python, Ansible, and all collections are pre-installed — no runtime installation required.

Runner Labels (configured in OKD ConfigMap)

The runner ConfigMap (gitea-act-runner-config) must have the following labels registered. Without the docker label, build-image.yaml will not be picked up by the runner.

# configmap.yaml — labels section
runner:
  labels:
    - "docker:host"         # required for build-image.yaml (runs-on: docker)
    - "ansible:host"        # required for ansible-runner.yaml (runs-on: ansible)
    - "ubuntu-latest:docker://..."

Label	runs-on value	Purpose
docker:host	docker	Direct host execution with DinD sidecar — used for Docker builds
ansible:host	ansible	Direct host execution — Ansible jobs via container image
ubuntu-latest	ubuntu-latest	Container execution via DinD

Note: After changing the ConfigMap labels, the runner pod must re-register. Delete the pod to force a restart: kubectl delete pod -n gitea-act-runner -l app=gitea-act-runner

---

Bootstrap: First Image Build

No manual build from a laptop is required. The existing gitea/act_runner:latest pod already has a DinD sidecar and the docker:host label registered, so it can build and push the custom image itself.

Steps:

1. Create the repository in Gitea and push all files
2. Set the required secrets in the ansible org (see above)
3. Trigger the build manually via workflow_dispatch in Gitea Actions UI

The runner will build the image and push it to gitea.mod.home/ansible/ansible-act-runner:latest. All subsequent builds are triggered automatically when docker/Dockerfile changes on main.

---

Roadmap

• TLS for Gitea registry via cert-manager (remove insecure flag)
• Samba AD DC deployment playbook
• Bind9 DNS backend playbook
• Windows domain join playbook
• Fluentbit → VictoriaLogs for Samba log shipping