@codyswann/lisa 2.198.1 → 2.199.0

package/cdk/create-only/.github/workflows/deploy.yml

@@ -1,5 +1,4 @@
-# This file is managed by Lisa.
-# Do not edit directly — changes will be overwritten on the next `lisa` run.
+# This file is created by Lisa (create-only — edit freely, Lisa won't overwrite it).
 
 name: 🚀 Release and Deploy
 
@@ -30,7 +29,11 @@ jobs:
     timeout-minutes: 5
     outputs:
       environment: ${{ steps.env.outputs.environment }}
+      approval_environment: ${{ steps.approval.outputs.approval_environment }}
+      require_approval: ${{ steps.approval.outputs.require_approval }}
     steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v6
       - name: 🔄 Set environment
         id: env
         run: |
@@ -39,6 +42,26 @@ jobs:
           else
             echo "environment=${{ github.ref_name }}" >> $GITHUB_OUTPUT
           fi
+      - name: 🚦 Resolve approval gate from .lisa.config.json
+        id: approval
+        run: |
+          BRANCH="${{ steps.env.outputs.environment }}"
+          CONFIG=".lisa.config.json"
+          APPROVAL_ENV="$BRANCH"
+          REQUIRE="false"
+          if [ -f "$CONFIG" ] && jq empty "$CONFIG" 2>/dev/null; then
+            # Friendly environment name for the branch: an explicit
+            # github.environments[].branch match wins, then the
+            # deploy.branches map, then the branch name itself.
+            NAME=$(jq -r --arg b "$BRANCH" '[.github.environments // {} | to_entries[] | select(.value.branch == $b) | .key] | first // empty' "$CONFIG")
+            if [ -z "$NAME" ]; then
+              NAME=$(jq -r --arg b "$BRANCH" '[.deploy.branches // {} | to_entries[] | select(.value == $b) | .key] | first // empty' "$CONFIG")
+            fi
+            APPROVAL_ENV="${NAME:-$BRANCH}"
+            REQUIRE=$(jq -r --arg e "$APPROVAL_ENV" '.github.environments[$e].require_approval // false' "$CONFIG")
+          fi
+          echo "approval_environment=$APPROVAL_ENV" >> $GITHUB_OUTPUT
+          echo "require_approval=$REQUIRE" >> $GITHUB_OUTPUT
 
   release:
     name: 📦 Release
@@ -49,7 +72,8 @@ jobs:
       environment: ${{ needs.determine_environment.outputs.environment }}
       release_strategy: 'standard-version'
       skip_jobs: 'test:e2e,test:integration'
-      require_approval: false
+      require_approval: ${{ needs.determine_environment.outputs.require_approval == 'true' }}
+      approval_environment: ${{ needs.determine_environment.outputs.approval_environment }}
       require_signatures: false
       generate_sbom: true
       override_blackout: true

package/expo/create-only/.github/workflows/deploy.yml

@@ -1,5 +1,4 @@
-# This file is managed by Lisa.
-# Do not edit directly — changes will be overwritten on the next `lisa` run.
+# This file is created by Lisa (create-only — edit freely, Lisa won't overwrite it).
 
 # This is an example deployment workflow that demonstrates the recommended pattern:
 # 1. Call the release.yml workflow to create a release
@@ -50,7 +49,11 @@ jobs:
     timeout-minutes: 5
     outputs:
       environment: ${{ steps.env.outputs.environment }}
+      approval_environment: ${{ steps.approval.outputs.approval_environment }}
+      require_approval: ${{ steps.approval.outputs.require_approval }}
     steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v6
       - name: 🔄 Set environment
         id: env
         run: |
@@ -59,6 +62,26 @@ jobs:
           else
             echo "environment=${{ github.ref_name }}" >> $GITHUB_OUTPUT
           fi
