docs/workflows/Automation/Gitea/Publish Zensical Documentation with a Host Runner.md

---
tags:
  - Gitea
  - Zensical
  - GitOps
---

## Purpose
Install and register the host-based Gitea Actions runner that synchronizes this documentation repository into `/srv/zensical/docs`.  The Zensical account, watchdog service, and destination directory must already exist from the Zensical deployment.

## Install the Host Runner
Now is time for the arguably most-important stage of deployment, which is setting up a [Gitea Act Runner](https://docs.gitea.com/usage/actions/act-runner).  This is how document changes in a Gitea repository will propagate automatically into Zensical's `/srv/zensical/docs` folder.

```sh
# Install Dependencies
sudo apt install -y nodejs npm git rsync curl

# Create dedicated Gitea runner service account
sudo useradd --system --create-home --home /var/lib/gitea_runner --shell /usr/sbin/nologin gitearunner || true

# Allow the runner to write documentation changes
sudo usermod -aG zensical gitearunner

# Allow the runner to start and stop Zensical Watchdog Service
sudo tee /etc/sudoers.d/gitearunner-systemctl > /dev/null <<'EOF'
gitearunner ALL=NOPASSWD: /usr/bin/systemctl start zensical-watchdog.service, /usr/bin/systemctl stop zensical-watchdog.service
EOF
sudo chmod 440 /etc/sudoers.d/gitearunner-systemctl
sudo chown root:root /etc/sudoers.d/gitearunner-systemctl
sudo visudo -c

# Download Newest Gitea Runner Binary (https://gitea.com/gitea/act_runner/releases)
cd /tmp
wget https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-linux-amd64
sudo install -m 0755 act_runner-0.2.13-linux-amd64 /usr/local/bin/gitea_runner
gitea_runner --version

# Generate Gitea Runner Configuration
sudo mkdir -p /etc/gitea_runner
sudo chown gitearunner:gitearunner /etc/gitea_runner
sudo -u gitearunner gitea_runner generate-config > /etc/gitea_runner/config.yaml
```

### Configure Registration Token
- Navigate to: "**<Gitea Repo> > Settings > Actions > Runners**"
    - If you don't see this, it needs to be enabled.  Navigate to: "**<Gitea Repo> > Settings > "Enable Repository Actions: Enabled" > Update Settings**"
- Click the "**Create New Runner**" button on the top-right of the page and copy the registration token somewhere temporarily.
- Navigate back to the GuestVM running Zensical and run the following commands.

```sh
# Start Token Registration Process
sudo -u gitearunner env HOME=/var/lib/gitea_runner /usr/local/bin/gitea_runner register --config /etc/gitea_runner/config.yaml

# Gitea Instance URL: https://git.bunny-lab.io
# Gitea Runner Token: <Gitea-Runner-Token>
# Runner Name: zensical-docs-runner

# Move Runner Config to Correct Location & Configure Permissions
sudo mv /tmp/.runner /var/lib/gitea_runner/.runner
sudo chown gitearunner:gitearunner /var/lib/gitea_runner/.runner
sudo chmod 600 /var/lib/gitea_runner/.runner
```

### Create Service
Now we need to configure the Gitea runner to start automatically via a service just like the Zensical Watchdog service.

```sh
# Create Gitea Runner Service
sudo tee /etc/systemd/system/gitea-runner.service > /dev/null <<'EOF'
[Unit]
Description=Gitea Actions Runner (gitea_runner)
After=network-online.target
Wants=network-online.target

[Service]
Environment=HOME=/var/lib/gitea_runner
User=gitearunner
Group=gitearunner
WorkingDirectory=/var/lib/gitea_runner
ExecStart=/usr/local/bin/gitea_runner daemon --config /etc/gitea_runner/config.yaml
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target
EOF

# Remove Container-Based Configurations to Force Runner to Run in Host Mode
sudo sed -i \
  '/^[[:space:]]*labels:/,/^[[:space:]]*cache:/{
    /^[[:space:]]*labels:/c\  labels:\n    - "zensical-host:host"
    /^[[:space:]]*cache:/!d
  }' \
  /etc/gitea_runner/config.yaml

# Enable and Start the Service
sudo systemctl daemon-reload
sudo systemctl enable --now gitea-runner.service
```

### Repository Workflow
Place the following file into your documentation repository at the given location and this will enable the runner to execute when changes happen to the repository data.

```yaml title="gitea/workflows/automatic-deployment.yml"
name: Automatic Documentation Deployment

on:
  push:
    branches: [ main ]

jobs:
  zensical_deploy:
    name: Sync Docs to https://kb.bunny-lab.io
    runs-on: zensical-host

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

      - name: Stop Zensical Service
        run: sudo /usr/bin/systemctl stop zensical-watchdog.service

      - name: Sync repository into /srv/zensical/docs
        run: |
          rsync -rlD --delete \
            --exclude='.git/' \
            --exclude='.gitea/' \
            --exclude='assets/' \
            --exclude='schema/' \
            --exclude='stylesheets/' \
            --exclude='schema.json' \
            --chmod=D2775,F664 \
            . /srv/zensical/docs/

      - name: Start Zensical Service
        run: sudo /usr/bin/systemctl start zensical-watchdog.service

      - name: Notify via NTFY
        if: always()
        run: |
          curl -d "https://kb.bunny-lab.io - Zensical job status: ${{ job.status }}" https://ntfy.bunny-lab.io/gitea-runners

```

## Related Documentation
- [Zensical Deployment](<../../../deployments/automation/Documentation/Zensical.md>) — Prepare the service account, watchdog, and destination directory first.
- [Related Gitea Workflows](<../../../reference/Automation/Gitea Configuration Delivery.md>) — Find the connected deployments, procedures, and references for this subject.