This article explains how to connect a runner to a build machine when the pipeline YAML is written and no one is running the jobs. After reading it, you can add a runner in the console (the program installed on a build machine that runs jobs for AngusGit), generate a registration token that lasts 1 hour, copy the Docker or Zip command onto the build machine and run it, and confirm that the heartbeat brings it online.
Pipelines and runners are available on Team and Enterprise. Community has no CI/CD menu, and the steps in this article do not apply there.
1. Prepare a build machine
Before you connect, check the network, the container environment, and the host environment. The Docker method starts a container on this machine for each job (a short-lived isolated environment started from an image). The Zip method runs the job directly on the host (the machine where the runner process lives). A job is one group of steps in a pipeline.
| Check | Which method | Requirement |
|---|---|---|
| Network | Every method | The build machine opens the connection to AngusGit (HTTPS / a WebSocket connection that stays open). AngusGit does not connect back to the build machine |
| Container environment | Docker method | Docker is installed. The current user can run docker and mount /var/run/docker.sock
|
| Host environment | Zip method | JDK 21, curl, and unzip are installed. The current user can sudo (the install path is /opt/AngusRunnerAgent) |
On the build machine, try curl -I https://<your AngusGit address>. An HTTP status code means the network path is open.
2. Add a runner in the console
- Open the connect page
In the sidebar, open CI/CD → Runners and click Add Runner at the upper right. The page switches to Connect a new Runner.
- Confirm the control plane URL
Control plane URL defaults to the site the browser has open. The hint is “Defaults to this site. Change it if runners cannot reach the current origin.” If you open AngusGit by a domain name on the office network, and the build machine in the server room can reach only an internal IP, change this field to the address the build machine can reach.
- Fill in the name and labels
Runner name (optional) should say which machine this is, for example build-linux-01. Labels (optional) are comma-separated, for example linux,docker. A job in a pipeline picks a runner by labels, so these labels have to match what the job writes. If you are not sure, leave them empty and use the default labels of the method you pick. Max concurrent jobs is how many jobs this machine runs at the same time. The default is 4, and the allowed range is 1 to 64. Choose it from the machine’s CPU and memory.
- Generate a registration token
Next to Registration token, click Generate token. The page says “Short-lived registration token issued (shown once)”, and below that “Token expires at {time}”. The token lasts 1 hour. It is filled into the commands below. If you click Copy command with no token, the message is “Generate or paste a token before copying commands”.
The picture below is the page before you click Generate token. The control plane URL is https://git.anguskit.com, the name is build-linux-01, the labels are linux,docker, and max concurrent jobs is 4. The yellow hint is “No token yet. Click Generate token for a short-lived rrt_, or paste the shared registration token from ops.” Copy command is disabled. The three tabs are Zip install, Run with Docker, and One-line install script. The page opens on Run with Docker. The tabs do not show the word Recommended. Preferring Docker is this article’s suggestion.
3. Pick a method and copy the command
The commands on all three tabs already include the URL, name, labels, concurrency, and token you filled in. In the samples below, <Token> is the placeholder for that registration token. On the page, Copy command inserts the real token.
Run with Docker (suggested)
The tab hint is “Pulls repo.anguskit.com/docker-public/angus-runner-agent from the public AngusRepo. Workspace defaults to /opt/AngusRunnerAgent/data/workspaces.” The command looks like this:
docker run -d --restart=always --name build-linux-01 \
-v /opt/AngusRunnerAgent/logs:/opt/AngusRunnerAgent/logs \
-v /opt/AngusRunnerAgent/data:/opt/AngusRunnerAgent/data \
-v /var/run/docker.sock:/var/run/docker.sock \
-e RUNNER_SERVER_URL=wss://git.anguskit.com/ws/runner \
-e RUNNER_REGISTER_TOKEN=<注册令牌> \
-e RUNNER_NAME=build-linux-01 \
-e RUNNER_LABELS=linux,docker \
-e RUNNER_MAX_CONCURRENCY=4 \
repo.anguskit.com/docker-public/angus-runner-agent:1.0.0
A few points: --restart=always brings the runner back after the machine reboots. Mounting /var/run/docker.sock lets the runner start a container on this machine for each job. When the labels are left empty, the default is linux,docker.
Zip install
The tab hint is “Download the Zip from AngusRepo and install to /opt/AngusRunnerAgent. Workspace defaults to $APP_HOME/data/workspaces. Omit the docker label for NATIVE jobs.” The command downloads and unpacks AngusRunnerAgent-1.0.0.zip, copies it to /opt/AngusRunnerAgent, sets environment variables such as RUNNER_SERVER_URL and RUNNER_REGISTER_TOKEN, runs ./doctor-native.sh to check the machine, and then runs ./startup-agent.sh to start.
With this method, the job runs directly on the host, using the JDK, Node.js, and other tools already installed on the machine. The same hint says to omit the docker label for NATIVE jobs. A runner that has the docker label is treated as a Docker runner and does not take host jobs.
One-line install script
The command looks like this:
curl -fsSL https://git.anguskit.com/runner/install.sh | bash -s -- \
--url https://git.anguskit.com --token <注册令牌> \
--name build-linux-01 --labels linux,docker --max-concurrency 4
The tab hint is “Downloads /runner/install.sh from the control plane and starts the public Docker image.” The result matches the Docker method. It fits when you would rather not assemble the docker run flags by hand.
Which tasks fit the two Docker methods, and which fit Zip, is in the “Docker or the host” article linked at the end.
4. Run it on the build machine and wait until it is online
Paste the copied command into a terminal on the build machine and run it. Then go back to the console and click Done, wait for heartbeat.
The page shows “Waiting for “build-linux-01” to come online…” and checks every few seconds. After the runner connects, it says “Runner “build-linux-01” is online”. The machine appears in the list with status Online or Idle.
After a successful connect, you can compare the list at CI/CD → Runners. This instance already has two idle runners: dev-1, mode NATIVE, executor SHELL, labels linux, native, and dev, concurrency 0/2; priv-1, mode DOCKER, executor SHELL, labels linux and docker, concurrency 0/2. build-linux-01, connected with the command above, also appears in that table, with status Idle and last heartbeat “just now”.
If 90 seconds pass and it is still not online, the page says “Timed out waiting for heartbeat. Refresh the list later to confirm.” That timeout is not always a failure. The runner may still be pulling the image. Refresh the list after a minute or two. If it is still missing, use section 6.
5. After it is connected
Once it is online, day-to-day work is watching the status, changing labels, or disabling it for a while. A reinstall is rarely needed.
- Runner status. The list uses Online, Idle, Busy, Offline, and Disabled. The runner sends a heartbeat every 15 seconds. If more than 90 seconds pass with no heartbeat and the connection is also gone, it becomes Offline.
- Change the name, labels, and concurrency. Open Edit runner from the list. A reinstall is not required. The label hint is “Comma-separated. Labels only select a runner and do not change its execution mode.”
- Reinstall or move to another machine. Open the runner detail, go to the Install runner tab, and generate the command again under Install / reinstall. The hint is “Generated from this runner’s name and labels. Issue or paste a registration token before running on a new host.” The original registration token was used up on the first connect.
- Stop using this machine for a while. Click Disable. It stops taking new jobs. Click Enable when you want it back. The disable confirmation says: “Disable runner "{name}"? It will stop picking up jobs, and heartbeats will not bring it back online.”
On a private deployment, operations can also configure a shared registration token on the server (CICD_RUNNER_REGISTER_TOKEN) and paste it at connect time. The default value of that token is change-me-runner-register-token. Change it before the service goes live. Otherwise any machine that knows the default and can reach AngusGit can register itself as a runner and take jobs.
6. When the connection fails
| What you see | Why | What to do |
|---|---|---|
| “Timed out waiting for heartbeat. Refresh the list later to confirm.”, and a refresh still shows nothing | The build machine cannot reach Control plane URL, or the registration token has expired | On the build machine, curl -I <control plane URL> to check the network. A token older than 1 hour has to be generated again, and the command copied again |
| After the Docker method, the container exits quickly | The token is wrong, or the control plane cannot be reached | Run docker logs build-linux-01 and read the last few error lines |
| The Docker method fails while pulling the image | The build machine cannot reach repo.anguskit.com
|
Let the build machine reach the public network, or import the image into an internal registry ahead of time and change the image address in the command to that internal address |
Zip method: doctor-native.sh reports an error |
JDK 21 or another dependency is missing | Install what it prints, then run ./startup-agent.sh
|
| The runner is online, and the job stays Pending | The job’s execution mode or labels do not match this runner | Read the wait reason next to the job on the run detail. The article “The runner is not taking jobs”, linked at the end, shows how to track it down |
The runner process log is on the Logs tab of the runner detail. The page says “Runner process log: registration, heartbeats, job assignment, image pulls, and step execution. Step output is on the pipeline run page.” An older runner that does not report this log shows “No process logs yet (upgrade the runner to a version that reports logs)”. In that case, look at /opt/AngusRunnerAgent/logs on the build machine.
Common questions
How many runners can one machine have?
One is usually enough. Max concurrent jobs controls how many jobs run at the same time. When the same machine must offer both Docker and host execution, install two: one with the Docker method and the docker label, and one with the Zip method and no docker label. Give them different names.
If the registration token expires, does a runner that is already connected go offline?
No. The registration token from the console is single-use. It is used only on the first connect. After a successful connect, AngusGit issues a long-lived identity token to that runner. The runner stores it on the machine and uses it for later restarts and reconnects. To connect another new machine, generate a new registration token.
Does the runner need an open port?
No. The runner opens the connection to AngusGit. The build machine does not need any port open to the outside.
Summary
A runner is the program installed on a build machine that runs pipeline jobs for AngusGit. Under CI/CD → Runners → Add Runner, confirm the Control plane URL the build machine can reach, fill in the name, labels, and concurrency, click Generate token, pick a method, copy the command, run it on the build machine, and click Done, wait for heartbeat. A machine that has Docker should use the Docker method first. A job that must build directly on the host uses the Zip method, with JDK 21 installed. On a private deployment, change the default shared registration token.
Conclusion: Under CI/CD → Runners → Add Runner, fill in a Control plane URL the build machine can reach and the labels, click Generate token, copy the command onto the build machine, and the connect is done when the list shows Online or Idle.
Top comments (0)