nprasad2077/docs

mirror of https://gitea.com/gitea/docs.git synced 2026-11-04 09:15:33 +00:00

Files

T

silverwind be6aefc7e8 Simplify the runner docs and fix their outdated facts (#600 )

The runner pages had drifted from the runner. They claimed Podman is unsupported, a registration retry limit of 10, a `container.env` proxy override that has no effect, and they used the deprecated `generate-config` command, while the actual instructions were buried under implementation details.

The develop and 5.x pages are rewritten from the current runner sources (`main` is `v5.2.0`). They are shorter and aimed at operators, with a new page covering what jobs get. The reference generator now documents the `config` command, and the quickstart pages in every language use the `gitea-runner` binary name.

Reviewed-on: https://gitea.com/gitea/docs/pulls/600
Reviewed-by: Lunny Xiao <[email protected]>
Co-authored-by: silverwind <[email protected]>

2026-10-21 05:25:45 +00:00

4.5 KiB

Raw Blame History

sidebar_position

sidebar_position
1

Install from a binary

The runner is a single binary, gitea-runner, built for Linux, macOS, Windows, and FreeBSD.

Download

Download releases from dl.gitea.com/gitea-runner. Find builds from the main branch in its nightly directory. Each binary has a matching .sha256 checksum file:

VERSION=nightly
curl -sSLO "https://dl.gitea.com/gitea-runner/$VERSION/gitea-runner-$VERSION-linux-amd64"
curl -sSLO "https://dl.gitea.com/gitea-runner/$VERSION/gitea-runner-$VERSION-linux-amd64.sha256"
sha256sum -c "gitea-runner-$VERSION-linux-amd64.sha256"
sudo install -m 0755 "gitea-runner-$VERSION-linux-amd64" /usr/local/bin/gitea-runner

To build the runner yourself, run make build in a clone of gitea/runner.

First run

gitea-runner register --instance https://gitea.example.com --token <token>
gitea-runner daemon

register prompts for the remaining settings and writes the .runner registration file to the working directory. Run daemon from the same directory so it can read the file. See Registration.

systemd

Create a user and a configuration file. Then register the runner as that user from its home directory:

sudo useradd --system --home-dir /var/lib/gitea-runner --create-home gitea-runner
sudo mkdir -p /etc/gitea-runner
sudo gitea-runner config init -c /etc/gitea-runner/config.yaml
sudo chown gitea-runner /etc/gitea-runner/config.yaml
cd /var/lib/gitea-runner
sudo -u gitea-runner gitea-runner register -c /etc/gitea-runner/config.yaml \
  --instance https://gitea.example.com --token <token>

Install the unit as /etc/systemd/system/gitea-runner.service:

[Unit]
Description=Gitea Actions runner
Documentation=https://gitea.com/gitea/runner
After=network-online.target
Wants=network-online.target
# Uncomment when jobs use the local Docker daemon:
# After=docker.service
# Requires=docker.service

[Service]
Type=simple
ExecStart=/usr/local/bin/gitea-runner daemon --config /etc/gitea-runner/config.yaml
WorkingDirectory=/var/lib/gitea-runner
User=gitea-runner
Group=gitea-runner
Restart=on-failure
RestartSec=5s
TimeoutStopSec=3h

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now gitea-runner

Stopping the service cancels running jobs unless runner.shutdown_timeout gives them time to finish. Keep runner.shutdown_timeout below TimeoutStopSec:

sudo -u gitea-runner gitea-runner config set -c /etc/gitea-runner/config.yaml runner.shutdown_timeout 2h50m

For jobs in containers, give the gitea-runner user access to the Docker daemon's socket, for example through the docker group. That access is equivalent to root on the host. Set the runner's environment variables, such as proxy settings, with Environment= lines in the unit.

launchd (macOS)

Adjust the paths and user for your setup, then save this file as /Library/LaunchDaemons/com.gitea.runner.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.gitea.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/gitea-runner</string>
        <string>daemon</string>
        <string>--config</string>
        <string>/etc/gitea-runner/config.yaml</string>
    </array>
    <key>UserName</key>
    <string>_gitea-runner</string>
    <key>WorkingDirectory</key>
    <string>/var/lib/gitea-runner</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        <key>HOME</key>
        <string>/var/lib/gitea-runner</string>
    </dict>
    <key>StandardErrorPath</key>
    <string>/var/lib/gitea-runner/runner.log</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

sudo launchctl bootstrap system /Library/LaunchDaemons/com.gitea.runner.plist

Windows

Run gitea-runner daemon with a service wrapper such as WinSW. The runner has no service installer of its own.

On macOS and Windows, jobs usually run directly on the runner's machine with host labels.

4.5 KiB Raw Blame History