akua-dev · robinbraemer · Aug 13, 2026 · Aug 13, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -22,6 +22,14 @@ The rendered profile content lives in `profile/README.md`.
 - After README changes, scan for broken relative asset links.
 - Preview rendered Markdown before shipping visual changes.
 
+## GitHub Actions runners
+
+- Read [RUNNERS.md](RUNNERS.md) before selecting a self-hosted runner label.
+- Treat [runner-profiles.json](runner-profiles.json) as the machine-readable
+  resource and capability contract.
+- Use only the stable labels in that catalog; do not encode backend, runtime,
+  provider, or node details in repository workflows.
+
 ## Maintaining this file
 
 Keep this file for knowledge useful to almost every future agent session in this

diff --git a/README.md b/README.md
@@ -5,13 +5,8 @@ This repository maintains the public GitHub organization profile for `akua-dev`.
 The rendered organization profile lives in
 [profile/README.md](profile/README.md).
 
-This change installs the base-owned, secret-free validation infrastructure for
-the provider-neutral runner catalog. It intentionally publishes no runner
-catalog yet.
-
-After this bootstrap merges to `main`, create the follow-up catalog publication
-change from that merge commit. That change adds `RUNNERS.md`,
-`runner-profiles.yaml`, `runner-profiles.json`, and
-`runner-catalog-manifest.json`; its pull request is then checked by the
-base-owned [`runner-catalog-trusted.yml`](.github/workflows/runner-catalog-trusted.yml)
-workflow against the private `akua-dev/gitops` source.
+The organization-wide, provider-neutral GitHub Actions contract is documented
+in [RUNNERS.md](RUNNERS.md). Machine consumers can use
+[runner-profiles.yaml](runner-profiles.yaml) or
+[runner-profiles.json](runner-profiles.json); provenance is bound to the private
+GitOps source by [runner-catalog-manifest.json](runner-catalog-manifest.json).
diff --git a/RUNNERS.md b/RUNNERS.md
@@ -0,0 +1,83 @@
+# Akua GitHub Actions runner profiles
+
+This provider-neutral catalog defines the stable runner labels and their conservative guarantees.
+Workflows select a label by declared resources and capabilities; the implementation behind a label may change without repository edits.
+Capacity is shared across all profiles and capped at 4 concurrent jobs. A label does not reserve a private slot.
+
+<!-- runner-catalog-contract
+contractVersion: 2.0.0
+capacity:
+  scope: organization
+  allocation: shared
+  maxConcurrentJobs: 4
+  queueSlo: 
+  notes:
+  - Capacity is shared by all three profiles; a profile label does not reserve a private
+    slot.
+  - Four concurrent jobs are the current safe contract. Six was only a short load
+    experiment.
+selection:
+  safeMatch:
+    resources: required-at-most-guaranteed-minimum
+    capabilities: required-subset-of-guaranteed
+  order:
+  - akua-x64-ci-v2
+  - akua-docker-ci-v2
+  - akua-heavy-ci-v2
+  noMatch: external-runner-or-reduce-requirements
+provenance:
+  repository: akua-dev/gitops
+  path: clusters/agentos/runner-platform/profiles.yaml
+  revision: 59234e828aa544b2079404ffccd12d334567c0ac
+  sha256: 00a7ffd62374be2919214455967c06befc4f29c9425b682e07290e5606bca7e5
+-->
+
+## Selection rules
+
+1. Select the first profile whose guaranteed resources meet the declared requirements and whose capabilities contain every required capability.
+2. Use the stable label in workflow configuration; do not infer implementation details from the label.
+3. Use `akua-heavy-ci-v2` only when requirements exceed Docker but fit Heavy: 4 vCPU, 7168 MiB memory and 20480 MiB usable disk.
+Requirements above Heavy, or capabilities absent from every profile, require an external runner or reduced requirements.
+Required-resource inputs are supplied through AKUA_CI_REQUIRED_VCPU, AKUA_CI_REQUIRED_MEMORY_MIB and AKUA_CI_REQUIRED_DISK_MIB.
+
+## Profile guarantees
+
+| Label | Profile | Minimum CPU | Minimum memory | Minimum usable disk | Guaranteed capabilities | Status | Deprecation |
+| --- | --- | ---: | ---: | ---: | --- | --- | --- |
+| `akua-x64-ci-v2` | Standard | 2 vCPU | 4096 MiB | 10240 MiB | ordinary build and test tooling | active | not deprecated |
+| `akua-docker-ci-v2` | Docker | 4 vCPU | 6144 MiB | 15360 MiB | Docker, Buildx, service containers, privileged containers, ordinary build and test tooling | active | not deprecated |
+| `akua-heavy-ci-v2` | Heavy | 4 vCPU | 7168 MiB | 20480 MiB | Docker, Buildx, service containers, privileged containers, ordinary build and test tooling | active | not deprecated |
+
+## `akua-x64-ci-v2`
+
+Recommended uses:
+- linting, formatting, unit tests and ordinary compilation
+- jobs that do not start containers or require large local caches
+
+Exclusions:
+- Docker, Buildx and service containers
+- workloads whose requirements exceed the Standard guarantees
+
+## `akua-docker-ci-v2`
+
+Recommended uses:
+- Docker and Buildx image builds
+- integration tests using Docker or service containers
+
+Exclusions:
+- workloads whose requirements exceed the Docker guarantees; use Heavy only when all Heavy bounds fit
+
+## `akua-heavy-ci-v2`
+
+Recommended uses:
+- memory-heavy compilation, packaging and browser or integration suites that fit the Heavy guarantees
+- Docker jobs whose declared requirements exceed Docker but fit Heavy
+
+Exclusions:
+- workloads requiring more than 4 vCPU, 7168 MiB memory or 20480 MiB usable disk; use an external runner or reduce requirements
+
+## Versioning and deprecation
+
+The public contract version is 2.0.0. Profiles are active and not deprecated unless the structured catalog says otherwise.
+The machine-readable catalogs and provenance manifest are the canonical serialized projections of this document.
+
diff --git a/profile/README.md b/profile/README.md
@@ -29,6 +29,8 @@ software from one workspace.
 - [Docs](https://docs.akua.dev) - learn the platform concepts and workflows.
 - [AI & Agents](https://docs.akua.dev/ai) - connect external AI tools through
   MCP or use hosted agents in the dashboard.
+- [GitHub Actions runner profiles](../RUNNERS.md) - select the stable
+  self-hosted CI label by declared resources and capabilities.
 - [Bring your own cloud](https://docs.akua.dev/platform/byoc) - understand how
   Akua works with infrastructure you own.
 

diff --git a/runner-catalog-manifest.json b/runner-catalog-manifest.json
@@ -0,0 +1,161 @@
+{
+  "manifestVersion": 1,
+  "source": {
+    "repository": "akua-dev/gitops",
+    "path": "clusters/agentos/runner-platform/profiles.yaml",
+    "revision": "59234e828aa544b2079404ffccd12d334567c0ac",
+    "sha256": "00a7ffd62374be2919214455967c06befc4f29c9425b682e07290e5606bca7e5"
+  },
+  "catalog": {
+    "apiVersion": "runners.akua.dev/v1alpha1",
+    "kind": "RunnerProfileCatalog",
+    "metadata": {
+      "name": "akua-ci-catalog",
+      "contractVersion": "2.0.0",
+      "documentation": "https://github.com/akua-dev/.github/blob/main/RUNNERS.md",
+      "provenance": {
+        "repository": "akua-dev/gitops",
+        "path": "clusters/agentos/runner-platform/profiles.yaml",
+        "revision": "59234e828aa544b2079404ffccd12d334567c0ac",
+        "sha256": "00a7ffd62374be2919214455967c06befc4f29c9425b682e07290e5606bca7e5"
+      }
+    },
+    "capacity": {
+      "scope": "organization",
+      "allocation": "shared",
+      "maxConcurrentJobs": 4,
+      "queueSlo": null,
+      "notes": [
+        "Capacity is shared by all three profiles; a profile label does not reserve a private slot.",
+        "Four concurrent jobs are the current safe contract. Six was only a short load experiment."
+      ]
+    },
+    "policy": {
+      "requirementEnvironment": {
+        "cpu": "AKUA_CI_REQUIRED_VCPU",
+        "memoryMiB": "AKUA_CI_REQUIRED_MEMORY_MIB",
+        "diskMiB": "AKUA_CI_REQUIRED_DISK_MIB"
+      },
+      "selection": {
+        "safeMatch": {
+          "resources": "required-at-most-guaranteed-minimum",
+          "capabilities": "required-subset-of-guaranteed"
+        },
+        "order": [
+          "akua-x64-ci-v2",
+          "akua-docker-ci-v2",
+          "akua-heavy-ci-v2"
+        ],
+        "noMatch": "external-runner-or-reduce-requirements"
+      }
+    },
+    "profiles": [
+      {
+        "id": "standard-v2",
+        "label": "akua-x64-ci-v2",
+        "class": "standard",
+        "displayName": "Standard",
+        "status": "active",
+        "minimumResources": {
+          "vcpu": 2,
+          "memoryMiB": 4096,
+          "usableDiskMiB": 10240
+        },
+        "capabilities": {
+          "guaranteed": [
+            "ordinary build and test tooling"
+          ]
+        },
+        "workload": {
+          "recommended": [
+            "linting, formatting, unit tests and ordinary compilation",
+            "jobs that do not start containers or require large local caches"
+          ],
+          "exclusions": [
+            "Docker, Buildx and service containers",
+            "workloads whose requirements exceed the Standard guarantees"
+          ]
+        },
+        "deprecation": {
+          "deprecated": false,
+          "announcedAt": null,
+          "sunsetAt": null,
+          "replacementLabel": null
+        }
+      },
+      {
+        "id": "docker-v2",
+        "label": "akua-docker-ci-v2",
+        "class": "docker",
+        "displayName": "Docker",
+        "status": "active",
+        "minimumResources": {
+          "vcpu": 4,
+          "memoryMiB": 6144,
+          "usableDiskMiB": 15360
+        },
+        "capabilities": {
+          "guaranteed": [
+            "Docker",
+            "Buildx",
+            "service containers",
+            "privileged containers",
+            "ordinary build and test tooling"
+          ]
+        },
+        "workload": {
+          "recommended": [
+            "Docker and Buildx image builds",
+            "integration tests using Docker or service containers"
+          ],
+          "exclusions": [
+            "workloads whose requirements exceed the Docker guarantees; use Heavy only when all Heavy bounds fit"
+          ]
+        },
+        "deprecation": {
+          "deprecated": false,
+          "announcedAt": null,
+          "sunsetAt": null,
+          "replacementLabel": null
+        }
+      },
+      {
+        "id": "heavy-v2",
+        "label": "akua-heavy-ci-v2",
+        "class": "heavy",
+        "displayName": "Heavy",
+        "status": "active",
+        "minimumResources": {
+          "vcpu": 4,
+          "memoryMiB": 7168,
+          "usableDiskMiB": 20480
+        },
+        "capabilities": {
+          "guaranteed": [
+            "Docker",
+            "Buildx",
+            "service containers",
+            "privileged containers",
+            "ordinary build and test tooling"
+          ]
+        },
+        "workload": {
+          "recommended": [
+            "memory-heavy compilation, packaging and browser or integration suites that fit the Heavy guarantees",
+            "Docker jobs whose declared requirements exceed Docker but fit Heavy"
+          ],
+          "exclusions": [
+            "workloads requiring more than 4 vCPU, 7168 MiB memory or 20480 MiB usable disk; use an external runner or reduce requirements"
+          ]
+        },
+        "deprecation": {
+          "deprecated": false,
+          "announcedAt": null,
+          "sunsetAt": null,
+          "replacementLabel": null
+        }
+      }
+    ]
+  }
+}
+