@1aboveio/skills 0.10.0

package/skills/cicd-pipeline/google-cloud/references/vpc.md

@@ -0,0 +1,312 @@
+# VPC Configuration
+
+VPC networks, subnets, and firewall rules for GCP infrastructure.
+
+## Network Operations
+
+### List Networks
+
+```bash
+# All networks in project
+gcloud compute networks list
+
+# With details
+gcloud compute networks list --format="table(name,subnetMode,autoCreateSubnetworks)"
+```
+
+### Create Network
+
+```bash
+# Custom subnet mode (recommended)
+gcloud compute networks create $NAME \
+  --subnet-mode=custom \
+  --mtu=1460 \
+  --bgp-routing-mode=regional
+
+# Legacy (auto-create subnets)
+gcloud compute networks create $NAME \
+  --subnet-mode=legacy \
+  --auto-create-subnetworks
+```
+
+### Delete Network
+
+```bash
+gcloud compute networks delete $NAME
+```
+
+---
+
+## Subnet Operations
+
+### List Subnets
+
+```bash
+# All subnets in region
+gcloud compute networks subnets list --region=us-central1
+
+# In specific network
+gcloud compute networks subnets list \
+  --filter="network:$NETWORK" \
+  --region=us-central1
+```
+
+### Create Subnet
+
+```bash
+gcloud compute networks subnets create $SUBNET \
+  --network=$NETWORK \
+  --region=us-central1 \
+  --range=$IP_RANGE \
+  --purpose=REGIONAL_MANAGED_PROXY \
+  --enable-flow-logs \
+  --logging-flow-sampling=0.5 \
+  --logging-metadata=include-all
+```
+
+### Describe Subnet
+
+```bash
+gcloud compute networks subnets describe $SUBNET \
+  --region=us-central1 \
+  --format="yaml(ipCidrRange,purpose,privateIpGoogleAccess,secondaryIpRanges)"
+```
+
+---
+
+## Cloud Run with VPC
+
+### Deploy Cloud Run with VPC
+
+```bash
+gcloud run deploy $SERVICE \
+  --image=$IMAGE \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --subnet=$SUBNET
+```
+
+### Update Existing Service VPC
+
+```bash
+gcloud run services update $SERVICE \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --subnet=$SUBNET
+```
+
+### Cloud Run Job with VPC
+
+```bash
+gcloud run jobs create $JOB \
+  --image=$IMAGE \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --subnet=$SUBNET
+
+# Update existing job
+gcloud run jobs update $JOB \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --subnet=$SUBNET
+```
+
+---
+
+## Cloud SQL Connection Standard
+
+**1Above standard:** Connect via direct VPC + private IP. Do NOT use Cloud SQL Auth Proxy (`--add-cloudsql-instances`).
+
+### Connection string format
+
+```
+postgresql://<user>:<password>@<PRIVATE_IP>:5432/<database>?sslmode=no-verify&connect_timeout=5
+```
+
+### Cloud SQL instance private IPs (GCP project: cosmic-heaven-479306-v5)
+
+| Instance | Private IP |
+|----------|------------|
+| ai-dev   | 10.58.0.11 |
+
+### Cloud Run deploy flags
+
+```bash
+--network=default \
+--subnet=default \
+--vpc-egress=private-ranges-only
+# Do NOT add: --add-cloudsql-instances
+```
+
+### Why sslmode=no-verify?
+
+`ai-dev` has `requireSsl: true` + `TRUSTED_CLIENT_CERTIFICATE_REQUIRED`.
+`sslmode=no-verify` encrypts the connection without requiring client certificates — consistent with all existing services (a1-research-dev, etc.).
+
+### Reference service
+
+Check `a1-research-dev` DATABASE_URL in Secret Manager as the canonical example.
+
+---
+
+## VPC Connectors (Serverless VPC Access)
+
+### Create VPC Connector
+
+```bash
+gcloud compute networks vpc-access connectors create $CONNECTOR \
+  --region=us-central1 \
+  --network=$NETWORK \
+  --range=$IP_RANGE
+```
+
+### List VPC Connectors
+
+```bash
+gcloud compute networks vpc-access connectors list --region=us-central1
+```
+
+### Use Connector with Cloud Run
+
+```bash
+gcloud run services update $SERVICE \
+  --region=us-central1 \
+  --vpc-connector=$CONNECTOR
+```
+
+---
+
+## Firewall Rules
+
+### List Firewall Rules
+
+```bash
+# All rules
+gcloud compute firewall-rules list
+
+# For specific network
+gcloud compute firewall-rules list --filter="network:$NETWORK"
+
+# With details
+gcloud compute firewall-rules describe $RULE
+```
+
+### Create Firewall Rule
+
+```bash
+# Allow SSH from anywhere (dev only)
+gcloud compute firewall-rules create allow-ssh \
+  --network=$NETWORK \
+  --allow=tcp:22 \
+  --source-ranges=0.0.0.0/0 \
+  --target-tags=$TAG
+
+# Allow internal traffic
+gcloud compute firewall-rules create allow-internal \
+  --network=$NETWORK \
+  --allow=tcp,udp,icmp \
+  --source-ranges=$IP_RANGE \
+  --direction=INGRESS
+
+# Allow health checks
+gcloud compute firewall-rules create allow-health-check \
+  --network=$NETWORK \
+  --allow=tcp:80,tcp:443 \
+  --source-ranges=35.191.0.0/16,130.211.0.0/22 \
+  --target-tags=$TAG
+```
+
+---
+
+## Private Google Access
+
+### Check if Subnet Has Private Google Access
+
+```bash
+gcloud compute networks subnets describe $SUBNET \
+  --region=us-central1 \
+  --format="value(privateIpGoogleAccess)"
+```
+
+### Enable Private Google Access on Subnet
+
+```bash
+gcloud compute networks subnets describe $SUBNET \
+  --region=us-central1 \
+  --set-private-ip-google-access
+```
+
+---
+
+## Shared VPC (Host Project)
+
+### List Shared VPC Networks
+
+```bash
+gcloud compute shared-vpc list-host-projects
+gcloud compute networks list --project=$HOST_PROJECT
+```
+
+### Enable Shared VPC on Service Project
+
+```bash
+gcloud compute projects enable-shared-vpc $SERVICE_PROJECT
+
+# Attach service project to host
+gcloud compute shared-vpc associated-projects add $SERVICE_PROJECT \
+  --host-project=$HOST_PROJECT
+```
+
+---
+
+## VPC Peering
+
+### Create VPC Peering
+
+```bash
+# From network A
+gcloud compute networks peerings create $PEERING_NAME \
+  --network=$NETWORK_A \
+  --peer-project=$PROJECT_B \
+  --peer-network=$NETWORK_B \
+  --export-custom-routes \
+  --import-custom-routes
+```
+
+### List Peerings
+
+```bash
+gcloud compute networks peerings list --network=$NETWORK
+```
+
+---
+
+## Useful Queries
+
+### Find Subnet by IP Range
+
+```bash
+gcloud compute networks subnets list \
+  --filter="ipCidrRange:$IP_RANGE" \
+  --regions=us-central1
+```
+
+### Find Resources Using Specific Network
+
+```bash
+# Cloud Run services
+gcloud run services list \
+  --filter="metadata.annotations.run.googleapis.com/network-name:$NETWORK"
+
+# Cloud Run jobs
+gcloud run jobs list \
+  --filter="metadata.annotations.run.googleapis.com/network-name:$NETWORK"
+```
+
+### Check VPC Flow Logs Status
+
+```bash
+gcloud compute networks subnets describe $SUBNET \
+  --region=us-central1 \
+  --format="value(logConfig.enable)"
+```