+      - name: 🚦 Resolve approval gate from .lisa.config.json
+        id: approval
+        run: |
+          BRANCH="${{ steps.env.outputs.environment }}"
+          CONFIG=".lisa.config.json"
+          APPROVAL_ENV="$BRANCH"
+          REQUIRE="false"
+          if [ -f "$CONFIG" ] && jq empty "$CONFIG" 2>/dev/null; then
+            # Friendly environment name for the branch: an explicit
+            # github.environments[].branch match wins, then the
+            # deploy.branches map, then the branch name itself.
+            NAME=$(jq -r --arg b "$BRANCH" '[.github.environments // {} | to_entries[] | select(.value.branch == $b) | .key] | first // empty' "$CONFIG")
+            if [ -z "$NAME" ]; then
+              NAME=$(jq -r --arg b "$BRANCH" '[.deploy.branches // {} | to_entries[] | select(.value == $b) | .key] | first // empty' "$CONFIG")
+            fi
+            APPROVAL_ENV="${NAME:-$BRANCH}"
+            REQUIRE=$(jq -r --arg e "$APPROVAL_ENV" '.github.environments[$e].require_approval // false' "$CONFIG")
+          fi
+          echo "approval_environment=$APPROVAL_ENV" >> $GITHUB_OUTPUT
+          echo "require_approval=$REQUIRE" >> $GITHUB_OUTPUT
 
   release:
     name: 📦 Release
@@ -69,7 +92,8 @@ jobs:
       environment: ${{ needs.determine_environment.outputs.environment }}
       release_strategy: 'standard-version'
       skip_jobs: 'test:e2e,test:unit,test:integration'
-      require_approval: false
+      require_approval: ${{ needs.determine_environment.outputs.require_approval == 'true' }}
+      approval_environment: ${{ needs.determine_environment.outputs.approval_environment }}
       require_signatures: false
       generate_sbom: true
       node_version: '22.21.1'

package/nestjs/create-only/.github/workflows/deploy.yml

@@ -42,7 +42,11 @@ jobs:
     timeout-minutes: 5
     outputs:
       environment: ${{ steps.env.outputs.environment }}
+      approval_environment: ${{ steps.approval.outputs.approval_environment }}
+      require_approval: ${{ steps.approval.outputs.require_approval }}
     steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v6
       - name: 🔄 Set environment
         id: env
         run: |
@@ -51,6 +55,26 @@ jobs:
           else
             echo "environment=${{ github.ref_name }}" >> $GITHUB_OUTPUT
           fi
+      - name: 🚦 Resolve approval gate from .lisa.config.json
+        id: approval
+        run: |
+          BRANCH="${{ steps.env.outputs.environment }}"
+          CONFIG=".lisa.config.json"
+          APPROVAL_ENV="$BRANCH"
+          REQUIRE="false"
+          if [ -f "$CONFIG" ] && jq empty "$CONFIG" 2>/dev/null; then
+            # Friendly environment name for the branch: an explicit
+            # github.environments[].branch match wins, then the
+            # deploy.branches map, then the branch name itself.
+            NAME=$(jq -r --arg b "$BRANCH" '[.github.environments // {} | to_entries[] | select(.value.branch == $b) | .key] | first // empty' "$CONFIG")
+            if [ -z "$NAME" ]; then
+              NAME=$(jq -r --arg b "$BRANCH" '[.deploy.branches // {} | to_entries[] | select(.value == $b) | .key] | first // empty' "$CONFIG")
+            fi
+            APPROVAL_ENV="${NAME:-$BRANCH}"
+            REQUIRE=$(jq -r --arg e "$APPROVAL_ENV" '.github.environments[$e].require_approval // false' "$CONFIG")
+          fi
+          echo "approval_environment=$APPROVAL_ENV" >> $GITHUB_OUTPUT
+          echo "require_approval=$REQUIRE" >> $GITHUB_OUTPUT
 
   # Step 1: Create a release
   release:
@@ -61,11 +85,10 @@ jobs:
       environment: ${{ needs.determine_environment.outputs.environment }}
       release_strategy: 'standard-version'
       skip_jobs: 'test:e2e,test:unit,test:integration,test'
-      # require_approval: ${{ needs.determine_environment.outputs.environment == 'main' }}
-      # require_signatures: ${{ needs.determine_environment.outputs.environment == 'main' }}
       generate_sbom: true
       override_blackout: true
-      require_approval: false
+      require_approval: ${{ needs.determine_environment.outputs.require_approval == 'true' }}
+      approval_environment: ${{ needs.determine_environment.outputs.approval_environment }}
       require_signatures: false
       node_version: '22.21.1'
       package_manager: 'bun'

package/package.json

@@ -94,7 +94,7 @@
     "ws": ">=8.20.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-setup-github-repo/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lisa-setup-github-repo
 description: "Apply Lisa's GitHub repository…"
-allowed-tools: ["Bash", "Read", "AskUserQuestion"]
+allowed-tools: ["Bash", "Read", "Edit", "AskUserQuestion"]
 ---
 
 # Setup GitHub Repository Governance
@@ -29,6 +29,28 @@ Apply the fleet-standard GitHub repository configuration to this project's repo.
    - `prevent delete`, `protect tags` (`v*`), plus stack overlays (`cdk validation`, staging-only `playwright`)
    - Repos without `.github/workflows/` get only app-based required checks — an Actions check that can never report would block every PR forever
 3. **Deploy key** (`scripts/setup-deploy-key.sh --yes`) — write-access deploy key + `DEPLOY_KEY` secret, skipped when already configured. The `base` ruleset's `DeployKey: always` bypass is what lets CI version-bump pushes through protected branches.
+4. **Deployment environments** (`scripts/lisa-github-environments.sh`) — entirely optional; only runs when `.lisa.config.json` declares environments:
+   ```json
+   {
+     "github": {
+       "environments": {
+         "production": {
+           "branch": "main",
+           "require_approval": true,
+           "reviewers": ["some-user", "some-org/some-team"],
+           "prevent_self_review": false,
+           "wait_timer": 0
+         },
+         "staging": { "branch": "staging" }
+       }
+     }
+   }
+   ```
+   - Environment names are friendly names (`production`), mapped to branches. Branch resolution order: explicit `branch` → `deploy.branches[<name>]` → the name itself.
+   - `require_approval: true` provisions **required reviewers** (usernames or `org/team-slug`, max 6) — GitHub pauses any workflow job bound to the environment until a listed reviewer approves it in the Actions UI. Reviewers are mandatory when `require_approval` is true; the script refuses a gate nobody can approve.
+   - Every declared environment also gets a **deployment branch policy** pinned to its branch, so only that branch can deploy to it.
+   - Provisioning matters: GitHub silently auto-creates an environment **without** protection rules the first time a workflow references it, so an unprovisioned approval gate gates on nothing.
+   - The stack `deploy.yml` templates read this same config at runtime and pass `require_approval`/`approval_environment` to `release.yml`, whose `release_approval` job is where the run pauses. Requires a public repo or a paid plan for private repos (the script skips gracefully otherwise).
 
 ## Workflow
 
@@ -56,7 +78,31 @@ bash "$LISA_SCRIPTS/lisa-github-repo-setup.sh" .
 
 Requires `gh` authenticated with **admin** permission on the repo. A 403 on rulesets means the plan doesn't support them (private repo on a free personal plan) — settings and deploy key still apply; the script skips rulesets gracefully.
 
-### Step 4 — Verify
+### Step 4 — Wire the approval gate into an existing deploy.yml (guided edit)
+
+Only when `.lisa.config.json` has a `github.environments` entry with `require_approval: true` AND `.github/workflows/deploy.yml` exists but does not reference `approval_environment`:
+
+```bash
+[ -f .github/workflows/deploy.yml ] \
+  && jq -e '[.github.environments // {} | .[] | select(.require_approval == true)] | length > 0' .lisa.config.json > /dev/null 2>&1 \
+  && ! grep -q 'approval_environment' .github/workflows/deploy.yml \
+  && echo "deploy.yml needs approval wiring"
+```
+
+A `grep` hit is only a first pass — before skipping the edit, read the `release` job's `with:` block and confirm it actually passes both `require_approval` and `approval_environment` from the `determine_environment` outputs (a commented-out or unrelated occurrence doesn't count as wired).
+
+`deploy.yml` is create-only — the project owns it, so Lisa never patches it automatically. Show the user the two changes from the current stack template (`<stack>/create-only/.github/workflows/deploy.yml` in the Lisa repo) and offer to apply them via Edit:
+
+1. In `determine_environment`, add a checkout step plus the `🚦 Resolve approval gate from .lisa.config.json` step, and expose the `approval_environment` / `require_approval` outputs.
+2. In the `release` job's `with:` block, replace `require_approval: false` with:
+   ```yaml
+   require_approval: ${{ needs.determine_environment.outputs.require_approval == 'true' }}
+   approval_environment: ${{ needs.determine_environment.outputs.approval_environment }}
+   ```
+
+Skip this step (and say why) if the project's deploy.yml doesn't call Lisa's `release.yml` (rails uses `release-rails.yml` and harper-fabric has no release call — approval gating for those stacks is not wired yet).
+
+### Step 5 — Verify
 
 ```bash
 gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
@@ -64,4 +110,13 @@ gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
 gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/rulesets" --jq '[.[].name]'
 ```
 
