threadlight-cicd

Files (45)

• SKILL.md
• agentops-runtime.md · references/
• azure-pipelines.yml.tmpl · references/azure-devops/
• best-practices.md · references/
• central-platform-boundary.md.tmpl · references/
• 01-uami-federated-credentials.azure-devops.md.tmpl · references/env-setup/
• 01-uami-federated-credentials.azure-devops.sh.tmpl · references/env-setup/
• 01-uami-federated-credentials.github-actions.md.tmpl · references/env-setup/
• 01-uami-federated-credentials.github-actions.sh.tmpl · references/env-setup/
• 02-rbac-role-assignments.md.tmpl · references/env-setup/
• 02-rbac-role-assignments.sh.tmpl · references/env-setup/
• 03-runners-private-vnet.md.tmpl · references/env-setup/
• 03-runners-private-vnet.sh.tmpl · references/env-setup/
• README.md.tmpl · references/env-setup/
• azd-deploy-prod.yml.tmpl · references/github-actions/
• onboarding-path-decision.md · references/
• pipeline-design-checklist.md · references/
• release-contract.md · references/
• agentops_runtime.py · scripts/
• generate_pipeline.py · scripts/
• release_agentops.py · scripts/
• release_runner.py · scripts/
• returns_gateway_operator.py · scripts/
• returns_release.py · scripts/
• native_observer_fixture.py · tests/
• test_agentops_gate.py · tests/
• test_central_boundary.py · tests/
• test_env_runbooks.py · tests/
• test_eval_gate.py · tests/
• test_generate_azuredevops.py · tests/
• test_generate_github.py · tests/
• test_mcp_gate.py · tests/
• test_native_context.py · tests/
• test_native_observer_route.py · tests/
• test_native_release_local.py · tests/
• test_no_secrets_in_templates.py · tests/
• test_onboarding_gate.py · tests/
• test_release_acceptance.py · tests/
• test_release_agentops.py · tests/
• test_release_runner.py · tests/
• test_returns_gateway_operator.py · tests/
• test_returns_release.py · tests/
• test_returns_release_process.py · tests/
• test_verified_pipeline.py · tests/
• test_version.py · tests/

SKILL.md (first lines)

# Threadlight CI/CD — verified release + environment setup

> The skill that answers "**how does this pilot actually deploy to production
> when the agent can't run `azd up` and has no standing rights?**" — by
> validating a separate preproduction candidate, then promoting its immutable
> image through a protected production job. The federated-identity pipeline and
> runbooks define the separation. The customer's platform team configures the
> identity, permissions, and
> runners. Secret-free by construction; parallel-track-safe by design.

## When to use

- The pilot's prod environment is **locked down**: direct writes are restricted,
  deploys must go through a pipeline, and the agent has no deploy rights.
- You need a **GitHub Actions or Azure DevOps** prod-deploy pipeline that logs in
  with **OIDC / Workload Identity Federation** (no `AZURE_CREDENTIALS`, no client
  secret, no PAT).
- The platform team needs **ready-to-run `az` runbooks** for the UAMI, federated
  credentials, least-privilege RBAC, and (for private VNets) the runners.
- You must make the **central-platform boundary** explicit so the pilot pipeline
  never touches the Citadel hub.

**When NOT to use:** deploying the hub itself (`threadlight-citadel-hub`), onboarding a
spoke onto an existing hub (`threadlight-citadel-spoke`), the permissive first-run
deploy (`threadlight-deploy`), or the readiness scorecard
(`threadlight-production-ready`). See the description's DO NOT USE FOR list.

## Onboarding-path decision gate (runs FIRST)

Before generating anything, resolve which track the pilot is on. `resolve_onboarding_path()`
branches on two questions and is the source of truth for posture + RBAC scope:

```
Is a central platform env required?  (Citadel hub / shared AI gateway /
                                      shared networking / platform Key Vault)
│
├─ no  ──────────────────► standalone        (validate target sub/RG, shared-resource
│                                             usage, network exposure FIRST)
│                                             posture: standard-ai-gateway | agt | direct
│                                             RBAC scope: target-rg
│
└─ yes ─► already deployed?
          │
          ├─ yes ─────────► spoke-onboard    (consume hub via Access Contract →
          │                                   threadlight-citadel-spoke)
          │                                   posture: citadel-spoke · RBAC scope: spoke-rg
          │
          └─ no  ─────────► hub-deploy-then-spoke
                                              (stand up hub on the SEPARATE central
                                               track → threadlight-citadel-hub, THEN
                                               threadlight-citadel-spoke)
                                              posture: citadel-spoke · RBAC scope: spoke-rg
```

