A Gitlab Runner Custom Executor utilizing Anka Build Cloud to run your Gitlab jobs on macOS VMs.

1. Install and Register a self-managed Gitlab Runner. See here for more info.
2. An active Anka Build Cloud.
3. An Anka VM Template in the Anka Build Cloud Registry with git installed, Remote Login enabled, and ssh port forwarding configured (more info).

1. Download the binary to the same machine your Gitlab Runner is running on.

2. Add the following [runners.custom] block to Gitlab Runner configuration:

   By default, runner config is at ~/.gitlab-runner/config.toml

   Any environment variables can be specified in the environment block and apply to all jobs. However, they are also available in the job's environment, so avoid placing SSH credentials and other sensitive variables in the environment block.

   environment = [
     "ANKA_CLOUD_CONTROLLER_URL=https://anka.contoller:8090",
     "ANKA_CLOUD_TEMPLATE_ID=8c592f53-65a4-444e-9342-79d3ff07837c",
   ]
   [runners.custom]
       config_exec = "/path/to/anka-cloud-gitlab-executor"
       config_args = ["config"]
       prepare_exec = "/path/to/anka-cloud-gitlab-executor"
       prepare_args = ["prepare"]
       run_exec = "/path/to/anka-cloud-gitlab-executor"
       run_args = ["run"]
       cleanup_exec = "/path/to/anka-cloud-gitlab-executor"
       cleanup_args = ["cleanup"]
   

3. Add executor = "custom" to [[runners]] block

4. (Optional) Tag your Anka runners

Check out the full configuration spec for more info

⚠️ Prepare stage is the one responsible for starting an Instance in the Controller, and waiting for it to get started. Default timeout is 1 hour, make sure you modify this according to the load and expected pull times of your Anka Cloud !

All variables are parsed as strings, since Gitlab is stating: "To ensure consistent behavior, you should always put variable values in single or double quotes." Reference

Accepted values for booleans are: "1", "t", "T", "true", "TRUE", "True", "0", "f", "F", "false", "FALSE", "False"

To prevent SSH credentials from being exposed to the job log, they can instead be specified via command line arguments in the config.toml > runner.custom:

Note: values specified via job environment variables will override those provided via command line arguments.

  [runners.custom]
      config_exec = "/path/to/anka-cloud-gitlab-executor"
      config_args = ["config"]
      prepare_exec = "/path/to/anka-cloud-gitlab-executor"
      prepare_args = ["prepare"]
      run_exec = "/path/to/anka-cloud-gitlab-executor"
      run_args = ["run", "--ssh-username", "anka", "--ssh-password", "admin"]
      cleanup_exec = "/path/to/anka-cloud-gitlab-executor"
      cleanup_args = ["cleanup"]

Example basic pipeline:

variables:
  ANKA_CLOUD_CONTROLLER_URL: "http:https://anka.contoller:8090"
  ANKA_CLOUD_TEMPLATE_ID: "8c592f53-65a4-444e-9342-79d3ff07837c"

build-job:
  stage: build
  tags:
    - anka_cloud_executor
  script:
    - echo "building"

test-job:
  stage: test
  tags:
    - anka_cloud_executor
  script:
    - echo "running tests"

Example pipeline with all available configurations:

variables:
  ANKA_CLOUD_CONTROLLER_URL: "https://anka.contoller:8090"
  ANKA_CLOUD_TEMPLATE_ID: "8c592f53-65a4-444e-9342-79d3ff07837c"
  ANKA_CLOUD_TEMPLATE_TAG: "builder"
  ANKA_CLOUD_NODE_ID: "038d5b6f-2e54-44fd-a8bc-53629b086887"
  ANKA_CLOUD_DEBUG: "true"
  ANKA_CLOUD_SKIP_TLS_VERIFY: "TRUE"
  ANKA_CLOUD_CA_CERT_PATH: "/mnt/certs/ca.pem"
  ANKA_CLOUD_CLIENT_CERT_PATH: "/mnt/certs/devops-crt.pem"
  ANKA_CLOUD_CLIENT_CERT_KEY_PATH: "/mnt/certs/devops-key.pem"
  ANKA_CLOUD_SSH_USER_NAME: "veertu"
  ANKA_CLOUD_SSH_PASSWORD: "P@$$w0rd"
  ANKA_CLOUD_CUSTOM_HTTP_HEADERS: "{\"X-CUSTOM-HEADER\": \"custom-value\"}"
  ANKA_CLOUD_BUILDS_DIR: "/tmp/veertu/build"
  ANKA_CLOUD_CACHE_DIR: "/tmp/veertu/cache"
  
build-job-1:
  stage: build
  tags:
    - anka_cloud_executor
  variables:
    ANKA_CLOUD_TEMPLATE_ID: "8c592f53-65a4-444e-9342-79d3ff07837c"
  script:
    - echo "building part 1"

build-job-2:
  stage: build
  tags:
    - anka_cloud_executor
  variables:
    ANKA_CLOUD_NODE_GROUP_ID: "ff7e840e-9510-42e3-44ae-7a65c00c5979"
    ANKA_CLOUD_TEMPLATE_ID: "8c592f53-65a4-444e-9342-79d3ff07837c"
  script:
    - echo "building part 2"


unit-test-job:
  stage: test
  tags:
    - anka_cloud_executor
  variables:
    ANKA_CLOUD_TEMPLATE_TAG: "tester"
    ANKA_CLOUD_PRIORITY: "1"
    ANKA_CLOUD_TEMPLATE_NAME: "sonoma-xcode15"
  script:
    - echo "running unit tests"

integration-test-job:
  stage: test
  tags:
    - anka_cloud_executor
  variables:
    ANKA_CLOUD_TEMPLATE_TAG: "tester"
    ANKA_CLOUD_PRIORITY: "10"
    ANKA_CLOUD_TEMPLATE_ID: "8c592f53-65a4-444e-9342-79d3ff07837c"
    ANKA_CLOUD_VM_VCPU: "1"
    ANKA_CLOUD_VM_VRAM_MB: "4096"
  script:
    - echo "running integration tests"

Please read Gitlab Custom Executor docs first here

This project produces a single binary, that accepts the current Gitlab stage as its first argument:

1. Config
2. Prepare (Creates the Instance on the Anka Cloud, waiting for it to get scheduled)
3. Run (Creates a remote shell on the VM, and pushes Gitlab provided script with stdin)
4. Cleanup (Performs Termination request to the Anka Cloud Controller)