@codyswann/lisa 2.198.1 → 2.199.0

package/plugins/src/base/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/scripts/lisa-github-environments.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+#
+# lisa-github-environments.sh
+#
+# Provisions GitHub deployment Environments declared in .lisa.config.json:
+#   { "github": { "environments": {
+#       "production": {
+#         "branch": "main",
+#         "require_approval": true,
+#         "reviewers": ["some-user", "some-org/some-team"],
+#         "prevent_self_review": false,
+#         "wait_timer": 0
+#       } } } }
+#
+# For each declared environment it applies:
+#   - required reviewers (the human approval gate), resolved from usernames
+#     ("login") and team slugs ("org/team-slug") to reviewer ids
+#   - prevent_self_review / wait_timer protection rules
+#   - a custom deployment branch policy pinned to the environment's branch,
+#     so only that branch can deploy to the environment
+#
+# Branch resolution order: .branch → deploy.branches[<name>] → <name> itself.
+#
+# Entirely optional: repos without github.environments in .lisa.config.json
+# are left untouched. Provisioning matters because GitHub silently
+# auto-creates an environment WITHOUT protection rules the first time a
+# workflow references it — an approval gate bound to a non-provisioned
+# environment gates on nothing.
+#
+# Usage:
+#   lisa-github-environments.sh [options] [project-path]
+#
+# Options:
+#   -n, --dry-run    Show the environment payloads without applying them
+#   -v, --verbose    Show detailed output
+#   -h, --help       Show this help message
+#
+# Requires:
+#   - gh CLI (authenticated with repo admin permissions)
+#   - jq
+#
+
+set -eo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+DRY_RUN=false
+VERBOSE=false
+PROJECT_PATH=""
+REPO=""
+
+log_info() { echo -e "${BLUE}ℹ${NC} $1"; }
+log_success() { echo -e "${GREEN}✓${NC} $1"; }
+log_warning() { echo -e "${YELLOW}⚠${NC} $1"; }
+log_error() { echo -e "${RED}✗${NC} $1" >&2; }
+log_verbose() { [[ "$VERBOSE" == "true" ]] && echo -e "  $1" || true; }
+
+show_help() {
+  sed -n '2,38p' "$0" | sed 's/^# \{0,1\}//'
+}
+
+read_environments() {
+  local project_path="$1"
+  local envs="{}"
+
+  if [[ -f "$project_path/.lisa.config.json" ]]; then
+    if ! envs=$(jq '.github.environments // {}' "$project_path/.lisa.config.json" 2>/dev/null); then
+      log_warning ".lisa.config.json could not be parsed — ignoring github.environments" >&2
+      envs="{}"
+    fi
+  fi
+
+  echo "$envs"
+}
+
+resolve_branch() {
+  local project_path="$1"
+  local name="$2"
+  local env_json="$3"
+  local branch
+
+  branch=$(echo "$env_json" | jq -r '.branch // empty')
+  if [[ -z "$branch" && -f "$project_path/.lisa.config.json" ]]; then
+    branch=$(jq -r --arg n "$name" '.deploy.branches[$n] // empty' "$project_path/.lisa.config.json" 2>/dev/null) || branch=""
+  fi
+
+  echo "${branch:-$name}"
+}
+
+# Resolves a reviewer entry to the {type, id} shape the environments API
+# expects. Entries containing "/" are org team slugs; anything else is a user.
+resolve_reviewer() {
+  local entry="$1"
+  local id
+
+  if [[ "$entry" == */* ]]; then
+    local org="${entry%%/*}"
+    local slug="${entry#*/}"
+    if ! id=$(gh api "orgs/$org/teams/$slug" --jq .id 2>/dev/null); then
+      log_error "Could not resolve team reviewer '$entry' — check the org/team-slug and your token's read:org scope"
+      return 1
+    fi
+    jq -n --argjson id "$id" '{type: "Team", id: $id}'
+  else
+    if ! id=$(gh api "users/$entry" --jq .id 2>/dev/null); then
+      log_error "Could not resolve user reviewer '$entry' — check the username"
+      return 1
+    fi
+    jq -n --argjson id "$id" '{type: "User", id: $id}'
+  fi
+}
+
+build_payload() {
+  local env_json="$1"
+  local reviewers_json="$2"
+
+  jq -n \
+    --argjson reviewers "$reviewers_json" \
+    --argjson prevent "$(echo "$env_json" | jq '.prevent_self_review // false')" \
+    --argjson wait "$(echo "$env_json" | jq '.wait_timer // 0')" \
+    '{
+      wait_timer: $wait,
+      prevent_self_review: $prevent,
+      reviewers: $reviewers,
+      deployment_branch_policy: {
+        protected_branches: false,
+        custom_branch_policies: true
+      }
+    }'
+}
+
+ensure_branch_policy() {
+  local name="$1"
+  local branch="$2"
+  local existing
+
+  existing=$(gh api "repos/$REPO/environments/$name/deployment-branch-policies" --jq '.branch_policies[].name' 2>/dev/null) || existing=""
+  if echo "$existing" | grep -qxF "$branch"; then
+    log_verbose "Deployment branch policy '$branch' already present on '$name'"
+    return 0
+  fi
+
+  if jq -n --arg b "$branch" '{name: $b}' | gh api -X POST "repos/$REPO/environments/$name/deployment-branch-policies" --input - > /dev/null 2>&1; then
+    log_success "Pinned '$name' deployments to branch '$branch'"
+  else
+    log_warning "Could not create deployment branch policy '$branch' on '$name'"
+  fi
+}
+
+provision_environment() {
+  local name="$1"
+  local env_json="$2"
+  local branch
+  branch=$(resolve_branch "$PROJECT_PATH" "$name" "$env_json")
+
+  local require_approval
+  require_approval=$(echo "$env_json" | jq -r '.require_approval // false')
+
+  local reviewer_entries
+  reviewer_entries=$(echo "$env_json" | jq -r '.reviewers // [] | .[]')
+
+  # An approval gate with nobody able to approve would silently gate on
+  # nothing — refuse rather than provision a no-op.
+  if [[ "$require_approval" == "true" && -z "$reviewer_entries" ]]; then
+    log_error "Environment '$name' has require_approval: true but no reviewers — list at least one username or org/team-slug in github.environments.$name.reviewers"
+    exit 1
+  fi
+
+  local reviewers_json="[]"
+  local entry reviewer
+  while IFS= read -r entry; do
+    [[ -z "$entry" ]] && continue
+    if ! reviewer=$(resolve_reviewer "$entry"); then
+      exit 1
+    fi
+    reviewers_json=$(echo "$reviewers_json" | jq --argjson r "$reviewer" '. + [$r]')
+  done <<< "$reviewer_entries"
+
+  local payload
+  payload=$(build_payload "$env_json" "$reviewers_json")
+  log_verbose "Environment '$name' payload: $(echo "$payload" | jq -c .)"
+
+  if [[ "$DRY_RUN" == "true" ]]; then
+    log_info "[DRY RUN] Would provision environment '$name' (branch: $branch):"
+    echo "$payload" | jq .
+    log_info "[DRY RUN] Would pin deployment branch policy '$branch' on '$name'"
+    return 0
+  fi
+
+  local response
+  if ! response=$(echo "$payload" | gh api -X PUT "repos/$REPO/environments/$name" --input - 2>&1); then
+    # Environments with protection rules need a public repo or a paid plan —
+    # skip gracefully like the rulesets script does.
+    if echo "$response" | grep -qiE "HTTP 403|HTTP 422|upgrade to github"; then
+      log_warning "Environments are not available on this repository's plan — skipped '$name'. Approval gates will not be enforced until the repo is public or on a paid plan."
+      return 0
+    fi
+    log_error "Failed to provision environment '$name': $response"
+    exit 1
+  fi
+  log_success "Provisioned environment '$name' (branch: $branch)"
+
+  ensure_branch_policy "$name" "$branch"
+}
+
+main() {
+  while [[ $# -gt 0 ]]; do
+    case $1 in
+      -n|--dry-run) DRY_RUN=true; shift ;;
+      -v|--verbose) VERBOSE=true; shift ;;
+      -h|--help) show_help; exit 0 ;;
+      -*) log_error "Unknown option: $1"; show_help; exit 1 ;;
+      *) PROJECT_PATH="$1"; shift ;;
+    esac
+  done
+
+  PROJECT_PATH="${PROJECT_PATH:-.}"
+  PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
+
+  if ! command -v gh &> /dev/null || ! command -v jq &> /dev/null; then
+    log_error "Requires gh and jq"
+    exit 1
+  fi
+
+  local envs
+  envs=$(read_environments "$PROJECT_PATH")
+  if [[ "$(echo "$envs" | jq 'length')" == "0" ]]; then
+    log_info "No github.environments configured in .lisa.config.json — skipping"
+    return 0
+  fi
+
+  if ! gh auth status &> /dev/null; then
+    log_error "GitHub CLI is not authenticated. Run 'gh auth login' first."
+    exit 1
+  fi
+
+  cd "$PROJECT_PATH"
+  REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null) || {
+    log_error "Could not determine repository for $PROJECT_PATH"
+    exit 1
+  }
+  log_info "Repository: $REPO"
+
+  local name env_json
+  while IFS= read -r name; do
+    [[ -z "$name" ]] && continue
+    env_json=$(echo "$envs" | jq --arg n "$name" '.[$n]')
+    provision_environment "$name" "$env_json"
+  done <<< "$(echo "$envs" | jq -r 'keys[]')"
+}
+
+main "$@"

