Slim integrator skills to product rules only.

Drop customer-shaped recipes and reference kits so agents follow README examples instead of one integration.

Author: botirkhaltaev

skills/runner-modal-deploy/SKILL.md

@@ -3,167 +3,44 @@ name: runner-modal-deploy
 description: >-
   Deploys runner-modal GitHub Actions self-hosted runner pools on Modal
   Sandboxes. Use when creating Modal Secrets, writing Runner.create apps,
-  running modal deploy, registering GitHub workflow_job webhooks, tearing
-  down a pool, or setting up Modal CI for a repo. Not for hosted
-  ubuntu-latest runners or generic Modal Apps.
+  running modal deploy, registering GitHub workflow_job webhooks, or
+  tearing down a pool. Not for hosted ubuntu-latest or generic Modal Apps.
 ---
 
 # Deploying runner-modal
 
-Self-hosted GitHub Actions on Modal: one webhook Function per pool, one
-ephemeral Job Sandbox per `workflow_job`. Operator-deployed, not a managed
-service.
+Operator-deployed webhook Function + one Job Sandbox per `workflow_job`.
+Not a managed service. Human DX: `README.md`. Trust: `SECURITY.md`.
 
-Human DX: `README.md`. Trust model: `SECURITY.md`.
-Workflows: `runner-modal-workflows`. Job images: `runner-modal-images`.
-Failures: `runner-modal-troubleshoot`.
+Copy `examples/basic/app.py` (CPU) or `examples/gpu/app.py` (GPU). Do not
+invent a second resource profile on the same App.
 
