Using Self-Hosted Runners

Applicable Scenarios

When the official hosted runners cannot meet the requirements—such as needing special hardware (GPU, specific architecture), an internal network environment, a custom toolchain, or large-scale parallelism—a self-hosted runner can be deployed.

Configuration Instructions

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

Configuring and Installing Host Runners

Step 1: Access the Runner Management Page

Enter 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 on 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 displays "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 upper right corner of the page.
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 automatic 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
CPU Architecture	Required	Select the CPU architecture of the host. Supports 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 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	Choose 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 and CPU architecture (e.g., os=euler, arch=x64). You can click "+ Add Custom Tag" to add more tags based on this.

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 upper right corner of the script area to copy the complete script.

The generated script example structure is as follows:

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

# Use a 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 the 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. 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 logs.

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

Use the runs-on directive to specify the runner tag to match the self-hosted runner:

# .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 registered with the runner (including auto-generated and custom tags) form its complete tag set.

Configuring and Installing Kubernetes Runners

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

Step 1: Access the Runner Management Page

Enter 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 on Runners.
Enter the "Runners" page and click on the Kubernetes-Runner tab at the top.

Step 2: Create a Kubernetes Runner

Click the "+ Add Custom Runner" button in the upper right corner of the page.
In the dropdown menu, select "Add Kubernetes Runner" 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 credentials of the cluster, used for the runner to connect and authenticate the cluster
Namespace	Required	The target namespace for deploying the runner Pod. By default, it is `default`, and can be modified as needed
Image Name	Not required	The container image for the runner to run. By default, it is `Ubuntu`, pre-set by the system
CPU Architecture	Not required	Choose the CPU architecture for the Pod to run. Supports x64 (default) and arm
CPU	Required	The number of CPU cores requested per runner Pod. Default is `1` core
Memory	Required	The memory size requested per runner Pod. Default is `4` GB
Minimum Runner Count	Required	The lower limit for elastic scaling. The minimum number of Pods kept in the cluster at all times. Default is `1`
Maximum Runner Count	Required	The upper limit for 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. You can find the value of the server field in the kubeconfig file of the cluster.
Kubernetes config credentials: This is the content of the kubeconfig file, including the certificate and authentication information of the cluster. How to get it:
1. Execute cat ~/.kube/config on the cluster management node to obtain the complete content.
2. Or download the kubeconfig file from the cluster details page in the cloud platform console and paste its content into the input box.

Security Tip: Kubernetes config credentials contain the cluster's access certificate and key. Please keep them secure and avoid leaking them.

Elastic Scaling Configuration Notes:

Configuration Item	Description
Minimum Runner Count	The number of runner Pods always 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 the cluster can scale to when the number of pipeline tasks increases

When Minimum = Maximum = 1, it means a fixed 1 runner Pod, and no elastic scaling is performed.
To support concurrent execution, increase the maximum number. For example: Minimum 1, Maximum 5, meaning 1 Pod is kept idle, and up to 5 Pods can be scaled during peak times.

Custom Tag Configuration:

Same as for Host Runners, the tag table includes columns for 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 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 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. Click the job name to jump to the pipeline run details.

Step 6: Use the Kubernetes Runner in the Workflow

Use the runs-on directive to specify the runner tag to match the Kubernetes runner:

# .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 Runners and Kubernetes Runners

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	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 like GPU/NPU, internal network environment, long-term operation	Requires elastic scaling, container execution, environment isolation, and rapid expansion
Pre-requisites	The host must have internet access and pre-install Java 8, Git, and Docker	Must have an available K8s cluster and provide 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 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 through the "custom tags" table when creating the runner, supporting setting tag names, default values, and tag colors for precise matching and visual management.
Tag Groups: You can set the 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 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:
  - name: deploy-prod
    runs-on: [self-hosted, env-prod, server-backend]

# The following workflow cannot match (missing the env-prod tag)
jobs:
  - 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, supporting availability for specific projects
Project-Level	Project Settings → Runners	Only the pipelines of this project

Recommendation: General runners (such as standard builds) should be registered as organization-level, while specialized runners should be registered as project-level.

Runner Updates

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.), 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.

Applicable Scenarios​

Configuration Instructions​

Configuring and Installing Host Runners​

Configuring and Installing Kubernetes Runners​

Comparison Between Host Runners and Kubernetes Runners​

Self-Hosted Runner Tag Rules​

Organization-Level vs Project-Level Runners​

Runner Updates​