package/scripts/lisa-github-repo-setup.sh

@@ -8,6 +8,9 @@
 #   3. CI deploy key + DEPLOY_KEY secret (setup-deploy-key.sh --yes),
 #      so release workflows can push version bumps through the rulesets'
 #      DeployKey bypass.
+#   4. Deployment environments with required-reviewer approval gates
+#      (lisa-github-environments.sh), from the optional
+#      github.environments block in .lisa.config.json.
 #
 # Usage:
 #   lisa-github-repo-setup.sh [options] [project-path]
@@ -35,7 +38,7 @@ while [[ $# -gt 0 ]]; do
   case $1 in
     -n|--dry-run) DRY_RUN=true; PASSTHROUGH+=("--dry-run"); shift ;;
     -v|--verbose) VERBOSE=true; PASSTHROUGH+=("--verbose"); shift ;;
-    -h|--help) sed -n '2,24p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -h|--help) sed -n '2,27p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     -*) echo "Unknown option: $1" >&2; exit 1 ;;
     *) PROJECT_PATH="$1"; shift ;;
   esac
@@ -44,15 +47,15 @@ done
 PROJECT_PATH="${PROJECT_PATH:-.}"
 PROJECT_PATH="$(cd "$PROJECT_PATH" && pwd)"
 
-echo "==> Step 1/3: repository settings"
+echo "==> Step 1/4: repository settings"
 bash "$SCRIPT_DIR/lisa-github-repo-settings.sh" "${PASSTHROUGH[@]}" "$PROJECT_PATH"
 
 echo ""