**Invariant:** a spoke pilot's deploy identity is scoped to the **spoke resource
group only** — never the hub, regardless of whether the hub already exists. The
resolved decision is written to `docs/threadlight-cicd/onboarding-path.json` so
the choice is auditable.

## Parallel-track boundary (the must-tell)

The pilot pipeline is a **separate repo and pipeline** from the central platform.

| Concern | Owner | Track / skill |
|---|---|---|
| Citadel hub, shared APIM AI gateway, shared networking, platform Key Vault | Central platform team | **`threadlight-citadel-hub`** (Threadlight-owned, separate repo) |
| Wire the pilot to consume the hub via an Access Contract | Platform / SE | **`threadlight-citadel-spoke`** |
| Deploy the pilot's **use-case** resources into the spoke/target RG | This pipeline | **`threadlight-cicd`** |

The generated `central-platform-boundary.md` states the pilot pipeline **must not**
deploy or modify the hub, and that its UAMI RBAC is **spoke-RG-scoped only**.

```mermaid
flowchart LR
  subgraph central["Central platform repo (separate)"]
    HUB["threadlight-citadel-hub<br/>hub · shared APIM · networking · KV"]
  end
  subgraph pilot["Pilot repo (this pipeline)"]
    PIPE["threadlight-cicd<br/>azd-deploy-prod → spoke/target RG only"]
  end
  HUB -. "Access Contract<br/>(threadlight-citadel-spoke)" .-> PIPE
  PIPE -. "never writes" .-x HUB
```

## Quick reference

| Goal | Command |
|---|---|
| Interactive onboarding-path gate + generate | `python scripts/generate_pipeline.py --onboard` |
| GitHub Actions, standalone (public) | `python scripts/generate_pipeline.py --platform github-actions --central-env-required no --repo-full-name owner/repo --target-sub <sub> --target-rg <rg> --tenant-id <tid>` |
| Azure DevOps, spoke onto existing hub | `python scripts/generate_pipeline.py --platform azure-devops --central-env-required yes --central-env-exists yes --ado-org <org> --ado-project <proj> --ado-service-connection <sc> --target-sub <sub> --target-rg <rg> --tenant-id <tid> --hub-sub <hsub> --hub-apim-id <apim-id> --access-contract-product <product>` |
| Private-VNet target (self-hosted / managed pool) | add `--private-network` (and `--ado-pool-name <pool>` for ADO) |
| Validation target | add `--validation-env-name`, `--validation-sub`, `--validation-rg` and `--validation-client-id` or `--validation-service-connection` |
| Required release checks | Always blocking; legacy `--eval-gate hard` / `--mcp-gate hard` remain accepted, but soft or invalid modes fail |
| Approved producer/promotion contract | `--release-policy specs/release-policy.json`; see [release contract](references/release-contract.md) |
| Selected two-tool returns reference | `--reference-application returns-mcp/v1`; emits concrete adapter composition and a deliberately incomplete operator configuration |
| Optional AgentOps integration | `--agentops auto` (default; no opt-in means no pipeline change) or `--agentops off` |
| Explicit post-deploy Doctor opt-in | add `--agentops-refresh-doctor`; runtime owner approval and existing application telemetry scope are still required |
| Doctor-only schedule | add `--agentops-refresh-doctor --agentops-doctor-schedule "0 6 * * *"`; never schedules deployment |
| From a saved framing file | `--framing-file framing.json` |
| Run the test suite | `python -m pytest tests/ -v` |

> If `python` resolves to Python 2 on your machine, use `python3` (the generator
> renderer uses Python 3 stdlib; optional AgentOps authoritative service
> discovery uses the shared contract and PyYAML).

**Spoke flags:** `--hub-sub` / `--hub-apim-id` / `--access-contract-product` surface
the hub coordinates the platform team needs to wire the Access Contract; they are
echoed into `central-platform-boundary.md` and the runbooks (never used to deploy
the hub).

## What it emits

Rendered deterministically (offline, no Azure calls, no secrets) into the pilot repo:

- **Pipeline** — `.github/workflows/azd-deploy-prod.yml` or `azure-pipelines.yml`.
  `validation` prepares an isolated candidate, executes configured real
  producers and the supplied MCP checker, then enforces required domains.
  `promotion` depends on that success and uses a different protected

From aiappsgbb/threadlight-skills, MIT.

More from aiappsgbb/threadlight-skills