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—such as requiring special hardware (GPU, specific architecture), internal network environment, or custom toolchain—you can deploy self-hosted Runners.

Configuration Instructions

AtomGit Action supports two types of custom Runners: host and Kubernetes. The configuration method is as follows.

Host Runner Configuration and Installation

Step 1: Enter the Runner Management Page

1. Go to the target project/organization page and click on Project Settings/Organization Settings in the top navigation bar.
2. In the left sidebar, expand the Actions group and click Runners.
3. 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

1. Click the "+ Add Custom Runner" button at the top right of the page.
2. In the 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 path to the working directory 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 must have access to the internet and have Java 8, Git, and Docker installed."

The system provides the following 4 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 status without re-executing the registration script

Tip: If some environments are already 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

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

The generated script example structure is as follows:

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

# Prefer curl, fallback 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

4. Log in to the target host and paste and execute the script in the terminal:

# 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; 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

1. After the script runs successfully, return to the AtomGit platform's Project Settings → Runners page.
2. Confirm that the newly created Runner's status is Online (green indicator) in the Runner list.
3. If the Runner shows as offline, check the host network connectivity and 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 simultaneously exist in the Runner's tag set to be considered a successful match. The tags registered by the Runner (including both automatically generated and custom tags) form 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 scalability.

Step 1: Enter the Runner Management Page

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

Step 2: Create a Kubernetes Runners Set

1. Click the "+ Add Custom Runner" button at the top right of the page.
2. In the 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, e.g., https://10.0.0.1:6443
Kubernetes config Credential	Required	The kubeconfig credential content of the cluster, used for the Runner to connect and authenticate the cluster
Namespace	Required	The target namespace for deploying the Runner Pod, defaulting to default, which can be modified as needed
Image Name	Not Required	The container image for the Runner to run, defaulting to Ubuntu, pre-set by the system
CPU	Required	The number of CPU cores requested per Runner Pod, default 1 core
Memory	Required	The memory size requested per Runner Pod, default 4 GB
Minimum Runner Count	Required	The lower limit of elastic scaling, the minimum number of Pods always maintained in the cluster, default 1
Maximum Runner Count	Required	The upper limit of elastic scaling, the maximum number of Pods the cluster can scale up to, default 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, which can be found in the server field of the cluster's kubeconfig file.
• Kubernetes config Credential: This is the content of the kubeconfig file, containing the certificate and authentication information of the cluster. How to obtain it:
  1. Execute cat ~/.kube/config on the cluster management node to get the full 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: The Kubernetes config credential contains the access certificate and key of the cluster. Please keep it safe and avoid leaking it.

Elastic Scaling Configuration Notes:

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

• When Minimum = Maximum = 1, it means a fixed 1 Runner Pod, without elastic scaling.
• If you need to support concurrent execution, you can increase the maximum count. For example: Minimum 1, Maximum 5, meaning 1 Pod is retained when idle, and can scale up to 5 during peak times.

Custom Tag Configuration:

Same as the Host Runner, the tag table includes four columns: 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

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

Step 5: Verify the Runner Status and View Details

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

kubectl get pods -n <namespace> | grep runner

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

View Runner Details: Click on the Runner name in the list to enter the details page and 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, and last active time.
• Tags: Displays all tag key-value pairs and colors. Click the gear icon to edit the 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, pipeline, status, execution time, and duration of executed Jobs. Clicking the task name jumps to the pipeline run details.

Step 6: Use the Kubernetes Runners Set in the Workflow

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

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

# Use custom tags for precise matching
jobs:
  staging-test:
    name: staging-test
    runs-on: [self-hosted, env=staging, team=backend]
    steps:
      - 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, running as a system service	Runs as a Pod in the K8s cluster
Creation Method	Obtain the installation script after filling in the configuration on the page, and manually execute it on the host	The 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, managed by K8s scheduling
Elastic Scaling	Not supported, each host runs a fixed Runner	Supports configuring minimum/maximum Runner counts for on-demand scaling
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 (GPU/NPU), internal network environment, long-term operation	Requires elastic scaling, containerized execution, environment isolation, fast expansion
Pre-requisites	The host has internet access, and Java 8, Git, Docker are pre-installed	Has an available K8s cluster, and 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 adds the self-hosted tag by default to distinguish between hosted and self-hosted types.
• Custom Tags: Added through the "Custom Tags" table when creating the Runner. It supports setting the tag name (required), default value (optional), and tag color, used for precise matching and visual management. Additionally, the Runner supports two tag formats: String and key-value (depending on whether the default value is filled).

Tag Matching Logic: All tags in the workflow's runs-on list 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 tasks 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 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 pipelines of the organization, supports availability for specific projects
Project-level	Project Settings → Runners	Only this project's pipeline

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 Updates

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

1. Go to the Project Settings → Runners page and find the target Runner.
2. Delete the old version of the Runner and re-click "+ Add Custom Runner" → "Add Host Runner".
3. Fill out the form again according to the original configuration (Runner name, environment image, tags, etc.), and click "Get Execution Script".
4. 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.