READY TO REGISTER RUNNERS

Last Updated: 2025-01-XX
Status: Ready for Registration
Group: blueflyio/agent-platform

Current Status

• All component templates updated with correct tags
• Setup scripts ready
• Runner registration scripts updated with project-type tags
• Runner selector component available
• Waiting for registration token

Tags for GitLab Components

Standard Tags (Always Required)

Every component job must include:

tags:
  - docker    # Required for Docker executor
  - local     # Identifies self-hosted runners

Project-Type Tags

For npm-package components:

tags:
  - npm-package
  - docker
  - local

For typescript components:

tags:
  - typescript
  - docker
  - local

Note: TypeScript projects can use both tags together:

tags:
  - npm-package
  - typescript
  - docker
  - local

For drupal-module components:

tags:
  - drupal-module
  - docker
  - local

For drupal-recipe components:

tags:
  - drupal-recipe
  - docker
  - local

For python components:

tags:
  - python
  - docker
  - local

For generic/alpine components:

tags:
  - docker
  - local

Quick Start

1. Get Registration Token

Option A: Group-Level (Recommended)

Go to: https://gitlab.com/groups/blueflyio/agent-platform/-/settings/ci_cd
Expand "Runners" section
Copy "Registration token"

Option B: Use GitLab API

export GITLAB_TOKEN="glpat-your-token"
curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.com/api/v4/groups/blueflyio%2Fagent-platform" | jq -r '.runners_token'

2. Register Runners

export RUNNER_TOKEN="your-token-here"
cd ~/Sites/LLM

# Run setup script
./setup-local-runners.sh

# Or register manually (see below)

3. Start Runners

# Start as daemon (background)
gitlab-runner run --daemon

# Verify
gitlab-runner verify
gitlab-runner list

4. Use Runner Selector Component

Update your .gitlab-ci.yml files:

include:
  - component: gitlab.com/blueflyio/agent-platform/gitlab_components/runner-selector@v0.1.x
    inputs:
      runner_type: auto
      fallback_to_shared: true

build:
  extends: .runner-npm
  script:
    - npm ci
    - npm run build

Runners That Will Be Registered

1. docker-runner (Generic)

• Tags: docker, local, mac, arm64
• Purpose: Generic Docker jobs, Alpine-based jobs
• Runner ID: Will be assigned after registration
• Executor: Docker
• Image: docker:24-dind

2. npm-runner (NPM/TypeScript)

• Tags: npm-package, typescript, docker, local, mac, arm64
• Purpose: Node.js, npm, TypeScript projects
• Runner ID: Will be assigned after registration
• Executor: Docker
• Image: node:20-alpine

3. drupal-module-runner (Drupal Modules)

• Tags: drupal-module, docker, local, mac, arm64
• Purpose: Drupal modules, PHP projects
• Runner ID: Will be assigned after registration
• Executor: Docker
• Image: registry.gitlab.com/blueflyio/docker-images/drupal-ci:php8.3

4. drupal-recipe-runner (Drupal Recipes)

• Tags: drupal-recipe, docker, local, mac, arm64
• Purpose: Drupal recipes, YAML configuration
• Runner ID: Will be assigned after registration
• Executor: Docker
• Image: registry.gitlab.com/blueflyio/docker-images/drupal-ci:php8.3

5. python-runner (Python)

• Tags: python, docker, local, mac, arm64
• Purpose: Python projects, pytest
• Runner ID: Will be assigned after registration
• Executor: Docker
• Image: python:3.12-alpine

6. k8s-runner (Kubernetes - Optional)

• Tags: kubernetes, k8s, local
• Purpose: Kubernetes executor jobs
• Runner ID: Will be assigned after registration
• Executor: Kubernetes
• Requirements: Kubernetes cluster available

Manual Registration Commands

If setup script doesn't exist, register manually:

Docker Runner (Generic)

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image docker:24 \
  --description "docker-runner" \
  --tag-list "docker,local,mac,arm64" \
  --run-untagged=false \
  --locked=false

NPM Runner

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image node:20-alpine \
  --description "npm-runner" \
  --tag-list "npm-package,typescript,docker,local,mac,arm64" \
  --run-untagged=false \
  --locked=false

Drupal Module Runner

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image registry.gitlab.com/blueflyio/docker-images/drupal-ci:php8.3 \
  --description "drupal-module-runner" \
  --tag-list "drupal-module,docker,local,mac,arm64" \
  --run-untagged=false \
  --locked=false

Drupal Recipe Runner

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image registry.gitlab.com/blueflyio/docker-images/drupal-ci:php8.3 \
  --description "drupal-recipe-runner" \
  --tag-list "drupal-recipe,docker,local,mac,arm64" \
  --run-untagged=false \
  --locked=false

Python Runner

gitlab-runner register \
  --url https://gitlab.com/ \
  --registration-token $RUNNER_TOKEN \
  --executor docker \
  --docker-image python:3.12-alpine \
  --description "python-runner" \
  --tag-list "python,docker,local,mac,arm64" \
  --run-untagged=false \
  --locked=false

Verification Steps

After registration:

1. Check runner status:

   gitlab-runner list
   gitlab-runner verify

2. Check GitLab UI:

   • Go to: https://gitlab.com/groups/blueflyio/agent-platform/-/settings/ci_cd
   • Expand "Runners" section
   • Verify all runners show as "online" and "active"

3. Test with a pipeline:

   • Create a test MR or push to a branch
   • Check pipeline runs on local runner
   • Verify job logs show correct runner

Best Practices

1. Use runner-selector component instead of manual tags
2. Enable fallback to shared runners (fallback_to_shared: true)
3. Use auto detection for project type
4. Monitor runner health in GitLab UI
5. Clean cache regularly to prevent disk issues

Tag Matching Rules

Jobs run on runners that have ALL specified tags:

Match Example:

• Job: [npm-package, docker, local]
• Runner: [npm-package, typescript, docker, local, mac, arm64]
• Match (runner has all job tags)

No Match Example:

• Job: [drupal-module, docker, local]
• Runner: [npm-package, docker, local]
• No match (runner missing 'drupal-module')

Summary

All components now use project-type tags:

• npm-package - For Node.js/npm
• typescript - For TypeScript
• drupal-module - For Drupal modules
• drupal-recipe - For Drupal recipes
• python - For Python
• docker + local - Always required

Never use: node, nodejs, php, drupal (use project-type tags instead)

Next Step: Get registration token and run setup script!