Using Self-Hosted Runners

Applicable Scenarios: When the official hosted runners cannot meet the requirements—special hardware (GPU, specific architecture), internal network environment, custom toolchain, or large-scale parallelism—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 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 Runner and Kubernetes Runner, with Host Runner selected by default.

Note: When first entering, the page shows "No data yet," indicating that no runner has been configured for this repository/organization.

Step 2: Create a Host Runner

Click the "+ Add Custom Runner" button in the top right corner of the page.
In the dropdown menu, select "Add Host Runner" to enter the runner configuration form.

Step 3: Fill in 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 environment and automatic installation options (see below for details)
Runner Working Directory	Required	The working directory path of the runner on the host. The system will 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, supporting Ubuntu and EulerOS
CPU Architecture	Required	Choose the CPU architecture of the host, supporting x64 and arm64
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 restores its registered state 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 installed components. It is recommended to keep "Restart without registration" checked to ensure the runner service remains 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	Choose a color for the tag to help distinguish it visually 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 and CPU architecture (such as os=euler, arch=x64). 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 generate a Shell installation script based on your configuration and display it in the "Execution Script" area below the form.
Click the copy icon in the top right corner 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

# Use self-hosted runner
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 runner → install dependencies → register with the platform → start the service

Important:

The target host must have access to the internet.

The script requires sudo permissions to run. 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 that the newly created runner's status is Online (green indicator) in the runner list.
If the runner shows as offline, check the host's network connectivity and the script execution log.

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

Match the self-hosted runner by specifying the runner tags in runs-on:

# .gitcode/workflows/gpu-build.yml
stages:
  - 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:
  - 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 of the runner (including automatically generated and custom tags) form its complete tag set.

Kubernetes Runner Configuration and Installation

The Kubernetes Runner runs as a Pod 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 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-Runner tab at the top.

Step 2: Create a Kubernetes Runner

Click the "+ Add Custom Runner" button in the top right corner of the page.
In the dropdown menu, select "Add Kubernetes Runner" to enter the runner configuration form.

Step 3: Fill in 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 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. The default is `default`, which can be modified as needed
Image Name	Not Required	The container image the runner runs on. The default is `Ubuntu`, preset by the system
CPU Architecture	Not Required	Choose the CPU architecture for the Pod to run, supporting x64 (default) and arm
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 kept in the cluster, default `1`
Maximum Runner Count	Required	The upper limit of elastic scaling. The maximum number of Pods that can be scaled up in the cluster, 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. It can be found in the server field of the cluster's kubeconfig file.
Kubernetes config credential: 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, run cat ~/.kube/config 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 secure and avoid leakage.

Elastic Scaling Configuration Notes:

Configuration Item	Description
Minimum Runner Count	The number of runner pods that should always be kept 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 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 support for concurrent execution, you can increase the maximum number. For example: Minimum 1, Maximum 5, meaning 1 pod is retained when idle, and up to 5 pods can be scaled 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. The system will automatically generate a default tag row based on the selected CPU architecture (e.g., arch=x64). You can click "+ Add Custom Tag" to add more tags (e.g., 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.
If you want to cancel this configuration, click "Cancel" to return to the previous page.

Step 5: Verify the Runner Status and View Details

Return to the AtomGit platform's Project Settings → Runners page and switch to the Kubernetes-Runner tab.
Confirm that the newly created runner's status is Online (green indicator) in the runner list.
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

Viewing Runner Details: Click the runner name in the list to enter the detail 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 key-value pairs of tags and their colors. Click the gear icon to edit tags.
Runners List: Shows the names, statuses (idle/running/offline), IP addresses, and last active times of all real-time Pod instances under the current runner group.
Execution History: Displays the names of executed jobs, their associated pipelines, status, execution time, and duration. Clicking the job name jumps to the pipeline run details.

Step 6: Use the Kubernetes Runner in the Workflow

Match the Kubernetes runner by specifying the runner tags in runs-on:

# .gitcode/workflows/k8s-build.yml
jobs:
  - name: container-build
    runs-on: [self-hosted, k8s, arch-x64]
    steps:
      - uses: checkout
      - run: docker build -t myapp:latest .

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

Comparison Between Host Runner and Kubernetes Runner

Comparison Dimension	Host Runner	Kubernetes Runner
Running Form	Installed on physical machines/virtual machines and runs 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	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 through CPU/memory fields and is managed by K8s scheduling
Elastic Scaling	Not supported, each host runs a fixed runner	Supports configuring minimum and 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 like GPU/NPU, internal network environment, long-term operation	Requires elastic scaling, containerized execution, environment isolation, and quick expansion
Pre-requisites	The host has access to the internet and has Java 8, Git, and Docker 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 generates tags based on the selected environment image and CPU architecture (e.g., os=euler, arch=x64) and adds the self-hosted tag by default to distinguish between hosted and self-hosted types.
Custom Tags: Added via the "custom tags" table when creating the runner, supporting setting tag names, default values, and tag colors for precise matching and visual management.
Tag Group: You can set a group attribute for the runner on the management page for organizational classification.

Tag Matching Logic: All tags in the workflow's runs-on list must fully 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 a production environment runner

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

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

Organization-Level vs Project-Level Runner

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: Register general runners (such as standard builds) as organization-level and specialized runners as project-level.

Runner Update

To update the runner, you need to 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.), 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​

Kubernetes Runner Configuration and Installation​

Comparison Between Host Runner and Kubernetes Runner​

Self-Hosted Runner Tag Rules​

Organization-Level vs Project-Level Runner​

Runner Update​