package/skills/cicd-pipeline/google-cloud/scripts/create-sa.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Create Service Account with Standard Roles
+# Usage: ./create-sa.sh [sa-name] [display-name] [roles...]
+
+set -e
+
+SA_NAME="${1:-my-sa}"
+DISPLAY_NAME="${2:-$SA_NAME}"
+PROJECT_ID="${PROJECT_ID:-your-project-id}"
+
+# Optional roles (default: cloudsql.client, secretmanager.secretAccessor)
+shift 2
+ROLES=("${@:-roles/cloudsql.client roles/secretmanager.secretAccessor)}")
+
+SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
+
+echo "Creating Service Account: $SA_NAME"
+echo "Email: $SA_EMAIL"
+echo "Roles: ${ROLES[*]}"
+
+# Create SA
+gcloud iam service-accounts create "$SA_NAME" \
+  --display-name="$DISPLAY_NAME" \
+  --project=$PROJECT_ID
+
+# Grant roles
+for ROLE in "${ROLES[@]}"; do
+  echo "Granting $ROLE..."
+  gcloud projects add-iam-policy-binding $PROJECT_ID \
+    --member="serviceAccount:$SA_EMAIL" \
+    --role="$ROLE"
+done
+
+echo ""
+echo "Service Account created successfully!"
+echo "Email: $SA_EMAIL"