-Report the applied settings and ruleset names. If any step failed, surface the error — do not mark the setup complete.
+When environments were configured, also confirm each one carries its protection rules and branch policy:
+
+```bash
+gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/environments" \
+  --jq '.environments[] | {name, protection_rules, deployment_branch_policy}'
+```
+
+For every environment declared in `github.environments`, treat a missing `deployment_branch_policy` — or, when `require_approval` is true, an empty `protection_rules` — as a failure: the environment exists but is unprotected, so an approval gate bound to it would block nothing.
+
+Report the applied settings, ruleset names, and environments. If any step failed, surface the error — do not mark the setup complete.

package/plugins/lisa/commands/lisa/setup/github-repo.md

@@ -1,5 +1,5 @@
 ---
-description: "Apply Lisa's GitHub repository governance baseline: merge-only settings with auto-merge and delete-branch-on-merge, branch + tag rulesets (CodeRabbit/GitGuardian/Quality Checks gates, prevent delete, protect tags), and a CI deploy key + DEPLOY_KEY secret. Idempotent; per-repo overrides via .lisa.config.json github.settings."
+description: "Apply Lisa's GitHub repository governance baseline: merge-only settings with auto-merge and delete-branch-on-merge, branch + tag rulesets (CodeRabbit/GitGuardian/Quality Checks gates, prevent delete, protect tags), a CI deploy key + DEPLOY_KEY secret, and optional deployment environments with human-approval gates from .lisa.config.json github.environments. Idempotent; per-repo overrides via .lisa.config.json github.settings."
 allowed-tools: ["Skill"]
 argument-hint: ""
 ---

package/plugins/lisa/rules/reference/config-resolution.md

@@ -274,6 +274,12 @@ Each vendor section is **conditionally required**: required only when that vendo
 | `github.projects.v2.owner.slug` | GitHub Project coordination is enabled | Owner login for the shared ProjectV2. In v1 it MUST match the tracked repository namespace (`github.org`); cross-namespace coordination is rejected. |
 | `github.projects.v2.number` | GitHub Project coordination is enabled | Human-facing ProjectV2 number from the GitHub UI / URL. Later utilities resolve the opaque node id from this owner + number pair. |
 | `github.projects.v2.required` | no | Coordination strictness flag. Default `false` keeps Project membership best-effort; `true` makes Project membership failures block the write. Setup/doctor/runtime validation reads Project ownership + access and branches on this flag: best-effort failures warn, required-mode failures stop the write. |
+| `github.environments` | no | Optional map of friendly environment name → deployment-environment declaration, provisioned by `/lisa:setup:github-repo` (`scripts/lisa-github-environments.sh`). Absent → no environments are touched. Each declared environment gets a deployment branch policy pinned to its branch. |
+| `github.environments.<name>.branch` | no | Branch that deploys to this environment. Resolution order: this field → `deploy.branches[<name>]` → the environment name itself. |
+| `github.environments.<name>.require_approval` | no | Default `false`. `true` provisions required reviewers on the environment and makes the stack `deploy.yml` templates pass `require_approval`/`approval_environment` to `release.yml`, pausing the run at the `release_approval` job until a reviewer approves. |
+| `github.environments.<name>.reviewers` | `require_approval = true` | Array of GitHub usernames or `org/team-slug` entries (max 6) allowed to approve deployments. Mandatory with `require_approval` — an approval gate nobody can approve is refused at provision time. |
+| `github.environments.<name>.prevent_self_review` | no | Default `false`. `true` stops the person who triggered the deployment from approving it themselves. |
+| `github.environments.<name>.wait_timer` | no | Default `0`. Minutes to delay the deployment after approval. |
 
 When `tracker = "github"` AND `source = "github"` (self-host), both reads and writes hit the same GitHub repo. Label namespaces are kept separate so the two flows don't collide — see "Self-host edge case" below.
 