-Reference integration: [Nordlys-Labs/nordlys `runners/`](https://github.com/Nordlys-Labs/nordlys/tree/main/runners).
+## Rules
 
-## Workflow
-
-Copy and check off:
-
-```
-- [ ] Pin runner-modal
-- [ ] Split Secrets
-- [ ] One App per pool
-- [ ] modal deploy
-- [ ] Webhook per pool
-- [ ] Health check
-```
-
-### 1. Pin runner-modal
-
-Separate uv project (Nordlys keeps this in `runners/`). PyPI is not set up;
-Image builds need `add_local_python_source("runner_modal")` at deploy time.
-
-```toml
-[project]
-name = "my-ci-runners"
-requires-python = ">=3.12"
-dependencies = ["modal>=1.5.2,<2", "runner-modal"]
-
-[tool.uv.sources]
-runner-modal = { git = "https://github.com/modal-projects/runner-modal.git", tag = "v0.1.0" }
-```
-
-```bash
-uv sync
-```
-
-### 2. Split Secrets
-
-Never merge these. Workflow code on a Job can read every mounted env key.
+- Pin with `uv add git+https://github.com/modal-projects/runner-modal.git@v0.1.0`.
+  Deploy from a checkout so Images can `add_local_python_source("runner_modal")`.
+- Two named Secrets, never one: `github-token` (`GITHUB_TOKEN`, Jobs only)
+  and `github-webhook` (`WEBHOOK_SECRET`, webhook Function only).
+- One `Runner.create` per `modal.App` = one resource profile. GPU is a
+  separate App. `repositories` required. Labels must include `self-hosted`.
+- `cpu` / `memory` / `gpu` are Job defaults, not webhook Function size.
+- Do not use a Modal Server for the webhook (503 on zero→one). Inputs queue.
+- Redeploy overwrites Runner meta (last deploy wins).
 
 ```bash
 modal secret create github-token GITHUB_TOKEN=ghp_xxx
 modal secret create github-webhook WEBHOOK_SECRET=$(openssl rand -hex 32)
+modal deploy examples/basic/app.py
 ```
 
-| Secret | Keys | Mounted on |
-|--------|------|------------|
-| `github-token` | `GITHUB_TOKEN` | Job Sandboxes only |
-| `github-webhook` | `WEBHOOK_SECRET` | webhook Function only |
-
-PAT or GitHub App: `POST /repos/{owner}/{repo}/actions/runners/generate-jitconfig`
-on allowlisted repos only (Administration: Read & write).
-
-### 3. One App per pool
-
-One `Runner.create` per `modal.App` = one resource profile. GPU is a
-**separate App**, not a label on the CPU pool. Redeploy overwrites Runner
-meta (last deploy wins).
-
-`repositories` is required and non-empty. `labels` must include `self-hosted`.
-Admission is fail-closed.
-
-Start from `examples/basic/app.py` or `examples/gpu/app.py`:
-
-```python
-import modal
-from runner_modal import Runner
-
-app = modal.App("myorg-ci")
-github = modal.Secret.from_name("github-token", required_keys=["GITHUB_TOKEN"])
-webhook = modal.Secret.from_name("github-webhook", required_keys=["WEBHOOK_SECRET"])
-
-Runner.create(
-    app=app,
-    name="ci",
-    github_secret=github,
-    webhook_secret=webhook,
-    repositories=["YOUR_ORG/YOUR_REPO"],
-    labels=["self-hosted", "modal", "ci"],
-    region="us-east",
-    cpu=2.0,
-    memory=4096,
-    max_concurrent=20,
-    min_containers=0,
-    idle_timeout=900,
-)
-```
-
-`cpu` / `memory` / `gpu` are Job Sandbox defaults. The webhook Function stays
-small (`buffer_containers=1` by default). Do not attach this as a Modal Server
-(503 on zero→one). Inputs queue on the Function.
-
-Nordlys shape: three pools, three Apps (`nordlys-ci`, `nordlys-ci-core`,
-`nordlys-ci-gpu`), same two Secrets.
-
-### 4. Deploy
-
-```bash
-uv run modal deploy cpu_app.py
-```
-
-`url` is `None` until the Function is deployed.
-
-### 5. Webhook per pool
-
-```python
-from runner_modal import Runner
-print(Runner.from_name("ci").url)  # …/webhook → payload is {url}/github
-```
-
-| Field | Value |
-|-------|--------|
-| Payload URL | `{url}/github` |
-| Content type | `application/json` |
-| Secret | same as `WEBHOOK_SECRET` |
-| Events | **Workflow jobs** only |
-
-One webhook per pool. Same secret is fine.
-
-### 6. Health
+Webhook: `{Runner.from_name("ci").url}/github`, `application/json`,
+**Workflow jobs** only, same `WEBHOOK_SECRET`. One webhook per pool.
 
 ```bash
 curl -sS "$URL/health"
 ```
 
-Returns `runner`, `labels`, `repositories` (count), `active_runners`,
-`max_concurrent`. `GET /health` is public.
-
-## Ops
-
-| Task | Command |
-|------|---------|
-| Logs (webhook Function) | `modal app logs <app-name>` |
-| Teardown pool state | `uv run python -c "from runner_modal import Runner; Runner.objects.delete('ci')"` |
-| Stop App | `modal app stop <app-name>` then remove the repo webhook |
-
-`Runner.objects.delete` removes `{name}-runner-meta`, `{name}-runner-deliveries`,
-and `{name}-cache`. GitHub runner rows are ephemeral (JIT); they appear only
-while a Job runs.
-
-## Cost knobs
-
-Per pool: `cpu` / `memory` / `gpu`, soft `max_concurrent` (list-then-create,
-not a lock), `idle_timeout` (Job linger), `min_containers` / `buffer_containers`
-(webhook warm pool; keep at `0` / `1`).
-
-## Public-repo forks
+Teardown: `Runner.objects.delete(name)`, then `modal app stop` and remove
+the GitHub webhook. JIT runner rows exist only while a Job runs.
 
-Self-hosted Jobs run workflow code with `GITHUB_TOKEN` in the Sandbox. Prefer
-approval for outside collaborators and read-only default workflow permissions.
-See `SECURITY.md`.
+`max_concurrent` is soft (list-then-create), not a lock.

skills/runner-modal-images/SKILL.md

@@ -1,134 +1,26 @@
 ---
 name: runner-modal-images
 description: >-
-  Customizes runner-modal Job images on Modal (Named Image {name}-job,
-  GPU pools, Docker VM runtime, shared /cache Volume). Use when rebuilding
-  the Actions runner recipe, publishing over ci-job, adding gcc/cmake/CUDA,
-  enabling cache=True, or setting experimental_options vm_runtime. Not for
-  generic Modal Image tutorials or webhook Function sizing.
+  Customizes runner-modal Job images (Named Image {name}-job, GPU, Docker
+  VM, /cache). Use when changing the Job recipe, enabling cache=True, or
+  setting vm_runtime. Not for generic Modal Image tutorials.
 ---
 
 # Customizing runner-modal Job images
 
-Webhook `Job.create` loads the published Named Image `{name}-job`.
-`Runner.create(image=)` is the **webhook Function** image
-(`control_plane_image()`), not the Job image.
+Jobs load the published Named Image `{name}-job`.
+`Runner.create(image=)` is the **webhook Function** image only.
 
-Recipes: [references/image-recipes.md](references/image-recipes.md).
-Deploy first: `runner-modal-deploy`. Workflows: `runner-modal-workflows`.
+## Rules
 
-Worked example: [Nordlys `runners/core_app.py`](https://github.com/Nordlys-Labs/nordlys/blob/main/runners/core_app.py)
-(Ubuntu 24.04 + gcc 13, publish over `ci_core-job`, `cache=True`).
+- Default CPU: `Runner.create` publishes `default_image()` as `{name}-job`.
+- GPU: separate App, `gpu=` on `Runner.create`. See `examples/gpu/app.py`.
+- Docker-in-CI: `experimental_options={"vm_runtime": True}` (no GPU).
+- Custom toolchain: build with `Runner.install_actions_runner`, then
+  `.publish(f"{name}-job")` **after** `Runner.create`. Last publish wins.
+  Keep `JOB_DEPS`, `add_local_python_source("runner_modal", copy=True)`,
+  and `RUNNER_ALLOW_RUNASROOT=1`. No `Path` / `add_local_dir`.
+- `cache=True` mounts `{name}-cache` at `/cache` for every Job in that
+  pool. Same-pool only. Default is `cache=False`.
 
-## Choose a path
-
-| Need | Do |
-|------|-----|
-| Default CPU CI | `Runner.create` only. Publishes `{name}-job` from `default_image()` (Debian slim + Actions runner) |
-| CUDA / ML | Separate pool. `gpu="T4"` (or other) on `Runner.create`. Default Job image is enough if CUDA comes from pip wheels |
-| Docker-in-CI | `experimental_options={"vm_runtime": True}` — **no GPU**. Library publishes `docker_image()` |
-| Different distro / gcc / cmake | Rebuild with `install_actions_runner`, then publish over `{name}-job` **after** `Runner.create` (last publish wins) |
-| Shared compile cache | `cache=True` → Volume at `/cache`, same-pool only |
-
-Do not invent `ResourceSpec` / `DockerResources`. Flat kwargs: `cpu`,
-`memory`, `gpu`, `experimental_options`. Modal enforces GPU vs VM limits.
-
-## Default publish
-
-`Runner.create` builds `default_image()` (or `docker_image()` when
-`vm_runtime`) and publishes it as `{name}-job`. Webhook Jobs use
-`Image.from_name`. Every deploy republishes the default recipe first.
-
-## Custom Job image
-
-Mirror the library recipe, then overwrite the Named Image. `add_local_python_source("runner_modal", copy=True)` is required until PyPI.
-
-```python
-import modal
-from runner_modal import Runner
-from runner_modal.meta import JOB_DEPS
-
-APP_NAME = "myorg-ci-core"
-RUNNER_NAME = "ci_core"
-
-app = modal.App(APP_NAME)
-github = modal.Secret.from_name("github-token", required_keys=["GITHUB_TOKEN"])
-webhook = modal.Secret.from_name("github-webhook", required_keys=["WEBHOOK_SECRET"])
-
-core_job_image = Runner.install_actions_runner(
-    modal.Image.from_registry("ubuntu:24.04", add_python="3.12")
-    .apt_install(
-        "curl", "ca-certificates", "git", "libicu-dev",
-        "liblttng-ust1t64", "libssl3t64", "tar", "unzip", "zip",
-        "build-essential", "gcc-13", "g++-13", "ninja-build", "pkg-config",
-    )
-    .uv_pip_install(*JOB_DEPS)
-    .uv_pip_install("cmake>=3.28", "conan>=2")
-    .add_local_python_source("runner_modal", copy=True)
-    .env({"RUNNER_ALLOW_RUNASROOT": "1", "CC": "gcc-13", "CXX": "g++-13"})
-)
-
-Runner.create(
-    app=app,
-    name=RUNNER_NAME,
-    github_secret=github,
-    webhook_secret=webhook,
-    repositories=["YOUR_ORG/YOUR_REPO"],
-    labels=["self-hosted", "modal", "ci-core"],
-    cpu=4.0,
-    memory=8192,
-    cache=True,
-    min_containers=0,
-    idle_timeout=900,
-)
-
-build_app = modal.App.lookup(APP_NAME, create_if_missing=True)
-core_job_image.build(build_app).publish(f"{RUNNER_NAME}-job")
-```
-
-Order: `Runner.create` (publishes stock `{name}-job`) → custom
-`.publish(f"{name}-job")`. Last publish wins. Redeploy both steps.
-
-No `Path` / `add_local_dir`. Use uv Image methods.
-
-## GPU pool
-
-Separate App. Host driver comes from Modal; CUDA userspace from wheels is
-fine on the default Job image.
-
-```python
-Runner.create(
-    app=app,
-    name="ci_gpu",
-    github_secret=github,
-    webhook_secret=webhook,
-    repositories=["YOUR_ORG/YOUR_REPO"],
-    labels=["self-hosted", "modal", "ci-gpu"],
-    gpu="T4",
-    cpu=4.0,
-    memory=16384,
-    max_concurrent=2,
-    min_containers=0,
-    idle_timeout=900,
-)
-```
-
-See `examples/gpu/app.py`.
-
-## Docker-in-CI
-
-```python
-Runner.create(
-    …,
-    experimental_options={"vm_runtime": True},
-    # no gpu=
-)
-```
-
-## `/cache`
-
-`cache=True` creates `{name}-cache` and mounts it at `/cache` for every Job
-in that pool. Same-pool Jobs can read/write each other’s files. Default is
-`cache=False`. This is not GitHub `actions/cache`.
-
-Workflows must point tools at `/cache` (`runner-modal-workflows`).
+Point tools at `/cache` in the workflow when you enable it.