package/skills/cicd-pipeline/google-cloud/scripts/gcp-config.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Project: ${PROJECT_ID:-your-project-id}
+# Region: us-central1
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+
+# Configuration
+PROJECT_ID="${PROJECT_ID:-your-project-id}"
+PROJECT_NUMBER="${PROJECT_NUMBER:-your-project-number}"
+REGION="us-central1"
+
+# Set project
+gcloud config set project $PROJECT_ID
+
+# Validate project
+if ! gcloud projects describe $PROJECT_ID &>/dev/null; then
+  log_error "Project $PROJECT_ID not accessible"
+  exit 1
+fi
+
+log_info "Project $PROJECT_ID configured successfully"

package/skills/cicd-pipeline/google-cloud/scripts/grant-iap.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# Grant IAP Access to Service Account
+# Usage: ./grant-iap-access.sh [service-account-email] [backend-service-name]
+
+set -e
+
+SA_EMAIL="${1:-e2e-runner@${PROJECT_ID:-your-project-id}.iam.gserviceaccount.com}"
+BACKEND_SERVICE="${2:-my-backend-service}"
+PROJECT_ID="${PROJECT_ID:-your-project-id}"
+
+echo "Granting IAP access to: $SA_EMAIL"
+echo "Backend service: $BACKEND_SERVICE"
+
+# Grant IAP access on backend service
+gcloud iap web add-iam-policy-binding \
+  --project=$PROJECT_ID \
+  --resource-type=backend-services \
+  --service=$BACKEND_SERVICE \
+  --member="serviceAccount:$SA_EMAIL" \
+  --role="roles/iap.httpsResourceAccessor"
+
+echo ""
+echo "IAP access granted successfully!"
+echo ""
+echo "Next: Use signed JWT to access IAP-protected service:"
+echo ""
+cat << 'EOF'
+SERVICE_URL="https://${BACKEND_SERVICE}-${HASH}-uc.a.run.app"
+SIGNER_SA="signer-sa@${PROJECT_ID}.iam.gserviceaccount.com"
+
+NOW="$(date +%s)"
+cat > /tmp/iap-jwt.json <<JSON
+{"iss":"${SIGNER_SA}","sub":"${SIGNER_SA}","aud":"${SERVICE_URL}/*","iat":${NOW},"exp":$((NOW+600))}
+JSON
+
+gcloud iam service-accounts sign-jwt /tmp/iap-jwt.json /tmp/iap-jwt.jwt \
+  --iam-account="${SIGNER_SA}"
+
+TOKEN="$(cat /tmp/iap-jwt.jwt)"
+curl -i "${SERVICE_URL}/" -H "Authorization: Bearer ${TOKEN}"
+EOF