package/plugins/lisa/skills/lisa-setup-github-repo/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lisa-setup-github-repo
-description: "Apply Lisa's GitHub repository governance baseline to the current project's repo: repository settings (merge-only, auto-merge, delete-branch-on-merge, update-branch suggestions, wiki off, secret scanning where available), branch + tag rulesets from Lisa templates (base PR gate with CodeRabbit/GitGuardian/Quality Checks, prevent delete, protect tags, stack overlays), and a write-access deploy key + DEPLOY_KEY secret so release workflows can push version bumps through the rulesets' DeployKey bypass. Idempotent — re-running updates settings and rulesets in place and skips an already-configured deploy key."
-allowed-tools: ["Bash", "Read", "AskUserQuestion"]
+description: "Apply Lisa's GitHub repository governance baseline to the current project's repo: repository settings (merge-only, auto-merge, delete-branch-on-merge, update-branch suggestions, wiki off, secret scanning where available), branch + tag rulesets from Lisa templates (base PR gate with CodeRabbit/GitGuardian/Quality Checks, prevent delete, protect tags, stack overlays), a write-access deploy key + DEPLOY_KEY secret so release workflows can push version bumps through the rulesets' DeployKey bypass, and optional deployment environments with human-approval gates (required reviewers) from the github.environments block in .lisa.config.json. Idempotent — re-running updates settings, rulesets, and environments in place and skips an already-configured deploy key."
+allowed-tools: ["Bash", "Read", "Edit", "AskUserQuestion"]
 ---
 
 # Setup GitHub Repository Governance
@@ -29,6 +29,28 @@ Apply the fleet-standard GitHub repository configuration to this project's repo.
    - `prevent delete`, `protect tags` (`v*`), plus stack overlays (`cdk validation`, staging-only `playwright`)
    - Repos without `.github/workflows/` get only app-based required checks — an Actions check that can never report would block every PR forever
 3. **Deploy key** (`scripts/setup-deploy-key.sh --yes`) — write-access deploy key + `DEPLOY_KEY` secret, skipped when already configured. The `base` ruleset's `DeployKey: always` bypass is what lets CI version-bump pushes through protected branches.
+4. **Deployment environments** (`scripts/lisa-github-environments.sh`) — entirely optional; only runs when `.lisa.config.json` declares environments:
+   ```json
+   {
+     "github": {
+       "environments": {
+         "production": {
+           "branch": "main",
+           "require_approval": true,
+           "reviewers": ["some-user", "some-org/some-team"],
+           "prevent_self_review": false,
+           "wait_timer": 0
+         },
+         "staging": { "branch": "staging" }
+       }
+     }
+   }
+   ```
+   - Environment names are friendly names (`production`), mapped to branches. Branch resolution order: explicit `branch` → `deploy.branches[<name>]` → the name itself.
+   - `require_approval: true` provisions **required reviewers** (usernames or `org/team-slug`, max 6) — GitHub pauses any workflow job bound to the environment until a listed reviewer approves it in the Actions UI. Reviewers are mandatory when `require_approval` is true; the script refuses a gate nobody can approve.
+   - Every declared environment also gets a **deployment branch policy** pinned to its branch, so only that branch can deploy to it.
+   - Provisioning matters: GitHub silently auto-creates an environment **without** protection rules the first time a workflow references it, so an unprovisioned approval gate gates on nothing.
+   - The stack `deploy.yml` templates read this same config at runtime and pass `require_approval`/`approval_environment` to `release.yml`, whose `release_approval` job is where the run pauses. Requires a public repo or a paid plan for private repos (the script skips gracefully otherwise).
 
 ## Workflow
 
@@ -56,7 +78,31 @@ bash "$LISA_SCRIPTS/lisa-github-repo-setup.sh" .
 
 Requires `gh` authenticated with **admin** permission on the repo. A 403 on rulesets means the plan doesn't support them (private repo on a free personal plan) — settings and deploy key still apply; the script skips rulesets gracefully.
 
-### Step 4 — Verify
+### Step 4 — Wire the approval gate into an existing deploy.yml (guided edit)
+
+Only when `.lisa.config.json` has a `github.environments` entry with `require_approval: true` AND `.github/workflows/deploy.yml` exists but does not reference `approval_environment`:
+
+```bash
+[ -f .github/workflows/deploy.yml ] \
+  && jq -e '[.github.environments // {} | .[] | select(.require_approval == true)] | length > 0' .lisa.config.json > /dev/null 2>&1 \
+  && ! grep -q 'approval_environment' .github/workflows/deploy.yml \
+  && echo "deploy.yml needs approval wiring"
+```
+
+A `grep` hit is only a first pass — before skipping the edit, read the `release` job's `with:` block and confirm it actually passes both `require_approval` and `approval_environment` from the `determine_environment` outputs (a commented-out or unrelated occurrence doesn't count as wired).
+
+`deploy.yml` is create-only — the project owns it, so Lisa never patches it automatically. Show the user the two changes from the current stack template (`<stack>/create-only/.github/workflows/deploy.yml` in the Lisa repo) and offer to apply them via Edit:
+
+1. In `determine_environment`, add a checkout step plus the `🚦 Resolve approval gate from .lisa.config.json` step, and expose the `approval_environment` / `require_approval` outputs.
+2. In the `release` job's `with:` block, replace `require_approval: false` with:
+   ```yaml
+   require_approval: ${{ needs.determine_environment.outputs.require_approval == 'true' }}
+   approval_environment: ${{ needs.determine_environment.outputs.approval_environment }}
+   ```
+
+Skip this step (and say why) if the project's deploy.yml doesn't call Lisa's `release.yml` (rails uses `release-rails.yml` and harper-fabric has no release call — approval gating for those stacks is not wired yet).
+
+### Step 5 — Verify
 
 ```bash
 gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
@@ -64,4 +110,13 @@ gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
 gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/rulesets" --jq '[.[].name]'
 ```
 
-Report the applied settings and ruleset names. If any step failed, surface the error — do not mark the setup complete.
+When environments were configured, also confirm each one carries its protection rules and branch policy:
+
+```bash
+gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/environments" \
+  --jq '.environments[] | {name, protection_rules, deployment_branch_policy}'
+```
+
+For every environment declared in `github.environments`, treat a missing `deployment_branch_policy` — or, when `require_approval` is true, an empty `protection_rules` — as a failure: the environment exists but is unprotected, so an approval gate bound to it would block nothing.
+
+Report the applied settings, ruleset names, and environments. If any step failed, surface the error — do not mark the setup complete.

package/plugins/lisa-agy/commands/lisa/setup/github-repo.md

@@ -1,5 +1,5 @@
 ---
-description: "Apply Lisa's GitHub repository governance baseline: merge-only settings with auto-merge and delete-branch-on-merge, branch + tag rulesets (CodeRabbit/GitGuardian/Quality Checks gates, prevent delete, protect tags), and a CI deploy key + DEPLOY_KEY secret. Idempotent; per-repo overrides via .lisa.config.json github.settings."
+description: "Apply Lisa's GitHub repository governance baseline: merge-only settings with auto-merge and delete-branch-on-merge, branch + tag rulesets (CodeRabbit/GitGuardian/Quality Checks gates, prevent delete, protect tags), a CI deploy key + DEPLOY_KEY secret, and optional deployment environments with human-approval gates from .lisa.config.json github.environments. Idempotent; per-repo overrides via .lisa.config.json github.settings."
 allowed-tools: ["Skill"]
 argument-hint: ""
 ---

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/skills/lisa-setup-github-repo/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lisa-setup-github-repo
-description: "Apply Lisa's GitHub repository governance baseline to the current project's repo: repository settings (merge-only, auto-merge, delete-branch-on-merge, update-branch suggestions, wiki off, secret scanning where available), branch + tag rulesets from Lisa templates (base PR gate with CodeRabbit/GitGuardian/Quality Checks, prevent delete, protect tags, stack overlays), and a write-access deploy key + DEPLOY_KEY secret so release workflows can push version bumps through the rulesets' DeployKey bypass. Idempotent — re-running updates settings and rulesets in place and skips an already-configured deploy key."
-allowed-tools: ["Bash", "Read", "AskUserQuestion"]
+description: "Apply Lisa's GitHub repository governance baseline to the current project's repo: repository settings (merge-only, auto-merge, delete-branch-on-merge, update-branch suggestions, wiki off, secret scanning where available), branch + tag rulesets from Lisa templates (base PR gate with CodeRabbit/GitGuardian/Quality Checks, prevent delete, protect tags, stack overlays), a write-access deploy key + DEPLOY_KEY secret so release workflows can push version bumps through the rulesets' DeployKey bypass, and optional deployment environments with human-approval gates (required reviewers) from the github.environments block in .lisa.config.json. Idempotent — re-running updates settings, rulesets, and environments in place and skips an already-configured deploy key."
+allowed-tools: ["Bash", "Read", "Edit", "AskUserQuestion"]
 ---
 
 # Setup GitHub Repository Governance
