Using Self-hosted Runners

This document introduces how to deploy and use self-hosted Runners and Kubernetes Runners, including configuration installation, tag rules, and management of organization-level and project-level Runners.

When the official hosted Runners cannot meet the needs—requiring special hardware (GPU, specific architecture), internal network environment, or custom toolchain—self-hosted Runners can be deployed.

Configuration Instructions

AtomGit Action supports two types of custom Runners: Host and Kubernetes. The configuration methods are as follows.

Host Runner Configuration and Installation

Step 1: Enter the Runner Management Page

Go to the target project/organization page and click on Project Settings/Organization Settings in the top navigation bar.
In the left sidebar, expand the Actions group and click Runners.
Enter the "Runners" page. There are two tabs at the top of the page: Host Runners and Kubernetes Runners Sets, with Host Runners selected by default.

Note: When first entering, the page displays "No data", indicating that no Runners have been configured for this repository/organization.

Step 2: Create a Host Runner

Click the "+ Add Custom Runner" button at the top right of the page.
In the pop-up dropdown menu, select "Add Host Runner" to enter the Runner configuration form.

Step 3: Fill in the Runner Configuration

Field	Required	Description
Runner Name	Required	A custom identifier for the Runner, such as `CI-runner`, used to distinguish different Runners on the management page
Installation Preparation	—	Precondition for the environment and auto-installation options (see below for details)
Runner Working Directory	Required	The working directory path of the Runner on the host. The system will automatically generate a default value (e.g., `/opt/runner_1783325952`), which can be modified as needed
Runner Environment Image	Required	Choose the operating system image for the Runner to run. Supports Ubuntu and EulerOS
Custom Tags	Optional	Add custom tags to the Runner for precise matching in workflows (see below for details)

Installation Preparation Options:

The page prompts: "Your host needs to have access to the Internet and have Java 8, Git, and Docker environments installed."

The system provides the following four checkboxes, all checked by default:

Option	Default	Description
☑ Auto-install JDK	Checked	The installation script automatically detects and installs the JDK environment
☑ Auto-install Git	Checked	The installation script automatically detects and installs Git
☑ Auto-install Docker	Checked	The installation script automatically detects and installs Docker
☑ Restart without registration	Checked	After the host restarts, the Runner automatically recovers its registered state without re-executing the registration script

Tip: If some environments are pre-installed on the host, you can uncheck the corresponding options, and the installation script will skip the already installed components. It is recommended to keep "Restart without registration" checked to ensure the Runner service is always available.

Custom Tag Configuration:

Custom tags are used to precisely match the target Runner in the workflow's runs-on. The tag table contains the following columns:

Column Name	Required	Description
Tag Name	Required	The key of the tag, such as `os`, `arch`, `env`, `server`
Default Value	Optional	The default value of the tag, such as `euler`, `x64`, `prod`, `backend`
Tag Color	Optional	Select a color for the tag to visually distinguish it on the management page
Operation	—	Click "Delete" to remove the tag

The system will automatically generate default tag rows based on the selected environment image (e.g., os=euler). You can click "+ Add Custom Tag" to add more tags on this basis.

Step 4: Get and Execute the Installation Script

After completing the form configuration, click the "Get Execution Script" button at the bottom left.
The system will automatically generate a Shell installation script based on your configuration, displayed in the "Execution Script" area below the form.
Click the copy icon in the top right corner of the script area to copy the complete script.

The structure of the generated script is as follows:

export RUNNER_INSTALL_URL=...
export RUNNER_INSTALL_FILE=install-octopus-runner.sh

# Prioritize using curl, fall back to wget if not available
if [ -f 'which curl' ]; then
  curl -# -k -o ${RUNNER_INSTALL_FILE} ${RUNNER_INSTALL_URL}
else
  wget ... ${RUNNER_INSTALL_URL}
fi

# Paste and execute the full script copied from the page
# The script will automatically complete: download the Runner → install dependencies → register to the platform → start the service

Important:

The target host must have access to the Internet.

The script requires sudo permissions to execute. Please ensure the current user has sudo permissions.

The installation script contains a one-time registration token. Do not leak or reuse it.

Step 5: Verify the Runner Status

After the script runs successfully, return to the AtomGit platform's Project Settings → Runners page.
Confirm the status of the newly created Runner in the Runner list is Online (green indicator).
If the Runner shows as offline, check the host's network connectivity and the script execution logs.

Step 6: Use the Self-hosted Runner in the Workflow

Specify the Runner tags in runs-on to match the self-hosted Runner:

# .gitcode/workflows/gpu-build.yml
stages:
  gpu-test:
    name: GPU Test
    jobs:
      name: cuda-compile
      runs-on: [self-hosted, euler, x64, gpu]
      steps:
        - run: nvcc -o myapp myapp.cu

# Use custom tags for precise matching
jobs:
  backend-deploy:
    name: backend-deploy
    runs-on: [self-hosted, env=prod, server=backend]
    steps:
      - run: ./deploy.sh

Tag Matching Rules: All tags listed in runs-on must exist simultaneously in the Runner's tag set to be considered a successful match. The tags registered with the Runner (including both automatically generated and custom tags) constitute its complete tag set.

Configuration and Installation of Kubernetes Runners Sets

Kubernetes Runners Sets run as Pods in your Kubernetes cluster, supporting elastic scaling and resource isolation, suitable for scenarios requiring containerized execution environments and on-demand scaling.

Step 1: Enter the Runner Management Page

Go to the target project/organization page and click on Project Settings/Organization Settings in the top navigation bar.
In the left sidebar, expand the Actions group and click Runners.
Enter the "Runners" page and click the Kubernetes Runners Sets tab at the top.

Step 2: Create a Kubernetes Runners Set

Click the "+ Add Custom Runner" button at the top right of the page.
In the pop-up dropdown menu, select "Add Kubernetes Runners Set" to enter the Runner configuration form.

Step 3: Fill in the Runner Configuration

Field	Required	Description
Name	Required	A custom identifier for the Runner, such as `k8s-runner-prod`
Cluster URL	Required	The access address of the Kubernetes API Server, such as `https://10.0.0.1:6443`
Kubernetes config credentials	Required	The kubeconfig credential content of the cluster, used for the Runner to connect and authenticate to the cluster
Namespace	Required	The target namespace for deploying the Runner Pod. The default is `default`, which can be modified as needed
Image Name	Not required	The container image for the Runner to run. The default is `Ubuntu`, pre-set by the system
CPU	Required	The number of CPU cores requested per Runner Pod. The default is 1 core
Memory	Required	The memory size requested per Runner Pod. The default is 4 GB
Minimum Runner Count	Required	The lower limit of elastic scaling. The minimum number of Pods that should always be maintained in the cluster, default is 1
Maximum Runner Count	Required	The upper limit of elastic scaling. The maximum number of Pods the cluster can scale to, default is 1
Custom Tags	Optional	Add custom tags to the Runner for precise matching in workflows

Cluster Connection Configuration Notes:

Cluster URL: This is the address of the Kubernetes API Server. The value of the server field in the cluster's kubeconfig file can be found.
Kubernetes config credentials: This is the content of the kubeconfig file, including the certificate and authentication information of the cluster. To obtain it:
1. On the cluster management node, execute cat ~/.kube/config to get the complete content.
2. Or download the kubeconfig file from the cluster details page in the cloud platform console and paste the content into the input box.

Security Tip: Kubernetes config credentials contain the access certificate and key of the cluster. Please keep them secure and avoid leakage.

Elastic Scaling Configuration Notes:

Configuration Item	Description
Minimum Runner Count	The number of Runner Pods that should always be maintained in the cluster, even when there are no pipeline tasks, ensuring that tasks can be scheduled immediately when they arrive
Maximum Runner Count	The maximum number of Runner Pods that can be scaled when the number of pipeline tasks increases

When Minimum = Maximum = 1, it means a fixed 1 Runner Pod, and no elastic scaling is performed.
If concurrent execution is needed, increase the maximum count. For example: Minimum 1, Maximum 5 means keeping 1 Pod idle and scaling up to 5 Pods during peak times.

Custom Tag Configuration:

Same as the Host Runner, the tag table includes columns for tag name, default value, tag color, and operation. You can click "+ Add Custom Tag" to add more tags (such as env=staging, team=backend, etc.).

Step 4: Create the Runner

After completing the form configuration, click the "Create" button at the bottom left.
The system will automatically deploy the Runner Pod in the specified Kubernetes cluster and namespace.

Step 5: Verify the Runner Status and View Details

Return to the AtomGit platform's Project Settings → Runners page and switch to the Kubernetes Runners Sets tab.
Confirm the status of the newly created Runner in the Runner list is Online (green indicator).
You can also verify whether the Pod is running normally in the Kubernetes cluster:

kubectl get pods -n <namespace> | grep runner

If the Runner shows as offline, check:
- Whether the cluster URL and Kubernetes config credentials are correct
- Whether the target namespace exists
- Whether the cluster network can access the AtomGit platform

View Runner Details: Click the Runner name in the list to enter the details page. You can view more information through four tabs:

Basic Information: Running status, Runner type, environment image and specifications, associated Runner group, number of executed tasks, elastic scaling configuration, last active time.
Tags: Displays all key-value pairs of tags and colors. Click the gear icon to edit tags.
Runners List: Displays the names, status (idle/running/offline), IP, and last active time of all real-time Pod instances under the current Runner set.
Execution History: Displays the name, associated pipeline, status, execution time, and duration of executed Jobs. Clicking the task name will redirect to the pipeline run details.

Step 6: Use Kubernetes Runners Sets in the Workflow

Specify the Runner tags in runs-on to match the Kubernetes Runners Sets:

# .gitcode/workflows/k8s-build.yml
jobs:
  container-build:
    name: container-build
    runs-on: [self-hosted, k8s, arch=x64]
    steps:
      - name: Checkout source code
        uses: checkout
      - name: Run test
        run: npu test

# Use custom tags for precise matching
jobs:
  staging-test:
    name: staging-test
    runs-on: [self-hosted, env=staging, team=backend]
    steps:
      - name: Run test
        run: npm test

Comparison between Host Runners and Kubernetes Runners Sets

Comparison Dimension	Host Runner	Kubernetes Runners Sets
Running Form	Installed on physical machines/virtual machines and runs as a system service	Runs as a Pod in the K8s cluster
Creation Method	Get the installation script after filling in the configuration on the page and manually execute it on the host	System automatically deploys after filling in the cluster information and resource configuration on the page
Resource Management	Relies on the host's own hardware resources	Declares resource requests via CPU/memory fields and is managed by K8s scheduling
Elastic Scaling	Not supported, each host runs a fixed Runner	Supports configuring minimum/maximum Runner counts and scales on demand
Environment Isolation	Multiple Jobs on the same host share the environment	Each Runner Pod has an independent container environment, naturally isolated
Applicable Scenarios	Requires special hardware like GPU/NPU, internal network environment, long-term operation	Requires elastic scaling, containerized execution, environment isolation, and quick expansion
Pre-requisites	Host has Internet access, pre-installed Java 8, Git, and Docker	Has a usable K8s cluster, provides kubeconfig credentials

Self-hosted Runner Tag Rules

The tag system of self-hosted Runners differs from that of official hosted Runners:

Auto-generated Tags: When creating a Runner, the system automatically generates tags based on the selected environment image (e.g., os=euler) and defaults to adding the self-hosted tag to distinguish between hosted and self-hosted types.
Custom Tags: Added through the "custom tags" table when creating a Runner. Supports setting tag names (required), default values (optional), and tag colors for precise matching and visual management. Additionally, the Runner supports string and key-value tag formats (depending on whether the default value is filled).

Tag Matching Logic: All tags in the runs-on list of the workflow must completely match the Runner's tag set or be a subset of the Runner's tags.

# Runner Tags: self-hosted, os=euler, arch=x64, env=prod, server=backend
# The workflow processes production environment business and needs to run on the production environment Runner

# The following workflow can match
jobs:
  deploy-prod:
    name: deploy-prod
    runs-on: [self-hosted, env=prod, server=backend]

# The following workflow cannot match (missing the env=prod tag)
jobs:
  deploy-prod:
    name: deploy-prod
    runs-on: [self-hosted, server=backend]

Organization-level vs Project-level Runners

Level	Registration Entry	Service Scope
Organization-level	Organization Settings → Runners	All projects under the organization, supports availability for specific projects
Project-level	Project Settings → Runners	Only the project's pipelines

Recommendation: General Runners (such as standard builds) are registered as organization-level, while specialized Runners are registered as project-level.

Tip: Considering the convenience of Runner management, organization-level Runners must belong to a Runner Group.

Runner Update

To update a Runner, re-obtain the installation script on the AtomGit platform and execute it:

Go to the Project Settings → Runners page and find the target Runner.
Delete the old version of the Runner, and then click "+ Add Custom Runner" → "Add Host Runner" again.
Fill out the form again according to the original configuration (Runner name, environment image, tags, etc.), and click "Get Execution Script".
Execute the newly generated installation script on the target host.

Tip: It is recommended to stop the current Runner service before updating and verify the service status after the update is complete.

Configuration Instructions​

Host Runner Configuration and Installation​

Configuration and Installation of Kubernetes Runners Sets​

Comparison between Host Runners and Kubernetes Runners Sets​

Self-hosted Runner Tag Rules​

Organization-level vs Project-level Runners​

Runner Update​