package/skills/cicd-pipeline/google-cloud/scripts/setup-secrets.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Setup Secrets for Service
+# Usage: ./setup-secrets.sh [service-name]
+
+set -e
+
+SERVICE_NAME="${1:-my-service}"
+PROJECT_ID="${PROJECT_ID:-your-project-id}"
+ENVIRONMENTS=("dev" "staging" "prod")
+
+for ENV in "${ENVIRONMENTS[@]}"; do
+  SECRET_NAME="${SERVICE_NAME}-database-url-${ENV}"
+  
+  echo "Creating secret: $SECRET_NAME"
+  
+  # Create secret (ignore if exists)
+  gcloud secrets create "$SECRET_NAME" \
+    --replication-policy="automatic" \
+    --project=$PROJECT_ID 2>/dev/null || true
+  
+  # Add version placeholder (user should update with actual value)
+  echo -n "postgresql://user:pass@host/${SERVICE_NAME}-${ENV}" | \
+    gcloud secrets versions add "$SECRET_NAME" \
+      --data-file=- \
+      --project=$PROJECT_ID
+done
+
+# Create shared secret key
+SHARED_SECRET="${SERVICE_NAME}-shared-secret"
+echo "Creating shared secret: $SHARED_SECRET"
+
+gcloud secrets create "$SHARED_SECRET" \
+  --replication-policy="automatic" \
+  --project=$PROJECT_ID 2>/dev/null || true
+
+# Generate random key
+openssl rand -hex 32 | \
+  gcloud secrets versions add "$SHARED_SECRET" \
+    --data-file=- \
+    --project=$PROJECT_ID
+
+echo ""
+echo "Secrets created successfully!"
+echo ""
+echo "Grant access to Cloud Run SA:"
+echo "  gcloud secrets add-iam-policy-binding ${SERVICE_NAME}-database-url-dev \\"
+echo "    --member=\"serviceAccount:${PROJECT_ID}-run@developer.gserviceaccount.com\" \\"
+echo "    --role=\"roles/secretmanager.secretAccessor\""