@@ -29,6 +29,28 @@ Apply the fleet-standard GitHub repository configuration to this project's repo.
    - `prevent delete`, `protect tags` (`v*`), plus stack overlays (`cdk validation`, staging-only `playwright`)
    - Repos without `.github/workflows/` get only app-based required checks — an Actions check that can never report would block every PR forever
 3. **Deploy key** (`scripts/setup-deploy-key.sh --yes`) — write-access deploy key + `DEPLOY_KEY` secret, skipped when already configured. The `base` ruleset's `DeployKey: always` bypass is what lets CI version-bump pushes through protected branches.
+4. **Deployment environments** (`scripts/lisa-github-environments.sh`) — entirely optional; only runs when `.lisa.config.json` declares environments:
+   ```json
+   {
+     "github": {
+       "environments": {
+         "production": {
+           "branch": "main",
+           "require_approval": true,
+           "reviewers": ["some-user", "some-org/some-team"],
+           "prevent_self_review": false,
+           "wait_timer": 0
+         },
+         "staging": { "branch": "staging" }
+       }
+     }
+   }
+   ```
+   - Environment names are friendly names (`production`), mapped to branches. Branch resolution order: explicit `branch` → `deploy.branches[<name>]` → the name itself.
+   - `require_approval: true` provisions **required reviewers** (usernames or `org/team-slug`, max 6) — GitHub pauses any workflow job bound to the environment until a listed reviewer approves it in the Actions UI. Reviewers are mandatory when `require_approval` is true; the script refuses a gate nobody can approve.
+   - Every declared environment also gets a **deployment branch policy** pinned to its branch, so only that branch can deploy to it.
+   - Provisioning matters: GitHub silently auto-creates an environment **without** protection rules the first time a workflow references it, so an unprovisioned approval gate gates on nothing.
+   - The stack `deploy.yml` templates read this same config at runtime and pass `require_approval`/`approval_environment` to `release.yml`, whose `release_approval` job is where the run pauses. Requires a public repo or a paid plan for private repos (the script skips gracefully otherwise).
 
 ## Workflow
 
@@ -56,7 +78,31 @@ bash "$LISA_SCRIPTS/lisa-github-repo-setup.sh" .
 
 Requires `gh` authenticated with **admin** permission on the repo. A 403 on rulesets means the plan doesn't support them (private repo on a free personal plan) — settings and deploy key still apply; the script skips rulesets gracefully.
 
-### Step 4 — Verify
+### Step 4 — Wire the approval gate into an existing deploy.yml (guided edit)
+
+Only when `.lisa.config.json` has a `github.environments` entry with `require_approval: true` AND `.github/workflows/deploy.yml` exists but does not reference `approval_environment`:
+
+```bash
+[ -f .github/workflows/deploy.yml ] \
+  && jq -e '[.github.environments // {} | .[] | select(.require_approval == true)] | length > 0' .lisa.config.json > /dev/null 2>&1 \
+  && ! grep -q 'approval_environment' .github/workflows/deploy.yml \
+  && echo "deploy.yml needs approval wiring"
+```
+
+A `grep` hit is only a first pass — before skipping the edit, read the `release` job's `with:` block and confirm it actually passes both `require_approval` and `approval_environment` from the `determine_environment` outputs (a commented-out or unrelated occurrence doesn't count as wired).
+
+`deploy.yml` is create-only — the project owns it, so Lisa never patches it automatically. Show the user the two changes from the current stack template (`<stack>/create-only/.github/workflows/deploy.yml` in the Lisa repo) and offer to apply them via Edit:
+
+1. In `determine_environment`, add a checkout step plus the `🚦 Resolve approval gate from .lisa.config.json` step, and expose the `approval_environment` / `require_approval` outputs.
+2. In the `release` job's `with:` block, replace `require_approval: false` with:
+   ```yaml
+   require_approval: ${{ needs.determine_environment.outputs.require_approval == 'true' }}
+   approval_environment: ${{ needs.determine_environment.outputs.approval_environment }}
+   ```
+
+Skip this step (and say why) if the project's deploy.yml doesn't call Lisa's `release.yml` (rails uses `release-rails.yml` and harper-fabric has no release call — approval gating for those stacks is not wired yet).
+
+### Step 5 — Verify
 
 ```bash
 gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
@@ -64,4 +110,13 @@ gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)" \
 gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/rulesets" --jq '[.[].name]'
 ```
 