-echo "==> Step 2/3: rulesets"
+echo "==> Step 2/4: rulesets"
 bash "$SCRIPT_DIR/lisa-github-rulesets.sh" --yes "${PASSTHROUGH[@]}" "$PROJECT_PATH"
 
 echo ""
-echo "==> Step 3/3: deploy key"
+echo "==> Step 3/4: deploy key"
 if [[ "$DRY_RUN" == "true" ]]; then
   echo "[DRY RUN] Would ensure a write-access deploy key + DEPLOY_KEY secret exist"
 else
@@ -69,5 +72,9 @@ else
   fi
 fi
 
+echo ""
+echo "==> Step 4/4: deployment environments"
+bash "$SCRIPT_DIR/lisa-github-environments.sh" "${PASSTHROUGH[@]}" "$PROJECT_PATH"
+
 echo ""
 echo "✓ GitHub repository governance setup complete"

package/typescript/copy-overwrite/.github/GITHUB_ACTIONS.md

@@ -123,6 +123,31 @@ Enterprise-grade release management:
 - Sentry release creation
 - Jira release creation
 - Compliance validation (SOC2, ISO27001, HIPAA, PCI-DSS)
+- Optional human-approval gate (`require_approval` + `approval_environment`)
+
+**Human-approval gate**: pass `require_approval: true` and the run pauses at the
+`🚦 Release Approval` job until a required reviewer approves it in the Actions UI.
+The pause is enforced by the GitHub Environment named in `approval_environment`
+(falls back to `environment`, i.e. the branch name):
+
+```yaml
+uses: CodySwannGT/lisa/.github/workflows/release.yml@main
+with:
+  require_approval: true
+  approval_environment: 'production'
+```
+
+Because everything downstream (versioning, GitHub Release, and any deploy job
+that `needs: release`) chains off this gate, approval blocks the whole pipeline.
+The Lisa stack `deploy.yml` templates wire both inputs automatically from the
+optional `github.environments` block in `.lisa.config.json`, mapping the branch
+to its friendly environment name (`main` → `production` via `deploy.branches`).
+The environment itself — required reviewers and a deployment branch policy —
+is provisioned by `/lisa:setup:github-repo`. Provision before enabling the gate:
+GitHub auto-creates unprovisioned environments **without** protection rules, so
+an unprovisioned gate blocks nothing. Not yet wired for rails
+(`release-rails.yml` doesn't thread approval inputs) or harper-fabric (no
+release.yml call).
 
 **Blackout Periods** (configurable):
 - Production: No weekends, no late nights (10 PM - 6 AM)
@@ -576,7 +601,11 @@ with:
   approval_environment: 'production'
 ```
 
-**Note**: Create the environment in **Settings** > **Environments** first.
+**Note**: Create the environment in **Settings** > **Environments** first (or
+declare it under `github.environments` in `.lisa.config.json` and run
+`/lisa:setup:github-repo`). Unlike release.yml's environment-enforced gate,
+quality.yml's `approval_gate` job only records an audit artifact — it does not
+pause the run. For an enforced human gate, use release.yml's `require_approval`.
 
 ### Custom Node Version