package/skills/cicd-pipeline/mergify/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/cicd-pipeline/mergify/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: mergify
+description: "Mergify merge-queue config, rules, PR delivery, and queue status. Use whenever a merge queue is involved — including plain-sounding asks about one PR ('watch #123 till it merges', 'where is #412 in the queue', 'checks are green, get it merged'): a `gh pr view`/`gh pr checks` poll cannot see a dequeue, so these need `mergify queue show` and the bundled watcher, never hand-rolled polling. Also: authoring or debugging `.mergify.yml`, queue rules, merge protections, batch size, the GitHub ruleset making merges queue-only; enqueue policy (`@mergifyio queue` vs `auto_merge_conditions`); a push dequeuing a queued PR; bypass actors; freezing a branch. Failures: a PR stuck, queued but never merging, or merged unqueued; CI green on GitHub but unmet in Mergify; a batch going red or bisecting; a check missing rather than failing. Outranks the vendor mergify-* command skills. NOT for GitHub Actions authoring (cloud-build), a failing CI job (cloud-debug), or GCP deploy pipelines (cloud-deploy)."
+---
+
+# Mergify Merge Queue
+
+Merge queue setup that defaults to **held**: a PR merges only when someone
+explicitly enqueues it, batches of 3 are tested together, and the branch is kept
+fresh against base.
+
+**This file is an index.** The doctrine lives in `references/`, one file per
+lane, because agents read skills partially — with an explicit `limit`, or by
+skimming until the content looks familiar — and anything below that cutoff is
+not deprioritized, it is *absent*. Keeping this file short means the routing
+survives a partial read even when the detail does not. That failure is why the
+file is shaped this way: an agent asked to watch a PR read the old 469-line
+version with `limit: 200`, never reached a single line about `dequeued`,
+hand-rolled its own shell watcher, and reported a queued PR as dequeued.
+
+So: **find your task below, then read that row's target.** Do not work from this
+page alone — it deliberately does not contain enough to act on.
+
+## Routing
+
+| Your task | Read | The rule you must not miss |
+|---|---|---|
+| **Get an open or just-pushed PR merged** | [`references/watch-contract.md`](references/watch-contract.md#enqueue-before-you-watch) | Enqueue, *then* watch — the watch never enqueues, so a watch started on a PR nothing will enqueue can only end `STALLED`. A push to an already-queued PR dequeues it (`pull-request-updated`): the verdict is stale, re-validate before re-enqueuing. Several ready at once? Enqueue them together — next row. |
+| **Deliver several ready PRs at once (a stack, an epic's units, a burst)** | [`references/watch-contract.md`](references/watch-contract.md#batch-delivery--enqueue-the-whole-ready-set-together) | Enqueue the whole ready set **together**, then watch: PRs riding one batch cost one CI run, and a red batch bisects to the culprit while the rest carry on. "If possible" is the point — a lone PR, or stragglers still waiting on review/CI/conflict, never hold the batch window open. |
+| Author or change `.mergify.yml` | [`references/configuration.md`](references/configuration.md) | [Rule 1](#rule-1--fetch-the-docs-before-writing-config): never write config from memory; finish with `validate` **and** `simulate`. |
+| **Watch a PR through the queue** | [`references/watch-contract.md`](references/watch-contract.md) | **[Rule 2](#rule-2--never-hand-roll-a-watcher): run the bundled watcher, never hand-roll one.** A watch observes a *progression*, not one state. |
+| Check status — "where is my PR?", "why is it stuck?" | [`references/diagnosis.md`](references/diagnosis.md#querying-pr-and-queue-status) | `mergify queue show <PR> -v` names the single blocking condition; nothing else in the toolchain does. `gh pr checks` is CI truth, never queue truth — and a one-off read of the `queued`/`dequeued` labels is neither. |
+| A PR merged without ever being queued | [`references/branch-protection.md`](references/branch-protection.md) | A required status check does **not** make the queue mandatory. Only the `update` rule does. |
+| Set up, audit, freeze, or protect a branch | [`references/configuration.md`](references/configuration.md#setup-checklist), then [`references/branch-protection.md`](references/branch-protection.md) | Bypass is granted per *ruleset*, never per rule — so Mergify bypasses the required check too. |
+| A batch keeps going red, bisects, or hangs on a check | [`references/traps.md`](references/traps.md) | An *absent* check reads as permanently unmet. That is not the same as failing. |
+| Something broke and you want the known landmines | [`references/traps.md`](references/traps.md) | Each one has been hit in production; skim it before debugging from first principles. |
+
+**Templates** — both required. The `.mergify.yml` decides what the queue *does*;
+the ruleset is what stops anyone bypassing the queue entirely.
+
+- [`assets/templates/mergify.yml`](assets/templates/mergify.yml) — copy to the
+  repo root as `.mergify.yml` and fill in the placeholders.
+- [`assets/templates/ruleset.json`](assets/templates/ruleset.json) — the GitHub
+  branch ruleset that makes the queue mandatory.
+
+**Scripts** — run these rather than reimplementing what they do:
+
+| Script | Use |
+|---|---|
+| [`scripts/watch-pr-delivery.mjs`](scripts/watch-pr-delivery.mjs) | Watch an enqueued PR to a terminal verdict. See [Rule 2](#rule-2--never-hand-roll-a-watcher). |
+| [`scripts/audit.mjs`](scripts/audit.mjs) | Audit a `.mergify.yml` against this skill's defaults — the shape `config validate` cannot check. |
+
+## Non-Negotiable Rules
+
+Three rules, two of them on this page rather than in a reference because they
+prevent a *silent* failure — the config looks valid, the watcher looks like it
+is working — and the third because it is the delivery default batching depends
+on. A reader who takes nothing else from this skill should take all three.
+
+### Rule 1 — Fetch the docs before writing config
+
+The schema changes and options get deprecated, so do not write `.mergify.yml`
+from memory:
+
+```bash
+curl -s https://docs.mergify.com/mergify-configuration-schema.json -o /tmp/mergify-schema.json
+```
+
+Reference pages: `https://docs.mergify.com/merge-queue/rules`,
+`/merge-queue/batches`, `/merge-protections/setup`, `/commands`. Full index at
+`https://docs.mergify.com/llms.txt`.
+
+Then always finish with both:
+
+```bash
+mergify config validate                                          # schema check
+mergify config simulate https://github.com/<owner>/<repo>/pull/<n>   # behaviour check
+```
+
+`validate` catches typos. `simulate` catches the config being *valid but wrong*
+— which is the failure mode that actually costs hours.
+
+### Rule 2 — Never hand-roll a watcher
+
+Watching a PR through the queue means running
+[`scripts/watch-pr-delivery.mjs`](scripts/watch-pr-delivery.mjs). Writing your
+own `gh pr view` polling snippet — in shell, in a background-task command, in
+anything — is refused, not merely discouraged.
+
+The reason is that **a watch tracks a progression, not a state.** The verdict
+depends on what the watcher has *already seen*: absent queue membership means
+"not admitted yet" before queue entry and "dequeued" after it, and no single
+snapshot distinguishes them. So the watcher must carry `seenQueued`, process-local
+`everActive` (membership observed *this* run — `--seen-queued` alone is only a
+resume hint and must not invent that observation), a re-read counter,
+readable-vs-absent, and a change clock across every poll. A background runner that
+re-runs a command each tick and reads its exit code is a stateless predicate
+evaluator with nowhere to keep any of that — the shape is wrong before the code is.
+
+```bash
+node ~/.agents/skills/mergify/scripts/watch-pr-delivery.mjs \
+  --repo <owner/repo> \
+  --pr <number>
+```
+
+Enqueue first — the watch never enqueues, so on a manual-delivery repo a watch
+started on an unqueued PR can only end `STALLED`. Full state machine, the
+`queued`/`dequeued` label semantics, the `"queued": true` JSON-shape trap, the
+dequeue-reason routing table, and how to read the `phases` progression:
+[`references/watch-contract.md`](references/watch-contract.md).
+
+### Rule 3 — Enqueue the whole ready set together
+
+Batch mode only pays when the PRs are **in the queue together**, and only the
+deliverer controls that. When several PRs against the same base are ready — a
+stack, an epic's independently-shippable units, a burst of related edits —
+enqueue them all in one pass, then watch them together. One batch CI run for N
+PRs; a red batch bisects to the culprit and the rest carry on. Serial delivery —
+enqueue, watch to merge, then enqueue the next — quietly buys N batches for
+work that could have ridden one, and is never faster. "If possible" is the
+escape hatch, not the rule: a lone PR, or PRs still waiting on review/CI/
+conflict, never hold the batch window open. Mechanics and the grouping rule
+(what Mergify actually batches together) live in
+[`references/watch-contract.md`](references/watch-contract.md#batch-delivery--enqueue-the-whole-ready-set-together).
+
+## Related Skills
+
+- [cloud-build](../cloud-build/SKILL.md) — the CI the queue gates on
+- [cloud-debug](../cloud-debug/SKILL.md) — when the CI job itself is failing
+- [resolve-issues](../../engineering/resolve-issues/SKILL.md) — consumes this skill's delivery
+  watch contract when it delivers merge-ready PRs through Mergify
+- `mergify-config`, `mergify-merge-queue`, `mergify-merge-protections`, `mergify-ci`,
+  `mergify-stack` (vendor plugin skills) — reference for raw CLI invocation. They document
+  *how to call* the commands; this skill decides *what the config should say* and owns the
+  GitHub-side enforcement. On any conflict, this skill wins — it encodes decisions the
+  vendor docs are neutral about (held-by-default enqueue, batch 3, the `update`-rule
+  ruleset, the traps in `references/traps.md`).
+