-Report the applied settings and ruleset names. If any step failed, surface the error — do not mark the setup complete.
+When environments were configured, also confirm each one carries its protection rules and branch policy:
+
+```bash
+gh api "repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/environments" \
+  --jq '.environments[] | {name, protection_rules, deployment_branch_policy}'
+```
+
+For every environment declared in `github.environments`, treat a missing `deployment_branch_policy` — or, when `require_approval` is true, an empty `protection_rules` — as a failure: the environment exists but is unprotected, so an approval gate bound to it would block nothing.
+
+Report the applied settings, ruleset names, and environments. If any step failed, surface the error — do not mark the setup complete.

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.198.1",
+  "version": "2.199.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-copilot/commands/lisa/setup/github-repo.md

@@ -1,5 +1,5 @@
 ---
-description: "Apply Lisa's GitHub repository governance baseline: merge-only settings with auto-merge and delete-branch-on-merge, branch + tag rulesets (CodeRabbit/GitGuardian/Quality Checks gates, prevent delete, protect tags), and a CI deploy key + DEPLOY_KEY secret. Idempotent; per-repo overrides via .lisa.config.json github.settings."
+description: "Apply Lisa's GitHub repository governance baseline: merge-only settings with auto-merge and delete-branch-on-merge, branch + tag rulesets (CodeRabbit/GitGuardian/Quality Checks gates, prevent delete, protect tags), a CI deploy key + DEPLOY_KEY secret, and optional deployment environments with human-approval gates from .lisa.config.json github.environments. Idempotent; per-repo overrides via .lisa.config.json github.settings."
 allowed-tools: ["Skill"]
 argument-hint: ""
 ---

package/plugins/lisa-copilot/rules/reference/config-resolution.md

@@ -274,6 +274,12 @@ Each vendor section is **conditionally required**: required only when that vendo
 | `github.projects.v2.owner.slug` | GitHub Project coordination is enabled | Owner login for the shared ProjectV2. In v1 it MUST match the tracked repository namespace (`github.org`); cross-namespace coordination is rejected. |
 | `github.projects.v2.number` | GitHub Project coordination is enabled | Human-facing ProjectV2 number from the GitHub UI / URL. Later utilities resolve the opaque node id from this owner + number pair. |
 | `github.projects.v2.required` | no | Coordination strictness flag. Default `false` keeps Project membership best-effort; `true` makes Project membership failures block the write. Setup/doctor/runtime validation reads Project ownership + access and branches on this flag: best-effort failures warn, required-mode failures stop the write. |
+| `github.environments` | no | Optional map of friendly environment name → deployment-environment declaration, provisioned by `/lisa:setup:github-repo` (`scripts/lisa-github-environments.sh`). Absent → no environments are touched. Each declared environment gets a deployment branch policy pinned to its branch. |
+| `github.environments.<name>.branch` | no | Branch that deploys to this environment. Resolution order: this field → `deploy.branches[<name>]` → the environment name itself. |
+| `github.environments.<name>.require_approval` | no | Default `false`. `true` provisions required reviewers on the environment and makes the stack `deploy.yml` templates pass `require_approval`/`approval_environment` to `release.yml`, pausing the run at the `release_approval` job until a reviewer approves. |
+| `github.environments.<name>.reviewers` | `require_approval = true` | Array of GitHub usernames or `org/team-slug` entries (max 6) allowed to approve deployments. Mandatory with `require_approval` — an approval gate nobody can approve is refused at provision time. |
+| `github.environments.<name>.prevent_self_review` | no | Default `false`. `true` stops the person who triggered the deployment from approving it themselves. |
+| `github.environments.<name>.wait_timer` | no | Default `0`. Minutes to delay the deployment after approval. |
 
 When `tracker = "github"` AND `source = "github"` (self-host), both reads and writes hit the same GitHub repo. Label namespaces are kept separate so the two flows don't collide — see "Self-host edge case" below.