Merge pull request #23 from japer-technology/copilot/add-definitive-t… #60
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # ╔══════════════════════════════════════════════════════════════════════════════╗ | |
| # ║ GitHub GStack Intelligence — Agent Workflow (Version 1.0.2) ║ | |
| # ║ ║ | |
| # ║ An AI agent that lives inside your GitHub repository. It uses Issues as ║ | |
| # ║ a conversational UI, Git for persistent memory, and Actions as its only ║ | |
| # ║ compute layer. No external servers or infrastructure required. ║ | |
| # ║ ║ | |
| # ║ QUICK START — copy this file into your repo and you're 4 steps away: ║ | |
| # ║ ║ | |
| # ║ 1. Copy this file → .github/workflows/ in your repository. ║ | |
| # ║ 2. Add an LLM API key as a repository secret ║ | |
| # ║ (Settings → Secrets and variables → Actions). ║ | |
| # ║ At minimum, add ONE of: ║ | |
| # ║ • OPENAI_API_KEY (OpenAI — default provider) ║ | |
| # ║ • ANTHROPIC_API_KEY (Anthropic Claude) ║ | |
| # ║ • GEMINI_API_KEY (Google Gemini) ║ | |
| # ║ • XAI_API_KEY (xAI Grok) ║ | |
| # ║ • OPENROUTER_API_KEY (OpenRouter / DeepSeek) ║ | |
| # ║ • MISTRAL_API_KEY (Mistral) ║ | |
| # ║ • GROQ_API_KEY (Groq) ║ | |
| # ║ 3. Run the workflow manually: ║ | |
| # ║ Actions → github-gstack-intelligence-agent → Run workflow. ║ | |
| # ║ This installs the agent folder into your repo (or upgrades it). ║ | |
| # ║ 4. Open an issue — the agent reads your message and replies! ║ | |
| # ║ ║ | |
| # ║ HOW IT WORKS: ║ | |
| # ║ • Every issue is a conversation thread. Comment again to continue. ║ | |
| # ║ • The agent commits every response to git — full history, full recall. ║ | |
| # ║ • Only repo collaborators with write access (or higher) can trigger ║ | |
| # ║ the agent. Unauthorized users are silently rejected. ║ | |
| # ║ ║ | |
| # ║ WHAT THIS WORKFLOW CONTAINS (three jobs): ║ | |
| # ║ run-install — Self-installer and upgrader (workflow_dispatch only). ║ | |
| # ║ run-agent — AI agent that responds to issues and comments. ║ | |
| # ║ run-gitpages — Publishes the agent's public-fabric to GitHub Pages. ║ | |
| # ║ ║ | |
| # ║ Docs: https://github.com/japer-technology/github-gstack-intelligence ║ | |
| # ╚══════════════════════════════════════════════════════════════════════════════╝ | |
| name: github-gstack-intelligence-agent | |
| # ────────────────────────────────────────────────────────────────────────────── | |
| # TRIGGERS | |
| # The workflow listens for several distinct GitHub events. Each event activates | |
| # a different job (see the `if:` guards on each job below). | |
| # ────────────────────────────────────────────────────────────────────────────── | |
| on: | |
| # 1. A new issue is opened → the agent reads it and posts an AI response. | |
| issues: | |
| types: [opened] | |
| # 2. A comment is added to an existing issue → the agent continues the | |
| # conversation, loading the full session history from git. | |
| issue_comment: | |
| types: [created] | |
| # 3. A pull request is opened or updated → the agent runs a /review skill | |
| # (or /cso if the security-audit label is present). | |
| pull_request: | |
| types: [opened, synchronize] | |
| # 4. Code is pushed to main → triggers a GitHub Pages deployment so the | |
| # agent's public-fabric site stays up to date. | |
| # paths-ignore ensures that editing this workflow file alone does NOT | |
| # trigger a redundant Pages deploy. | |
| push: | |
| branches: ["main"] | |
| paths-ignore: | |
| - ".github/workflows/**" | |
| # 5. Manual "Run workflow" button → installs the agent folder into your | |
| # repository, or upgrades it when a newer version is available. | |
| # Safe to re-run; it installs, upgrades, or skips as appropriate. | |
| workflow_dispatch: | |
| inputs: | |
| function: | |
| description: "Workflow function to run" | |
| required: false | |
| default: run-install | |
| type: choice | |
| options: | |
| - run-install | |
| - run-refresh-gstack | |
| # 6. Scheduled triggers for automated skills: | |
| # • Friday 5pm UTC → /retro (weekly retrospective) | |
| # • Daily 6am UTC → /benchmark (daily benchmark run, if enabled) | |
| schedule: | |
| - cron: '0 17 * * 5' # Every Friday at 5 PM UTC → /retro (weekly retrospective). | |
| - cron: '0 6 * * *' # Every day at 6 AM UTC → /benchmark (daily benchmark, if enabled). | |
| # 7. A release is published → /document-release skill updates documentation. | |
| release: | |
| types: [published] | |
| # 8. A deployment succeeds → /canary skill runs post-deployment monitoring. | |
| deployment_status: | |
| # ────────────────────────────────────────────────────────────────────────────── | |
| # PERMISSIONS | |
| # These are the minimum permissions the workflow needs. GitHub Actions uses | |
| # a least-privilege model; each permission listed here is required for a | |
| # specific reason documented below. | |
| # ────────────────────────────────────────────────────────────────────────────── | |
| permissions: | |
| contents: write # Commit agent responses, session state, and installed files to the repo. | |
| issues: write # Post AI replies as issue comments and add reaction indicators (🚀 / 👍). | |
| pull-requests: write # Post review findings as PR comments and add reaction indicators. | |
| actions: write # Allow the run-install job to push commits that subsequently trigger workflows. | |
| pages: write # Upload and deploy the agent's public-fabric site to GitHub Pages. | |
| id-token: write # Required by actions/deploy-pages for secure OIDC-based Pages deployment. | |
| # ══════════════════════════════════════════════════════════════════════════════ | |
| # JOBS | |
| # ══════════════════════════════════════════════════════════════════════════════ | |
| jobs: | |
| # ──────────────────────────────────────────────────────────────────────────── | |
| # JOB 1 — run-install | |
| # | |
| # Purpose : Self-installer and upgrader. Downloads the latest agent folder | |
| # from the template repository and commits it into YOUR repo. | |
| # If the agent is already installed at the latest version, it skips. | |
| # Trigger : workflow_dispatch (manual "Run workflow" button only). | |
| # Safe : Re-running is always safe — it installs, upgrades, or skips. | |
| # ──────────────────────────────────────────────────────────────────────────── | |
| run-install: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 10 # Prevent runaway downloads or git operations from burning CI minutes. | |
| # Only run when triggered manually via the Actions UI. | |
| # Skip when running inside the template repository itself — the run-install job | |
| # downloads FROM that repo, so running it there would be self-referential. | |
| if: >- | |
| github.event_name == 'workflow_dispatch' | |
| && github.event.inputs.function == 'run-install' | |
| && github.repository != 'japer-technology/github-gstack-intelligence' | |
| steps: | |
| # 1. Check out the repository so we can inspect and modify its contents. | |
| - name: Checkout | |
| uses: actions/checkout@v6 | |
| with: | |
| # Always operate on the default branch (usually "main"). | |
| ref: ${{ github.event.repository.default_branch }} | |
| # 2. Determine whether to install, upgrade, or skip. | |
| # • No folder → action=install | |
| # • Folder present, local VERSION < template VERSION → action=upgrade | |
| # • Folder present, local VERSION >= template VERSION → action=skip | |
| - name: Check for .github-gstack-intelligence | |
| id: check-folder | |
| run: | | |
| if [ ! -d ".github-gstack-intelligence" ]; then | |
| echo "action=install" >> "$GITHUB_OUTPUT" | |
| echo "📦 .github-gstack-intelligence not found — will install." | |
| else | |
| LOCAL_VERSION="0.0.0" | |
| if [ -f ".github-gstack-intelligence/VERSION" ]; then | |
| LOCAL_VERSION=$(tr -d '[:space:]' < .github-gstack-intelligence/VERSION) | |
| fi | |
| # Fetch only the VERSION file from the template repository. | |
| REMOTE_VERSION=$(curl -fsSL "https://raw.githubusercontent.com/japer-technology/github-gstack-intelligence/main/.github-gstack-intelligence/VERSION" | tr -d '[:space:]' || true) | |
| if [ -z "$REMOTE_VERSION" ]; then | |
| echo "::warning::Could not fetch remote VERSION — skipping upgrade check." | |
| echo "action=skip" >> "$GITHUB_OUTPUT" | |
| exit 0 | |
| fi | |
| echo "Local VERSION: $LOCAL_VERSION" | |
| echo "Remote VERSION: $REMOTE_VERSION" | |
| # Validate that both versions look like semver (digits and dots). | |
| SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+$' | |
| if ! [[ "$LOCAL_VERSION" =~ $SEMVER_RE ]] || ! [[ "$REMOTE_VERSION" =~ $SEMVER_RE ]]; then | |
| echo "::warning::VERSION format is not valid semver — skipping upgrade check." | |
| echo "action=skip" >> "$GITHUB_OUTPUT" | |
| exit 0 | |
| fi | |
| # Compare semver components (major.minor.patch). | |
| IFS='.' read -r L_MAJOR L_MINOR L_PATCH <<< "$LOCAL_VERSION" | |
| IFS='.' read -r R_MAJOR R_MINOR R_PATCH <<< "$REMOTE_VERSION" | |
| NEEDS_UPGRADE=false | |
| if [ "$R_MAJOR" -gt "$L_MAJOR" ]; then | |
| NEEDS_UPGRADE=true | |
| elif [ "$R_MAJOR" -eq "$L_MAJOR" ] && [ "$R_MINOR" -gt "$L_MINOR" ]; then | |
| NEEDS_UPGRADE=true | |
| elif [ "$R_MAJOR" -eq "$L_MAJOR" ] && [ "$R_MINOR" -eq "$L_MINOR" ] && [ "$R_PATCH" -gt "$L_PATCH" ]; then | |
| NEEDS_UPGRADE=true | |
| fi | |
| if [ "$NEEDS_UPGRADE" = true ]; then | |
| echo "action=upgrade" >> "$GITHUB_OUTPUT" | |
| echo "⬆️ Upgrade available: $LOCAL_VERSION → $REMOTE_VERSION" | |
| else | |
| echo "action=skip" >> "$GITHUB_OUTPUT" | |
| echo "✅ Local version ($LOCAL_VERSION) >= remote version ($REMOTE_VERSION) — nothing to do." | |
| fi | |
| fi | |
| # 3. Download the template repository as a zip, extract it, and apply | |
| # install or upgrade rules. | |
| # On fresh install: copies the agent folder and initialises defaults. | |
| # On upgrade: walks the template file-by-file using three categories: | |
| # ALWAYS overwrite — framework code (lifecycle/, skills/, etc.) | |
| # NEVER overwrite — user-customisable files (config, state, etc.) | |
| # DEFAULT — copy only if the file is new locally | |
| # This ensures user additions and modifications are never lost, even | |
| # for files outside the explicit preserve list. | |
| - name: Download and install from template | |
| if: steps.check-folder.outputs.action != 'skip' | |
| env: | |
| INSTALL_ACTION: ${{ steps.check-folder.outputs.action }} | |
| run: | | |
| set -euo pipefail | |
| ACTION="$INSTALL_ACTION" | |
| TARGET=".github-gstack-intelligence" | |
| # Download the latest template from the main branch. | |
| curl -fsSL "https://github.com/japer-technology/github-gstack-intelligence/archive/refs/heads/main.zip" \ | |
| -o /tmp/template.zip | |
| unzip -q /tmp/template.zip -d /tmp/template | |
| EXTRACTED=$(ls -d /tmp/template/github-gstack-intelligence-*) | |
| # Remove items from the extracted template that must not be copied | |
| # into the user's repo (heavy dependencies and internal analysis). | |
| rm -rf "$EXTRACTED/$TARGET/node_modules" | |
| rm -rf "$EXTRACTED/$TARGET/docs/analysis" | |
| rm -rf "$EXTRACTED/$TARGET/public-fabric" | |
| if [ "$ACTION" = "upgrade" ]; then | |
| # ── File-by-file upgrade ──────────────────────────────────── | |
| # | |
| # Instead of deleting everything and restoring backups, we walk | |
| # through the template file-by-file and apply upgrade rules. | |
| # Files that exist locally but are NOT in the ALWAYS-overwrite | |
| # list are left untouched — the user may have modified them on | |
| # purpose, or added new files since the last install. | |
| # ──────────────────────────────────────────────────────────── | |
| # Remove source repo's session state from the template so it is | |
| # never copied — the "never" category alone is not enough because | |
| # it copies template files when they don't exist locally. | |
| rm -rf "$EXTRACTED/$TARGET/state" | |
| echo "── Upgrade: processing template files ──" | |
| while IFS= read -r relpath; do | |
| relpath="${relpath#./}" | |
| SRC="$EXTRACTED/$TARGET/$relpath" | |
| DST="$TARGET/$relpath" | |
| # ── Classify the file ── | |
| # "always" takes precedence: checked first, then "never" only | |
| # applies if the file was not already classified as "always". | |
| CATEGORY="default" | |
| # Always overwrite: framework code that must stay current. | |
| case "$relpath" in | |
| lifecycle/*) CATEGORY="always" ;; | |
| skills/*) CATEGORY="always" ;; | |
| package.json) CATEGORY="always" ;; | |
| bun.lock) CATEGORY="always" ;; | |
| VERSION) CATEGORY="always" ;; | |
| esac | |
| # Never overwrite: user customisations that must be preserved. | |
| if [ "$CATEGORY" = "default" ]; then | |
| case "$relpath" in | |
| config.json) CATEGORY="never" ;; | |
| AGENTS.md) CATEGORY="never" ;; | |
| .pi/settings.json) CATEGORY="never" ;; | |
| .pi/APPEND_SYSTEM.md) CATEGORY="never" ;; | |
| .pi/BOOTSTRAP.md) CATEGORY="never" ;; | |
| state/*) CATEGORY="never" ;; | |
| esac | |
| fi | |
| # ── Apply the rule ── | |
| case "$CATEGORY" in | |
| always) | |
| mkdir -p "$(dirname "$DST")" | |
| cp "$SRC" "$DST" | |
| echo " ↻ overwrite $relpath" | |
| ;; | |
| never) | |
| if [ -f "$DST" ]; then | |
| echo " ✓ preserve $relpath" | |
| else | |
| mkdir -p "$(dirname "$DST")" | |
| cp "$SRC" "$DST" | |
| echo " + new $relpath (default from template)" | |
| fi | |
| ;; | |
| default) | |
| if [ -f "$DST" ]; then | |
| echo " · skip $relpath (exists locally — may be customised)" | |
| else | |
| mkdir -p "$(dirname "$DST")" | |
| cp "$SRC" "$DST" | |
| echo " + new $relpath" | |
| fi | |
| ;; | |
| esac | |
| done < <( cd "$EXTRACTED/$TARGET" && find . -type f | sort ) | |
| echo "── Upgrade complete ──" | |
| else | |
| # Fresh install. | |
| cp -R "$EXTRACTED/$TARGET" "$TARGET" | |
| # Remove the source repo's session state — each repo starts fresh. | |
| rm -rf "$TARGET/state" | |
| # Initialise defaults for a fresh install: | |
| # • AGENTS.md — the agent's identity file (editable by the user). | |
| # • settings.json — default LLM provider and model configuration. | |
| cp "$TARGET/install/GSTACK-INTELLIGENCE-AGENTS.md" "$TARGET/AGENTS.md" | |
| mkdir -p "$TARGET/.pi" | |
| cp "$TARGET/install/settings.json" "$TARGET/.pi/settings.json" | |
| fi | |
| # 4. Ensure common ignore patterns are present in .gitignore so that | |
| # node_modules and OS junk files never get committed. | |
| - name: Ensure .gitignore entries | |
| if: steps.check-folder.outputs.action != 'skip' | |
| run: | | |
| touch .gitignore | |
| for entry in "node_modules/" ".github-gstack-intelligence/node_modules/" ".DS_Store"; do | |
| grep -qxF "$entry" .gitignore || echo "$entry" >> .gitignore | |
| done | |
| # 4b. Ensure required Git attributes are present in .gitattributes so | |
| # that the append-only memory log merges correctly across parallel | |
| # agent runs (union merge driver). | |
| - name: Ensure .gitattributes entries | |
| if: steps.check-folder.outputs.action != 'skip' | |
| run: | | |
| touch .gitattributes | |
| for entry in "memory.log merge=union"; do | |
| grep -qxF "$entry" .gitattributes || echo "$entry" >> .gitattributes | |
| done | |
| # 5. Commit and push. Uses the appropriate message for install vs upgrade. | |
| # If nothing changed (edge case), the step is a harmless no-op. | |
| - name: Commit and push | |
| if: steps.check-folder.outputs.action != 'skip' | |
| env: | |
| INSTALL_ACTION: ${{ steps.check-folder.outputs.action }} | |
| run: | | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| git add .github-gstack-intelligence/ .gitignore .gitattributes | |
| if [ "$INSTALL_ACTION" = "upgrade" ]; then | |
| COMMIT_MSG="chore: upgrade .github-gstack-intelligence from template" | |
| else | |
| COMMIT_MSG="chore: install .github-gstack-intelligence from template" | |
| fi | |
| if git diff --cached --quiet; then | |
| echo "No changes to commit." | |
| else | |
| git commit -m "$COMMIT_MSG" | |
| git push | |
| fi | |
| # ──────────────────────────────────────────────────────────────────────────── | |
| # JOB 1b — run-refresh-gstack | |
| # | |
| # Purpose : Refresh the extracted gstack resources that live inside the | |
| # installed .github-gstack-intelligence folder. | |
| # Trigger : workflow_dispatch with function=run-refresh-gstack. | |
| # ──────────────────────────────────────────────────────────────────────────── | |
| run-refresh-gstack: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 10 # Prevent hung refresh operations from burning CI minutes. | |
| if: >- | |
| github.event_name == 'workflow_dispatch' | |
| && github.event.inputs.function == 'run-refresh-gstack' | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v6 | |
| with: | |
| ref: ${{ github.event.repository.default_branch }} | |
| - name: Check for .github-gstack-intelligence | |
| id: check-folder | |
| run: | | |
| if [ -d ".github-gstack-intelligence" ]; then | |
| echo "exists=true" >> "$GITHUB_OUTPUT" | |
| else | |
| echo "exists=false" >> "$GITHUB_OUTPUT" | |
| echo "::error::.github-gstack-intelligence folder not found." | |
| exit 1 | |
| fi | |
| - name: Setup Bun | |
| if: steps.check-folder.outputs.exists == 'true' | |
| uses: oven-sh/setup-bun@v2 | |
| with: | |
| bun-version: "1.2" | |
| - name: Run refresh | |
| if: steps.check-folder.outputs.exists == 'true' | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| run: bun .github-gstack-intelligence/lifecycle/refresh.ts | |
| - name: Verify refreshed gstack files | |
| if: steps.check-folder.outputs.exists == 'true' | |
| run: | | |
| python3 - <<'PY' | |
| import json | |
| import pathlib | |
| import sys | |
| root = pathlib.Path(".github-gstack-intelligence") | |
| metadata_path = root / "skills" / "source.json" | |
| if not metadata_path.exists(): | |
| print("::error::Missing .github-gstack-intelligence/skills/source.json after refresh.") | |
| sys.exit(1) | |
| metadata = json.loads(metadata_path.read_text()) | |
| # Validate source metadata. | |
| source = metadata.get("source", {}) | |
| if not source.get("repo"): | |
| print("::error::source.json is missing a valid 'source.repo' field.") | |
| sys.exit(1) | |
| if not source.get("ref"): | |
| print("::error::source.json is missing a valid 'source.ref' field.") | |
| sys.exit(1) | |
| if not source.get("commit"): | |
| print("::warning::source.json has no resolved commit SHA — using ref only.") | |
| inputs = metadata.get("inputs", []) | |
| outputs = metadata.get("outputs", []) | |
| if not inputs: | |
| print("::error::Refresh metadata does not list any checked gstack source files.") | |
| sys.exit(1) | |
| if not outputs: | |
| print("::error::Refresh metadata does not list any copied files.") | |
| sys.exit(1) | |
| GENERATED_MARKER = "<!-- GSTACK-INTELLIGENCE: GENERATED FILE -->" | |
| DO_NOT_TOUCH = "Do not touch" | |
| missing_outputs = [] | |
| unmarked_outputs = [] | |
| unwarned_outputs = [] | |
| empty_outputs = [] | |
| for relative_path in outputs: | |
| output_path = root / relative_path | |
| if not output_path.exists(): | |
| missing_outputs.append(relative_path) | |
| continue | |
| content = output_path.read_text() | |
| if len(content) < 50: | |
| empty_outputs.append(relative_path) | |
| continue | |
| if output_path.suffix == ".md": | |
| if GENERATED_MARKER not in content: | |
| unmarked_outputs.append(relative_path) | |
| if DO_NOT_TOUCH not in content: | |
| unwarned_outputs.append(relative_path) | |
| if missing_outputs: | |
| print(f"::error::Refresh is missing copied gstack files: {', '.join(missing_outputs)}") | |
| sys.exit(1) | |
| if empty_outputs: | |
| print(f"::error::Refreshed gstack files have no meaningful content: {', '.join(empty_outputs)}") | |
| sys.exit(1) | |
| if unmarked_outputs: | |
| print(f"::error::Generated gstack files are missing the upgrade warning marker: {', '.join(unmarked_outputs)}") | |
| sys.exit(1) | |
| if unwarned_outputs: | |
| print(f"::error::Generated gstack files are missing the 'Do not touch' warning: {', '.join(unwarned_outputs)}") | |
| sys.exit(1) | |
| print(f"✅ Validated {len(inputs)} upstream gstack files → {len(outputs)} copied outputs.") | |
| print(f" Source: {source.get('repo')} @ {source.get('commit', source.get('ref'))}") | |
| print(f" All outputs exist, have content, the generated marker, and the 'Do not touch' warning.") | |
| PY | |
| - name: Commit and push refreshed resources | |
| if: steps.check-folder.outputs.exists == 'true' | |
| run: | | |
| git config user.name "github-actions[bot]" | |
| git config user.email "github-actions[bot]@users.noreply.github.com" | |
| git add .github-gstack-intelligence/ | |
| if git diff --cached --quiet; then | |
| echo "No refresh changes to commit." | |
| else | |
| git commit -m "chore: refresh gstack resources" | |
| git push | |
| fi | |
| # ──────────────────────────────────────────────────────────────────────────── | |
| # JOB 2 — run-agent | |
| # | |
| # Purpose : The core AI agent. Reads the issue (or comment, PR, schedule, | |
| # release, or deployment event), loads the conversation session | |
| # from git, sends it to the configured LLM, and posts the response | |
| # back as a comment. For PRs, the /review or /cso skill is invoked | |
| # and findings appear as PR comments. For scheduled events, skills | |
| # like /retro and /benchmark run automatically. | |
| # Trigger : issues.opened, issue_comment.created, pull_request.opened/synchronize, | |
| # schedule, release.published, OR deployment_status (success). | |
| # Security: Only collaborators with write/maintain/admin access can trigger | |
| # (schedule/release/deployment events bypass actor checks). | |
| # ──────────────────────────────────────────────────────────────────────────── | |
| run-agent: | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 30 # LLM calls may take minutes; 30 min cap prevents runaway billing. | |
| # Concurrency: one agent run per target (issue or PR) at a time. | |
| # For issues: the second comment waits for the first to finish (cancel-in-progress: false). | |
| # For PRs: a new push cancels the previous review (cancel-in-progress via expression). | |
| # For schedule/release/deployment_status: one run per event type at a time. | |
| concurrency: | |
| group: >- | |
| github-gstack-intelligence-${{ github.repository }}-${{ | |
| github.event_name == 'pull_request' | |
| && format('pr-{0}', github.event.pull_request.number) | |
| || github.event_name == 'schedule' | |
| && format('schedule-{0}', github.event.schedule) | |
| || github.event_name == 'release' | |
| && format('release-{0}', github.event.release.tag_name) | |
| || github.event_name == 'deployment_status' | |
| && format('deploy-{0}', github.event.deployment.id) | |
| || format('issue-{0}', github.event.issue.number) | |
| }} | |
| cancel-in-progress: ${{ github.event_name == 'pull_request' }} | |
| # Trigger guard: | |
| # • Run on new issues. | |
| # • Run on issue comments, BUT skip comments posted by bots (the agent | |
| # itself) to avoid infinite loops, AND skip comments on pull requests | |
| # (issue_comment fires for both issues and PRs). | |
| # • Run on pull_request events (opened, synchronize), skipping bot-authored PRs. | |
| # • Run on schedule events (no actor check — runs as github-actions). | |
| # • Run on release events (published). | |
| # • Run on deployment_status events (only successful deployments). | |
| # • Reject the github-actions actor (both 'github-actions' and | |
| # 'github-actions[bot]') for non-scheduled/release/deployment events | |
| # to prevent bot-loop escalation. | |
| if: >- | |
| (github.event_name == 'schedule') | |
| || (github.event_name == 'release') | |
| || (github.event_name == 'deployment_status' && github.event.deployment_status.state == 'success') | |
| || ( | |
| github.actor != 'github-actions' | |
| && github.actor != 'github-actions[bot]' | |
| && ( | |
| (github.event_name == 'issues') | |
| || (github.event_name == 'issue_comment' && !github.event.issue.pull_request && !endsWith(github.event.comment.user.login, '[bot]')) | |
| || (github.event_name == 'pull_request' && !endsWith(github.event.pull_request.user.login, '[bot]')) | |
| ) | |
| ) | |
| steps: | |
| # 1. AUTHORIZATION — verify the actor has write-level (or higher) access | |
| # to the repository. This prevents random users on public repos from | |
| # consuming your LLM credits. On success a 🚀 reaction is added to | |
| # signal the agent is working; the reaction state is saved to a temp | |
| # file so the agent can later replace it with 👍 on completion. | |
| - name: Authorize | |
| id: authorize | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| # ── Pass GitHub context through environment variables ────────── | |
| # Avoids direct ${{ }} interpolation in shell code, which is an | |
| # expression-injection vector when values are attacker-controlled. | |
| # These specific values are GitHub-controlled (not user input), but | |
| # using env vars is a defence-in-depth best practice. | |
| EVENT_NAME: ${{ github.event_name }} | |
| ACTOR: ${{ github.actor }} | |
| REPO: ${{ github.repository }} | |
| COMMENT_ID: ${{ github.event.comment.id }} | |
| ISSUE_NUMBER: ${{ github.event.issue.number }} | |
| PR_NUMBER: ${{ github.event.pull_request.number }} | |
| run: | | |
| # Schedule, release, and deployment_status events have no human actor — | |
| # the workflow runs as github-actions. Skip authorization for these. | |
| if [[ "$EVENT_NAME" == "schedule" || "$EVENT_NAME" == "release" || "$EVENT_NAME" == "deployment_status" ]]; then | |
| echo "::notice::${EVENT_NAME} trigger — no actor authorization needed" | |
| exit 0 | |
| fi | |
| # Query the GitHub API for the actor's permission level on this repo. | |
| PERM=$(gh api "repos/${REPO}/collaborators/${ACTOR}/permission" --jq '.permission' 2>/dev/null || echo "none") | |
| echo "Actor: ${ACTOR}, Permission: $PERM" | |
| # Reject anyone below write access. | |
| if [[ "$PERM" != "admin" && "$PERM" != "maintain" && "$PERM" != "write" ]]; then | |
| echo "::error::Unauthorized: ${ACTOR} has '$PERM' permission" | |
| exit 1 | |
| fi | |
| # Add a 🚀 "rocket" reaction to the comment, issue, or PR as a visual | |
| # indicator that the agent has started processing. Save the reaction | |
| # ID so the agent can swap it for 👍 when it finishes. | |
| # Use jq for safe JSON construction — handles empty/null values without | |
| # producing malformed output. | |
| if [[ "$EVENT_NAME" == "issue_comment" ]]; then | |
| REACTION_ID=$(gh api "repos/${REPO}/issues/comments/${COMMENT_ID}/reactions" -f content=rocket --jq '.id' 2>/dev/null || echo "") | |
| jq -n \ | |
| --arg rid "$REACTION_ID" \ | |
| --arg cid "$COMMENT_ID" \ | |
| --arg inum "$ISSUE_NUMBER" \ | |
| --arg repo "$REPO" \ | |
| '{reactionId: (if $rid == "" then null else $rid end), reactionTarget: "comment", commentId: ($cid | tonumber), issueNumber: ($inum | tonumber), repo: $repo}' \ | |
| > /tmp/reaction-state.json | |
| elif [[ "$EVENT_NAME" == "pull_request" ]]; then | |
| # PRs are issues in GitHub — use the issues reactions API with the PR number. | |
| REACTION_ID=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/reactions" -f content=rocket --jq '.id' 2>/dev/null || echo "") | |
| jq -n \ | |
| --arg rid "$REACTION_ID" \ | |
| --arg prnum "$PR_NUMBER" \ | |
| --arg repo "$REPO" \ | |
| '{reactionId: (if $rid == "" then null else $rid end), reactionTarget: "issue", commentId: null, issueNumber: ($prnum | tonumber), repo: $repo}' \ | |
| > /tmp/reaction-state.json | |
| else | |
| REACTION_ID=$(gh api "repos/${REPO}/issues/${ISSUE_NUMBER}/reactions" -f content=rocket --jq '.id' 2>/dev/null || echo "") | |
| jq -n \ | |
| --arg rid "$REACTION_ID" \ | |
| --arg inum "$ISSUE_NUMBER" \ | |
| --arg repo "$REPO" \ | |
| '{reactionId: (if $rid == "" then null else $rid end), reactionTarget: "issue", commentId: null, issueNumber: ($inum | tonumber), repo: $repo}' \ | |
| > /tmp/reaction-state.json | |
| fi | |
| # 2. REJECTION FEEDBACK — if authorization failed, add a 👎 reaction so | |
| # the user gets immediate visual feedback that their request was denied. | |
| - name: Reject | |
| if: failure() && steps.authorize.outcome == 'failure' | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| EVENT_NAME: ${{ github.event_name }} | |
| REPO: ${{ github.repository }} | |
| COMMENT_ID: ${{ github.event.comment.id }} | |
| ISSUE_NUMBER: ${{ github.event.issue.number }} | |
| PR_NUMBER: ${{ github.event.pull_request.number }} | |
| run: | | |
| if [[ "$EVENT_NAME" == "issue_comment" ]]; then | |
| gh api "repos/${REPO}/issues/comments/${COMMENT_ID}/reactions" -f content=-1 | |
| elif [[ "$EVENT_NAME" == "pull_request" ]]; then | |
| gh api "repos/${REPO}/issues/${PR_NUMBER}/reactions" -f content=-1 | |
| else | |
| gh api "repos/${REPO}/issues/${ISSUE_NUMBER}/reactions" -f content=-1 | |
| fi | |
| # 3. CHECKOUT — clone the full repository (fetch-depth: 0) so the agent | |
| # can read prior session history, project files, and commit new state. | |
| - name: Checkout | |
| uses: actions/checkout@v6 | |
| with: | |
| ref: ${{ github.event.repository.default_branch }} | |
| fetch-depth: 0 # Full history needed — the agent reads and commits session state. | |
| # 4. SAFETY CHECK — ensure the agent folder exists. If the user hasn't | |
| # run the run-install job yet, skip gracefully instead of crashing. | |
| - name: Check for .github-gstack-intelligence | |
| id: check-folder | |
| run: | | |
| if [ -d ".github-gstack-intelligence" ]; then | |
| echo "exists=true" >> "$GITHUB_OUTPUT" | |
| else | |
| echo "exists=false" >> "$GITHUB_OUTPUT" | |
| echo "::notice::.github-gstack-intelligence folder not found, skipping." | |
| fi | |
| # 5. RUNTIME — install Bun, a fast JavaScript/TypeScript runtime. The | |
| # agent code (lifecycle/agent.ts) runs directly under Bun without a | |
| # separate compile step. | |
| - name: Setup Bun | |
| if: steps.check-folder.outputs.exists == 'true' | |
| uses: oven-sh/setup-bun@v2 | |
| with: | |
| bun-version: "1.2" # Pinned for reproducible builds across runs. | |
| # 6. CACHE — restore node_modules from a prior run when bun.lock hasn't | |
| # changed. Shaves ~5-10 seconds off the typical cold-start install. | |
| - name: Cache dependencies | |
| if: steps.check-folder.outputs.exists == 'true' | |
| uses: actions/cache@v5 | |
| with: | |
| path: .github-gstack-intelligence/node_modules | |
| key: gsi-deps-${{ hashFiles('.github-gstack-intelligence/bun.lock') }} | |
| # 7. INSTALL — install (or verify) the agent's npm dependencies. | |
| # --frozen-lockfile ensures the lockfile is never modified, so builds | |
| # are deterministic. | |
| - name: Install dependencies | |
| if: steps.check-folder.outputs.exists == 'true' | |
| run: cd .github-gstack-intelligence && bun install --frozen-lockfile | |
| # 8. PLAYWRIGHT (CONDITIONAL) — install the Chromium browser only when | |
| # a browser-based skill is being invoked (/qa, /qa-only, /design-review, | |
| # /canary). Adds ~30s and ~200MB to the runner, so we skip it for all | |
| # other skills to keep runs fast. | |
| # IMPORTANT: the playwright version is read from package.json to stay | |
| # in sync with the installed playwright-core dependency. A version | |
| # mismatch would download an incompatible Chromium binary. | |
| - name: Install Playwright (conditional) | |
| if: >- | |
| steps.check-folder.outputs.exists == 'true' | |
| && ( | |
| (github.event_name == 'issue_comment' && ( | |
| startsWith(github.event.comment.body, '/qa ') | |
| || startsWith(github.event.comment.body, '/qa-only ') | |
| || startsWith(github.event.comment.body, '/design-review') | |
| || startsWith(github.event.comment.body, '/canary') | |
| )) | |
| || github.event_name == 'deployment_status' | |
| ) | |
| env: | |
| PLAYWRIGHT_BROWSERS_PATH: /ms-playwright | |
| run: | | |
| # Read the playwright-core version from package.json so the CLI | |
| # downloads the exact Chromium build that matches the library. | |
| PKG=".github-gstack-intelligence/package.json" | |
| if [ ! -f "$PKG" ]; then | |
| echo "::error::${PKG} not found — cannot determine playwright-core version." | |
| exit 1 | |
| fi | |
| PW_VERSION=$(node -e " | |
| const deps = require('./${PKG}').dependencies || {}; | |
| const v = deps['playwright-core']; | |
| if (!v) { console.error('playwright-core not found in ${PKG}'); process.exit(1); } | |
| console.log(v); | |
| ") | |
| echo "Installing Playwright CLI @ ${PW_VERSION} (matching playwright-core dependency)" | |
| npx "playwright@${PW_VERSION}" install chromium --with-deps | |
| # 9. RUN THE AGENT — execute the core agent script. It reads the | |
| # triggering issue/comment, loads the matching conversation session, | |
| # calls the configured LLM, posts the reply, and commits state. | |
| # | |
| # The `--route` flag enables the event router: slash commands, label | |
| # routing, and skill-aware execution. Without it, all events go | |
| # through general conversation. | |
| # | |
| # All supported LLM provider keys are passed as environment variables. | |
| # Only the key for your chosen provider needs to be set as a secret; | |
| # the others will simply be empty and are safely ignored. | |
| - name: Run | |
| if: steps.check-folder.outputs.exists == 'true' | |
| env: | |
| ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} | |
| OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} | |
| GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }} | |
| XAI_API_KEY: ${{ secrets.XAI_API_KEY }} | |
| OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }} | |
| MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }} | |
| GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }} | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| PLAYWRIGHT_BROWSERS_PATH: /ms-playwright | |
| run: bun .github-gstack-intelligence/lifecycle/agent.ts --route | |
| # ──────────────────────────────────────────────────────────────────────────── | |
| # JOB 3 — run-gitpages | |
| # | |
| # Purpose : Publish the agent's public-fabric directory as a GitHub Pages | |
| # site. This gives you a live web page powered by the agent's | |
| # public output — no separate hosting needed. | |
| # Trigger : push to main (i.e. after the agent commits, or any manual push). | |
| # Note : Pages is automatically enabled on first run. If auto-enable | |
| # fails, a warning guides the user to enable it manually. | |
| # ──────────────────────────────────────────────────────────────────────────── | |
| run-gitpages: | |
| # Run after agent/install jobs finish. On push events those jobs are | |
| # skipped so run-gitpages starts immediately. | |
| needs: [run-agent, run-install, run-refresh-gstack] | |
| # always() ensures the job runs even when upstream jobs are skipped; | |
| # !cancelled() still respects manual cancellation. | |
| if: always() && !cancelled() | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 10 # Pages uploads are small; 10 min cap prevents stuck deployments. | |
| # Concurrency: only one Pages deployment at a time across the entire repo. | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| # Declare the GitHub Pages deployment environment so the workflow run UI | |
| # shows a direct link to the deployed site. | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| # 1. Check out the repo so we can read the public-fabric directory. | |
| # ref: main ensures we pick up any commits the agent just pushed. | |
| - name: Checkout | |
| uses: actions/checkout@v6 | |
| with: | |
| ref: main | |
| # 2. Verify the public-fabric directory exists. If the agent has not | |
| # been installed yet (e.g. on a fresh template repo) there is nothing | |
| # to deploy, so we abort early with a clear warning instead of | |
| # failing in a later step. | |
| - name: Check public-fabric exists | |
| id: check-folder | |
| run: | | |
| if [ -d ".github-gstack-intelligence/public-fabric" ]; then | |
| echo "folder_exists=true" >> "$GITHUB_OUTPUT" | |
| echo "✅ public-fabric directory found." | |
| else | |
| echo "folder_exists=false" >> "$GITHUB_OUTPUT" | |
| echo "::warning::Directory .github-gstack-intelligence/public-fabric not found. Skipping Pages deployment. Run the installer first (Actions → Run workflow)." | |
| fi | |
| # 3. AUTO-ENABLE Pages — attempt to enable GitHub Pages via the API. | |
| # This is a convenience so users don't have to visit Settings manually. | |
| # If the API call fails (e.g. insufficient org permissions), a warning | |
| # is surfaced and the remaining deploy steps are skipped gracefully. | |
| - name: Enable Pages | |
| if: steps.check-folder.outputs.folder_exists == 'true' | |
| id: enable-pages | |
| env: | |
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | |
| REPO: ${{ github.repository }} | |
| run: | | |
| # Check if Pages is already active. | |
| if gh api "repos/${REPO}/pages" --silent 2>/dev/null; then | |
| echo "pages_active=true" >> "$GITHUB_OUTPUT" | |
| echo "✅ GitHub Pages is already enabled." | |
| # If not, try to enable it with the "workflow" build type. | |
| elif gh api "repos/${REPO}/pages" \ | |
| -X POST -f build_type=workflow --silent 2>/dev/null; then | |
| echo "pages_active=true" >> "$GITHUB_OUTPUT" | |
| echo "✅ GitHub Pages has been enabled." | |
| else | |
| echo "pages_active=false" >> "$GITHUB_OUTPUT" | |
| echo "::warning::Could not enable GitHub Pages automatically. Please enable it manually in repository Settings → Pages → Source → GitHub Actions." | |
| fi | |
| # 4. Configure Pages — sets up the required Pages metadata. | |
| - name: Setup Pages | |
| if: steps.check-folder.outputs.folder_exists == 'true' && steps.enable-pages.outputs.pages_active == 'true' | |
| uses: actions/configure-pages@v5 | |
| # 5. Upload the public-fabric directory as a Pages artifact. | |
| - name: Upload artifact | |
| if: steps.check-folder.outputs.folder_exists == 'true' && steps.enable-pages.outputs.pages_active == 'true' | |
| uses: actions/upload-pages-artifact@v4 | |
| with: | |
| path: '.github-gstack-intelligence/public-fabric' | |
| # 6. Deploy the uploaded artifact to GitHub Pages. | |
| - name: Deploy to GitHub Pages | |
| if: steps.check-folder.outputs.folder_exists == 'true' && steps.enable-pages.outputs.pages_active == 'true' | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |