docs/workflows/Automation/Gitea/Deliver Configuration with a Docker Runner.md

tags

tags
Gitea Docker GitOps

Purpose

Configure the Docker-based Gitea runner and repository workflow described in the May 2025 GitOps experiment. The example synchronizes repository files into a bind-mounted destination and sends an ntfy notification.

!!! info "Dated Docker Runner Example" This is the configuration from the May 2025 runner experiment. Its Docker execution model and destination mounts differ from the Zensical host-runner workflow.

Deploy the Docker Runner

When it comes to deploying a runner, (assuming you want to use a docker-based runner) it has a few simple things that need to be configured, the docker-compose.yml and the .env files. These tell the runner to reach out to Gitea server to register the runner with the given repository that you generated a registration token on.

version: "3.8"
services:
  app:
    image: docker.io/gitea/act_runner:latest
    environment:
      CONFIG_FILE: /config.yaml
      GITEA_INSTANCE_URL: "${INSTANCE_URL}"
      GITEA_RUNNER_REGISTRATION_TOKEN: "${REGISTRATION_TOKEN}"
      GITEA_RUNNER_NAME: "${RUNNER_NAME}"
      GITEA_RUNNER_LABELS: "${RUNNER_NAME}" # This can be anything, and is referenced by the workflow task(s) later.
    volumes:
      - /srv/containers/gitea-runner-mkdocs/config.yaml:/config.yaml # You have to manually make this file before you start the container
      - /srv/containers/material-mkdocs/docs/docs:/Gitops_Destination # This is where the repository data will be copied to

INSTANCE_URL=https://git.bunny-lab.io
RUNNER_NAME=gitea-runner-mkdocs
REGISTRATION_TOKEN=<Generated Here: https://git.bunny-lab.io/bunny-lab/docs/settings/actions/runners>

Creating the config.yaml

The oddball thing about the way that I configured the Gitea Act Runner was telling it to run the container in "host mode" which tells it to run the tasks / workflows directly on the container itself instead of spinning up an instanced container (referred to as "Docker-in-Docker"). This keeps things simpler, but requires us to add a line to the config.yaml located at /srv/containers/gitea-runner-mkdocs/config.yaml. You can use your preferred text editor to add the following to the file's contents. This tells the runner to use itself for the tasks instead of an instanced docker container.

container_engine: ""

!!! info "Quick Config Command"

```sh
mkdir -p /srv/containers/gitea-runner-mkdocs
echo 'container_engine: ""' > "/srv/containers/gitea-runner-mkdocs/config.yaml"
```

Runner Workflow Task Files

When it comes to telling the runner what to do and how to do it, you create what are called runner "Workflows". These files reside within <RepoRoot>/.gitea/workflows and are .yaml format. If you have any familiarity with Ansible, the similarities are staggaring. You can have multiple workflows for one repository, with different flows that fire-off on different runners. An example of the flow used to replace Git-Repo-Updater's functionality can be seen below.

In the workflow below, it spins up a runner within the Alpine Linux environment that the docker.io/gitea/act_runner:latest uses, then installs NodeJS, Git, and Rsync for the core functionality that mirrors Git-Repo-Updater:

name: GitOps Automatic Deployment

on:
  push:
    branches: [ main ]

jobs:
  GitOps Automatic Deployment:
    runs-on: gitea-runner-mkdocs

    steps:
      - name: Install Node.js, git, rsync, and curl
        run: |
          apk add --no-cache nodejs npm git rsync curl

      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Copy Repository Data to Production Server
        run: |
          rsync -a --delete --exclude='.git/' --exclude='.gitea/' . /Gitops_Destination/

      - name: Notify via NTFY
        run: |
          curl -d "https://docs.bunny-lab.io - Workflow Completed" https://ntfy.bunny-lab.io/gitea-runners

!!! note "runs-on Variable" In this example workflow file, we are targeting the previously-mentioned gitea-runner-mkdocs runner, which we gave that "label" in the docker-compose.yaml file's GITEA_RUNNER_LABELS variable. You can name these labels whatever you want, as a way of organizing which runners run which workflows associated with a repository when changes are made to the repository.

Related Documentation

• Related Gitea Workflows — Find the connected deployments, procedures, and references for this subject.