Add Repo Radius feature specification

[zachcasper]

This pull request introduces a comprehensive feature specification document for "Repo Radius," detailing a new approach to delivering Radius as a lightweight, on-demand engine that runs within GitHub Actions, removing the need for a pre-configured Kubernetes cluster. The document outlines goals, user personas, scenarios, dependencies, risks, and required investments for implementing Repo Radius, making Radius more accessible to developers without platform engineering resources.

Repo Radius Feature Specification:

Overview and Motivation:

• Proposes transforming Radius from a persistent control plane requiring Kubernetes expertise into an ephemeral, on-demand service running inside GitHub Actions, with state stored in GitHub-native storage. This aims to lower the barrier to entry for developers and enable a "try-before-you-buy" experience.

Key Scenarios and User Experience:

• Describes end-to-end developer workflows, including deploying applications, setting up environments, authorizing cloud access via OIDC, resuming deployments, and migrating to a self-hosted Radius.
• Details how the UX component interacts with Repo Radius through GitHub APIs, including environment setup, OIDC configuration, workflow dispatch, execution, and output handling.

Technical Implementation and Dependencies:

• Outlines technical requirements such as supporting deployment to external Kubernetes clusters, externalizing the Radius data store, integrating with cloud provider credentials via OIDC, and supporting a customizable Terraform backend. (F232f160# Description

Type of change

• This pull request is a design document and only includes files in the eng/design-notes directory.

Contributor checklist

Please verify that the PR meets the following requirements, where applicable:

• An overview of proposed schema changes is included in a linked GitHub issue.
  • Yes
  • Not applicable
• A design document is added or updated under eng/design-notes/ in this repository, if new APIs are being introduced.
  • Yes
  • Not applicable
• The design document has been reviewed and approved by Radius maintainers/approvers.
  • Yes
  • Not applicable
• A PR for resource-types-contrib is created, if resource types or recipes are affected by the changes in this PR.
  • Yes
  • Not applicable
• A PR for dashboard is created, if the Radius Dashboard is affected by the changes in this PR.
  • Yes
  • Not applicable
• A PR for the documentation repository is created, if the changes in this PR affect the documentation or any user facing updates are made.
  • Yes
  • Not applicable

[Copilot]

Pull request overview

Adds a new design note / feature specification for “Repo Radius”, describing a proposed delivery model where Radius runs ephemerally inside GitHub Actions with state persisted in GitHub-native storage, to reduce the Kubernetes/platform-engineering setup burden for developers.

Changes:

• Introduces a comprehensive feature specification covering goals, non-goals, personas, scenarios, dependencies/risks, and open questions.
• Documents the intended end-to-end UX interaction model via GitHub APIs (environments, OIDC auth, workflow dispatch/execution, artifact-based outputs).
• Summarizes key technical investments required (external cluster deployment, externalized state store, standardized workflow contract, credential integration).

[sylvainsf]

The consolidation to a single run-rad-commands action plus the combined rad-commands-result artifact and the allowed-command enum all look right to me — this is a clean contract. Two small, additive suggestions, both keeping product mechanism out of the spec:

1. Offer a canonical rad-commands-result schema

Since the combined artifact is now the contract, it helps frontends to pin its shape. Here's a concrete example for the canonical case — a rad deploy followed by rad app graph -o json (both in the allowed-command enum):

{
  "schemaVersion": "1.0",
  "outcome": "succeeded",
  "exitCode": 0,
  "environment": "production",
  "commandsRequested": 2,
  "commandsRan": 2,
  "message": "All 2 commands succeeded.",
  "commands": [
    {
      "index": 0,
      "command": "deploy .radius/app.bicep",
      "outcome": "succeeded",
      "exitCode": 0,
      "stdout": "Building .radius/app.bicep...\nDeployment Complete\n\nResources:\n  todo-list   Applications.Core/applications\n  frontend    Applications.Core/containers\n  db          Applications.Datastores/sqlDatabases",
      "stderr": "",
      "errorMessage": null
    },
    {
      "index": 1,
      "command": "app graph my-app -o json",
      "outcome": "succeeded",
      "exitCode": 0,
      "stdout": "{\"resources\":[ ... ]}",
      "stderr": "",
      "errorMessage": null
    }
  ]
}

Notes on the shape:

• Top-level outcome + exitCode mirror your outcome table (succeeded / command_failed / disallowed_command), so the run conclusion and the artifact agree.
• commands[] is in input order with a stable index, which is what makes the combined artifact better than per-command files (your Alternatives section).
• A failed run keeps the same shape: the failed entry carries its exitCode/errorMessage and entries for commands that did not run are absent — exactly as the deploy-scenario outcomes describe.
• schemaVersion lets the JSON schema version independently within a major action version, per your versioning section.

If useful I can turn this into the canonical example block in the spec (or a referenced schema file), with the field set you prefer.

2. "Deferred to the technical design" pointers for Investments 1 and 5

You already do this well for the allowed-command set ("defined in the technical design"). Two more places where the same one-line deferral would keep the product spec clean while signaling the work exists:

• Investment 1 — a sentence that the mechanism by which Radius acquires Kubernetes API access for the named cluster (eksClusterName / aksClusterName) is defined in the technical design. (Implementation: the technical design covers the cloud-derived in-process acquisition and the interim it replaces.)
• Investment 5 — a sentence that the control-plane startup approach (action packaging and control-plane image baking) is defined in the technical design.

No mechanism specifics needed in the spec itself — just the pointer, matching the allowed-command pattern. The corresponding detail lives in the deploy-workflow technical design.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (2)

eng/design-notes/github/2026-06-repo-radius.md:488

• Grammar: “the second commands failed” should be singular (“the second command failed”).

Below is an example run-rad-commands-result artifact from the prototype. This example shows the workflow being run with three commands: rad resource list -o json, rad app show todo-list -o json, and rad app graph todo-list -o json. Note that the second commands failed and the third did not execute.

eng/design-notes/github/2026-06-repo-radius.md:512

• The example result artifact uses legacy Applications.Core/containers resource types/IDs. This doc otherwise describes the modern Radius.Core/Radius.Compute model; updating the example avoids confusion for readers and keeps it consistent with current resource type names.

      "stdout": "[{\"id\":\"/planes/radius/local/resourceGroups/default/providers/Applications.Core/containers/frontend\",\"name\":\"frontend\",\"type\":\"Applications.Core/containers\"}]",

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (3)

eng/design-notes/github/2026-06-repo-radius.md:480

• The command examples are inconsistent with the rad_commands input described earlier (which omits the rad prefix), and there is a grammar issue (“second commands”). Consider listing subcommands consistently as they would appear in the rad_commands array.

Below is an example run-rad-commands-result artifact from the prototype. This example shows the workflow being run with three commands: rad resource list -o json, rad app show todo-list -o json, and rad app graph todo-list -o json. Note that the second commands failed and the third did not execute.

eng/design-notes/github/2026-06-repo-radius.md:504

• The example artifact output uses legacy Applications.Core/containers identifiers. Elsewhere in the repo (e.g., built-in providers manifest) the container resource type is Radius.Compute/containers; updating the example avoids confusion about which type Repo Radius is expected to use going forward.

      "stdout": "[{\"id\":\"/planes/radius/local/resourceGroups/default/providers/Applications.Core/containers/frontend\",\"name\":\"frontend\",\"type\":\"Applications.Core/containers\"}]",

eng/design-notes/github/2026-06-repo-radius.md:196

• This section says the app is modeled in app.bicep, but the rad_commands example uses deploy .radius/app.bicep. Please make the spec consistent about the expected location/name of the app definition file, since that affects how the action checks out and runs deployments.

With the application already modeled in `app.bicep`, the developer asks the frontend to deploy it. Repo Radius runs on demand inside a GitHub Actions runner, provisions the resources defined in `app.bicep` and shuts down. The developer never installs or configures Radius or learns each provider's resource types and arguments.

This is the same standard deployment Radius performs today; Repo Radius does not change how Radius deploys applications. The only potential change to core Radius is adjusting the output of the `rad deploy` command so the frontend can collect incremental deployment progress updates.

#### User Experience

The developer asks the frontend to deploy an application:

1. **Request the deployment.** The developer asks for the application to be deployed, selecting the environment by name. For example, the developer requests the storefront application to be deployed to the `dev` environment.

2. **Preview what will be created.** Before anything is provisioned, the frontend shows the cloud resources that will be created and asks the developer for confirmation. For example, since the `dev` environment is configured to deploy to Azure, the frontend shows the developer:

    | Application resource       | Cloud resource                                  |
    | -------------------------- | ----------------------------------------------- |
    | `frontend` container       | Kubernetes service, deployment, service account |
    | `api` container            | Kubernetes service, deployment, service account |
    | `orders-db` database       | Azure Database for PostgreSQL Flexible Server   |
    | `cache` Redis cache        | Azure Cache for Redis                           |
    | `orders-queue` Kafka queue | Azure Event Hubs                                |

    It is the frontend's responsibility to examine the application's resources and their recipes to produce this initial deployment plan; previewing changes to an already-deployed application is covered in User Story 2.2.

3. **Watch the deployment progress.** As the deployment runs, the frontend shows the status of each individual cloud resource. The developer sees the Azure Database for PostgreSQL Flexible Server move from pending to provisioning to succeeded (or failed), so progress is visible resource by resource rather than as a single opaque step.

4. **See each resource's identity.** When the deployment completes, the frontend shows the cloud provider resource ID for each provisioned resource. For the storefront's database, this is the Azure resource ID of the Flexible Server, for example `/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/storefront-dev/providers/Microsoft.DBforPostgreSQL/flexibleServers/storefront-orders-db`.

#### Result

The frontend deploys the application by dispatching the `radius-run-rad-commands.yml` workflow passing in the target environment name and the `rad deploy` command.

| Input | Value |
| --- | --- |
| `environment` | The GitHub Environment name |
| `ref` | The git commit or tag to deploy (defaults to the latest commit on the default branch). Not used in this user story but is used in User Story 3.1. |
| `rad_commands` | `['deploy .radius/app.bicep', 'app graph storefront -o json']` |