Skip to content
gtcnsl
Docs Source
EN RU

Quickstart

From a freshly installed binary to a running Gitea with CI — three commands and a couple of checks.

Updated for v1.6.0

Before you start

You need gtcnsl on PATH (see Installation), a domain pointing at the box, and root. Everything else gtcnsl sets up for you.

Install Gitea

gtcnsl gitea install --yes

Pulls the verified Gitea binary from the official mirror, creates the git user, writes a default app.ini, deploys the systemd unit, and starts Gitea — auto-rolled-back if the health check fails. (--yes confirms the destructive, unattended operation.)

i
Set your domain
install writes a default app.ini. Point it at your host afterwards with gtcnsl config set server.DOMAIN git.example.com --yes — or apply a whole template (see Configuration).

Install the runner

gtcnsl runner install --executor=docker --yes

Installs the Gitea Actions Runner and its gitea-runner systemd unit with the chosen executor (--executor is required: host, docker, docker-rootless, podman, dind-rootless). The unit is deployed but stays stopped and not yet enabled — registering it starts the unit and enables it for boot, so no CI jobs run until you register.

Register the runner

gtcnsl runner register --instance https://git.example.com --token <fresh-token> --yes

Registers the runner with your instance and starts it. Get a token from Gitea → Site Admin → Runners → Create new runner (tokens are typically single-use). On the same run, gtcnsl also writes a baseline config.yaml for the runner (via the installed binary's own config generation subcommand) if one isn't already there — see Configuration.

i
Keep the token out of argv
--token <value> is visible to anyone on the host for the process's lifetime (ps, /proc/<pid>/cmdline). Pass --token-file <path> instead — mutually exclusive with --token — and gtcnsl reads it itself; on gitea-runner >= 2.1.0 the token never touches argv at all.

Check it worked

gtcnsl doctor

Reports PASS / WARN / FAIL across systemd, the binaries, app.ini, secrets, and both units (gitea, gitea-runner). Open https://git.example.com to finish the web setup.

!
DNS first
If the domain does not resolve to this host yet, registration will fail. Point DNS, then re-run the register step.

Next steps

Keep app.ini in Git and let gtcnsl config apply reconcile drift — see the Configuration guide for the template workflow, and Secrets for the four managed secrets.