From 992bac5e350221ee9319c34570a6f9ec56ec569e Mon Sep 17 00:00:00 2001 From: Layout Spec Maintainer Date: Wed, 4 Feb 2026 07:29:13 +0000 Subject: [PATCH] Update layout specification - February 04, 2026 - Analyzed 145 lock files (up from 137) - Documented 30 unique GitHub Actions (up from 25) - Cataloged 18 artifact names (up from 17) - Listed 24 common job names (up from 20) - Added comprehensive Step IDs section with 30+ entries - Expanded file paths section with 50+ patterns - Added environment variables reference - Added Go constants and JavaScript patterns - Enhanced usage guidelines with naming conventions - Added pattern analysis and workflow structure diagrams - Improved Docker integration section --- scratchpad/layout.md | 542 ++++++++++++++++++++++++++----------------- 1 file changed, 332 insertions(+), 210 deletions(-) diff --git a/scratchpad/layout.md b/scratchpad/layout.md index 3865d66f77..59bd3e2352 100644 --- a/scratchpad/layout.md +++ b/scratchpad/layout.md @@ -1,277 +1,399 @@ # GitHub Actions Workflow Layout Specification > Auto-generated specification documenting patterns used in compiled `.lock.yml` files. -> Last updated: 2026-01-23 +> Last updated: February 04, 2026 ## Overview -This document catalogs all file paths, folder names, artifact names, and other patterns used across our compiled GitHub Actions workflows (`.lock.yml` files). The specification is based on analysis of **137 lock files** in the `.github/workflows/` directory. +This document catalogs all file paths, folder names, artifact names, and other patterns used across our compiled GitHub Actions workflows (`.lock.yml` files). + +**Compilation Summary:** +- **Lock files analyzed**: 145 +- **Total action uses**: 6,472 +- **Unique actions**: 30 +- **Unique artifacts**: 18 +- **Unique job names**: 24 +- **Step IDs documented**: 30+ ## GitHub Actions -Common GitHub Actions used across workflows (24 unique external actions + 1 local action): - -| Action | Version (SHA) | Description | Context | -|--------|---------------|-------------|---------| -| `./actions/setup` | Local | gh-aw setup action | Used in virtually all workflows to initialize the environment | -| `actions/checkout` | `93cb6efe18208431cddfb8368fd83d5badbf9bfd` | Checks out repository code | Used in almost all workflows for accessing repo content | -| `actions/upload-artifact` | `b7c566a772e6b6bfb58ed0dc250532a479d7789f` | Uploads build artifacts | Used for agent outputs, patches, prompts, and logs | -| `actions/download-artifact` | `018cc2cf5baa6db3ef3c5f8a56943fffe632ef53` | Downloads artifacts from previous jobs | Used in safe-output jobs and conclusion jobs | -| `actions/setup-node` | `395ad3262231945c25e8478fd5baf05154b1d79f` | Sets up Node.js environment | Used in workflows requiring npm/node | -| `actions/setup-node` | `6044e13b5dc448c55e2357c09f80417699197238` | Sets up Node.js environment (alternate version) | Older version still in use | -| `actions/github-script` | `ed597411d8f924073f98dfc5c65a23a2325f34cd` | Runs GitHub API scripts | Used for GitHub API interactions | -| `actions/github-script` | `f28e40c7f34bde8b3046d885e986cb6290c5673b` | Runs GitHub API scripts (alternate version) | Older version still in use | -| `actions/setup-python` | `a26af69be951a213d495a4c3e4e4022e16d87065` | Sets up Python environment | Used in workflows requiring Python | -| `actions/setup-go` | `4dc6199c7b1a012772edbd06daecab0f50c9053c` | Sets up Go environment | Used in workflows requiring Go | -| `actions/setup-go` | `7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5` | Sets up Go environment (alternate version) | Older version still in use | -| `actions/cache` | `0057852bfaa89a56745cba8c7296529d2fc39830` | Cache dependencies | Used to cache dependencies for faster builds | -| `actions/cache/restore` | `0057852bfaa89a56745cba8c7296529d2fc39830` | Restore cached dependencies | Used for partial cache restoration | -| `actions/cache/save` | `0057852bfaa89a56745cba8c7296529d2fc39830` | Save dependencies to cache | Used for partial cache saving | -| `actions/create-github-app-token` | `29824e69f54612133e76f7eaac726eef6c875baf` | Creates GitHub App token | Used for authenticated GitHub API access | -| `actions/ai-inference` | `a6101c89c6feaecc585efdd8d461f18bb7896f20` | AI inference action | Used for AI model inference tasks | -| `astral-sh/setup-uv` | `d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86` | Sets up uv package manager | Used for Python package management | -| `docker/setup-buildx-action` | `8d2750c68a42422c14e847fe6c8ac0403b4cbd6f` | Sets up Docker Buildx | Used for multi-platform Docker builds | -| `docker/login-action` | `c94ce9fb468520275223c153574b00df6fe4bcc9` | Logs in to Docker registry | Used for Docker registry authentication | -| `docker/metadata-action` | `c299e40c65443455700f0fdfc63efafe5b349051` | Extracts Docker metadata | Used for Docker image tagging | -| `docker/build-push-action` | `263435318d21b8e681c14492fe198d362a7d2c83` | Builds and pushes Docker images | Used for containerized workflows | -| `anchore/sbom-action` | `deef08a0db64bfad603422135db61477b16cef56` | Generates Software Bill of Materials | Used for security compliance | -| `github/stale-repos` | `3477b6488008d9411aaf22a0924ec7c1f6a69980` | Identifies stale repositories | Used for repository maintenance | -| `super-linter/super-linter` | `2bdd90ed3262e023ac84bf8fe35dc480721fc1f2` | Lints code across multiple languages | Used for code quality checks | -| `github/gh-aw/actions/setup` | `623e612ff6a684e9a8634449508bdda21e2c178c` | gh-aw setup action (pinned version) | Used for specific workflow versions | +Common GitHub Actions used across workflows: + +| Action | Version/SHA | Description | Context | +|--------|-------------|-------------|---------| +| `./actions/setup` | Local action | Initializes gh-aw runtime environment | Used in virtually all workflows for setting up JavaScript runtime, MCP servers, and safe outputs | +| `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683` | SHA pinned | Checks out repository code at specific commit | Primary version - used in most workflows | +| `actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8` | SHA pinned | Checks out repository code at specific commit | Alternative version for specific workflows | +| `actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd` | SHA pinned | Checks out repository code at specific commit | Another pinned version | +| `actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f` | SHA pinned | Uploads build artifacts | Primary version for artifact uploads | +| `actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02` | SHA pinned | Uploads build artifacts | Alternative artifact upload version | +| `actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53` | SHA pinned | Downloads artifacts from previous jobs | Used in safe-output jobs and conclusion jobs | +| `actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd` | SHA pinned | Runs GitHub API scripts using JavaScript | Primary version for GitHub API interactions | +| `actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b` | SHA pinned | Runs GitHub API scripts | Alternative version | +| `actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f` | SHA pinned | Sets up Node.js environment | Primary version for workflows requiring npm/node | +| `actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238` | SHA pinned | Sets up Node.js environment | Alternative Node.js setup version | +| `actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065` | SHA pinned | Sets up Python environment | Used in Python-based workflows | +| `actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a` | SHA pinned | Sets up Go environment | Primary Go setup version | +| `actions/setup-go@4dc6199c7b1a012772edbd06daecab0f50c9053c` | SHA pinned | Sets up Go environment | Alternative Go version | +| `actions/setup-go@7a3fe6cf4cb3a834922a1244abfce67bcef6a0c5` | SHA pinned | Sets up Go environment | Another Go setup version | +| `actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9` | SHA pinned | Sets up Java environment | Used in Java-based workflows | +| `actions/setup-dotnet@67a3573c9a986a3f9c594539f4ab511d57bb3ce9` | SHA pinned | Sets up .NET environment | Used in .NET-based workflows | +| `actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830` | SHA pinned | Caches dependencies and build outputs | Full cache action | +| `actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830` | SHA pinned | Restores cache only | Used for cache restoration step | +| `actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830` | SHA pinned | Saves cache only | Used for cache saving step | +| `actions/ai-inference@a6101c89c6feaecc585efdd8d461f18bb7896f20` | SHA pinned | AI inference action | Used for AI model integrations | +| `github/gh-aw/actions/setup@623e612ff6a684e9a8634449508bdda21e2c178c` | SHA pinned | Remote reference to setup action | Used in some external workflow references | +| `docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f` | SHA pinned | Sets up Docker Buildx | Used for Docker-based workflows | +| `docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef` | SHA pinned | Logs into Docker registry | Docker authentication | +| `docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051` | SHA pinned | Extracts Docker metadata | Docker image metadata generation | +| `docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83` | SHA pinned | Builds and pushes Docker images | Docker build and publish | +| `astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86` | SHA pinned | Sets up uv (Python package installer) | Modern Python package management | +| `anchore/sbom-action@62ad5284b8ced813296287a0b63906cb364b73ee` | SHA pinned | Generates Software Bill of Materials | Security and compliance | +| `super-linter/super-linter@2bdd90ed3262e023ac84bf8fe35dc480721fc1f2` | SHA pinned | Runs multi-language linting | Code quality checks | +| `github/stale-repos@3477b6488008d9411aaf22a0924ec7c1f6a69980` | SHA pinned | Identifies stale repositories | Repository maintenance | ## Artifact Names -Artifacts uploaded/downloaded between workflow jobs (17 unique artifacts): - -| Name | Upload | Download | Description | Context | -|------|--------|----------|-------------|---------| -| `agent-artifacts` | ✅ | ✅ | Complete agent execution artifacts | Contains all files generated by agent job | -| `agent-output` | ✅ | ✅ | AI agent execution output | Contains the agent's response and analysis | -| `agent_outputs` | ✅ | - | Legacy agent outputs | Older naming convention, still in use | -| `safe-output` | ✅ | - | Safe output processing results | Used for safe-output job results | -| `safe-outputs-assets` | ✅ | ✅ | Safe outputs asset files | Assets for GitHub API operations | -| `cache-memory` | ✅ | ✅ | Cache memory files | Persistent cache across workflow runs | -| `cache-memory-focus-areas` | ✅ | ✅ | Focused cache areas | Specialized cache for specific topics | -| `cache-memory-repo-audits` | ✅ | ✅ | Repository audit cache | Cache for repository analysis | -| `repo-memory-default` | ✅ | ✅ | Default repository memory | Standard repo memory storage | -| `repo-memory-campaigns` | ✅ | ✅ | Campaign repository memory | Memory for campaign workflows | -| `python-source-and-data` | ✅ | - | Python source code and data | Python scripts and datasets | -| `data-charts` | ✅ | - | Data visualization charts | Generated chart images | -| `trending-source-and-data` | ✅ | - | Trending analysis data | Trending analysis results | -| `trending-charts` | ✅ | - | Trending visualization charts | Charts for trending data | -| `sbom-artifacts` | ✅ | - | Software Bill of Materials | Security compliance artifacts | -| `super-linter-log` | ✅ | ✅ | Super-linter execution logs | Code quality check logs | -| `threat-detection.log` | ✅ | - | Security threat detection logs | Security analysis results | +Artifacts uploaded/downloaded between workflow jobs: + +| Name | Type | Description | Context | +|------|------|-------------|---------| +| `agent-output` | Upload/Download | AI agent execution output | Contains the agent's response, analysis, and generated content | +| `agent-artifacts` | Upload | Complete agent execution artifacts | Includes all outputs from agent job | +| `agent_outputs` | Upload | Agent outputs (underscore variant) | Alternative naming for agent outputs | +| `safe-output` | Upload/Download | Safe outputs configuration | Configuration data passed from agent to safe-output jobs | +| `safe-outputs-assets` | Upload/Download | Safe output assets | Files and content generated by safe-output handlers | +| `cache-memory` | Upload/Download | Agent cache memory | Persistent memory for agent across runs | +| `cache-memory-focus-areas` | Upload/Download | Focused cache memory | Domain-specific cache for focus areas | +| `cache-memory-repo-audits` | Upload/Download | Repository audit cache | Cache for repository audit workflows | +| `repo-memory-default` | Upload/Download | Default repository memory | Standard repo memory storage | +| `repo-memory-campaigns` | Upload/Download | Campaign repository memory | Memory for campaign-based workflows | +| `python-source-and-data` | Upload | Python source files and data | Used in Python analysis workflows | +| `data-charts` | Upload | Generated data charts | Visualization outputs from data analysis | +| `trending-charts` | Upload | Trending data visualizations | Chart outputs for trending analysis | +| `trending-source-and-data` | Upload | Trending analysis data | Source data for trending workflows | +| `license-report` | Upload | License compliance report | Generated license analysis results | +| `sbom-artifacts` | Upload | Software Bill of Materials | SBOM generation outputs | +| `super-linter-log` | Upload/Download | Linter execution logs | Logs from super-linter runs | +| `threat-detection.log` | Upload | Security threat detection logs | Security analysis outputs | ## Common Job Names -Standard job names across workflows (20 unique job names): +Standard job names across workflows: | Job Name | Description | Context | |----------|-------------|---------| -| `activation` | Determines if workflow should run | Uses skip-if-match and other filters | -| `pre_activation` | Pre-activation checks | Runs before main activation job | -| `agent` | Main AI agent execution job | Runs the copilot/claude/codex engine | -| `detection` | Post-agent analysis job | Analyzes agent output for patterns | -| `conclusion` | Final status reporting job | Runs after all other jobs complete | -| `safe_outputs` | Safe output processing job | Executes safe-output handlers | -| `config` | Configuration setup job | Initializes workflow configuration | -| `release` | Release management job | Handles release creation/updates | -| `upload_assets` | Asset upload job | Uploads assets to GitHub releases | -| `push_repo_memory` | Repository memory update job | Pushes memory updates to storage | -| `update_cache_memory` | Cache memory update job | Updates cache memory files | -| `check_ci_status` | CI status verification job | Checks CI/CD pipeline status | -| `check_external_user` | External user verification job | Validates external contributor access | -| `test_environment` | Test environment setup job | Prepares testing environment | -| `super_linter` | Code linting job | Runs super-linter for code quality | -| `ast_grep` | AST-based code search job | Searches code using AST patterns | -| `search_issues` | Issue search job | Searches GitHub issues | -| `post-issue` | Post-issue creation job | Creates issues based on workflow results | -| `post_to_slack_channel` | Slack notification job | Posts updates to Slack | -| `notion_add_comment` | Notion integration job | Adds comments to Notion pages | +| `activation` | Determines if workflow should run | Uses skip-if-match, skip-if-no-match, and other filters to conditionally activate workflow | +| `pre_activation` | Pre-flight checks before activation | Early validation and environment checks | +| `agent` | Main AI agent execution job | Runs the copilot/claude/codex engine with configured tools and permissions | +| `detection` | Post-agent analysis job | Analyzes agent output for patterns, safe-outputs, and required follow-up actions | +| `conclusion` | Final status reporting job | Runs after all other jobs complete, reports success/failure, creates summaries | +| `safe_outputs` | Executes safe output operations | Dispatcher job that triggers safe-output handler jobs | +| `add_comment` | Adds comment to issue/PR | Safe-output job for commenting via GitHub API | +| `post-issue` | Posts new GitHub issue | Safe-output job for issue creation | +| `post_to_slack_channel` | Posts message to Slack | Integration with Slack notifications | +| `send_slack_message` | Sends Slack message | Alternative Slack integration pattern | +| `search_issues` | Searches GitHub issues | Query and filter issues based on criteria | +| `notion_add_comment` | Adds comment to Notion | Notion integration for commenting | +| `update_cache_memory` | Updates agent cache memory | Persists agent memory to artifacts | +| `push_repo_memory` | Pushes repository memory | Commits repo memory to git repository | +| `upload_assets` | Uploads generated assets | Handles file uploads to various destinations | +| `check_ci_status` | Checks CI build status | Validates CI pipeline completion | +| `check_external_user` | Validates external user access | Security check for external contributors | +| `config` | Configuration and setup job | Prepares workflow configuration | +| `test_environment` | Tests workflow environment | Validates runtime environment setup | +| `release` | Release management job | Handles version releases and publishing | +| `super_linter` | Runs code linting | Multi-language linting across codebase | +| `license-check` | Validates license compliance | Checks dependency licenses | +| `ast_grep` | AST-based code search | Structural code pattern matching | + +## Step IDs + +Common step IDs used across workflows: + +| Step ID | Description | Context | +|---------|-------------|---------| +| `check_membership` | Checks if user is org member | Security validation in activation job | +| `check_stop_time` | Validates workflow stop time | Prevents workflows from running past configured time | +| `check_skip_if_match` | Conditional skip based on pattern match | Activation filter for pattern-based execution | +| `check_skip_if_no_match` | Conditional skip when pattern doesn't match | Activation filter for required patterns | +| `check_command_position` | Validates command position in text | Checks if agent command is in valid position (start/end/anywhere) | +| `check_actor` | Validates workflow actor | Security check for authorized users | +| `checkout-pr` | Checks out pull request code | PR-specific checkout step | +| `ci_check` | CI status validation | Checks CI pipeline status | +| `agentic_execution` | Main agent execution step | Runs the AI agent with configured engine | +| `generate_aw_info` | Generates workflow info JSON | Creates metadata about workflow execution | +| `create_agent_session` | Creates agent session | Initializes agent execution environment | +| `collect_output` | Collects agent output | Gathers outputs from agent execution | +| `detect` | Detection analysis step | Analyzes outputs for patterns | +| `compute_config` | Computes configuration | Calculates runtime configuration | +| `compute-text` | Computes text output | Processes text-based outputs | +| `conclusion` | Conclusion summary step | Generates final workflow summary | +| `handle_agent_failure` | Handles agent failure | Error handling for agent failures | +| `handle_create_pr_error` | Handles PR creation errors | Error handling for PR creation | +| `missing_tool` | Reports missing tool | Safe-output for missing tool reporting | +| `noop` | No-operation step | Placeholder or completion marker | +| `add-comment` | Adds comment step | Comment addition step | +| `assign_to_agent` | Assigns issue to agent | GitHub issue assignment | +| `lock-issue` | Locks GitHub issue | Issue locking step | +| `build` | Build step | Compilation and build operations | +| `check-cache` | Checks cache availability | Cache validation step | +| `check-results` | Checks operation results | Result validation step | +| `get_release` | Fetches release information | GitHub release data retrieval | +| `determine-automatic-lockdown` | Determines if issue should be locked | Issue lockdown decision logic | +| `opencode` | OpenCode integration step | External tool integration | +| `meta` | Metadata processing step | Workflow metadata handling | ## File Paths Common file paths referenced in workflows: -### Environment Variables (Paths) - -| Path | Description | Context | -|------|-------------|---------| -| `${{ env.GH_AW_AGENT_OUTPUT }}` | Agent output environment variable | Dynamic path to agent output | -| `${{ env.GH_AW_SAFE_OUTPUTS }}` | Safe outputs environment variable | Dynamic path to safe outputs | - -### Fixed Paths - -| Path | Description | Context | -|------|-------------|---------| -| `/tmp/gh-aw/` | Root temporary directory | Base directory for all temporary files | -| `/tmp/gh-aw/agent-stdio.log` | Agent stdio log file | Captures agent execution logs | -| `/tmp/gh-aw/aw-prompts/prompt.txt` | Prompt file | Stores agent prompt content | -| `/tmp/gh-aw/aw.patch` | Git patch file | Contains code changes from agent | -| `/tmp/gh-aw/aw_info.json` | Workflow info JSON | Metadata about workflow execution | -| `/tmp/gh-aw/cache-memory` | Cache memory directory | Cache storage location | -| `/tmp/gh-aw/cache-memory-focus-areas` | Focus areas cache | Specialized cache directory | -| `/tmp/gh-aw/cache-memory-repo-audits` | Repository audits cache | Audit cache directory | -| `/tmp/gh-aw/repo-memory/default` | Default repo memory | Standard memory storage | -| `/tmp/gh-aw/repo-memory/campaigns` | Campaign repo memory | Campaign memory storage | -| `/tmp/gh-aw/mcp-config/logs/` | MCP configuration logs | Model Context Protocol logs | -| `/tmp/gh-aw/mcp-logs/` | MCP server logs | MCP server execution logs | -| `/tmp/gh-aw/safe-inputs/logs/` | Safe inputs logs | Safe input processing logs | -| `/tmp/gh-aw/safeoutputs/` | Safe outputs directory | Safe output processing files | -| `/tmp/gh-aw/safeoutputs/assets/` | Safe outputs assets | Assets for safe outputs | -| `/tmp/gh-aw/sandbox/agent/logs/` | Sandbox agent logs | Agent sandbox execution logs | -| `/tmp/gh-aw/sandbox/firewall/logs/` | Sandbox firewall logs | Network firewall logs | -| `/tmp/gh-aw/threat-detection/` | Threat detection directory | Security analysis files | -| `/tmp/gh-aw/threat-detection/detection.log` | Threat detection log | Security analysis log | -| `/tmp/gh-aw/redacted-urls.log` | Redacted URLs log | Log of sanitized URLs | -| `/tmp/gh-aw/layout-cache` | Layout cache directory | Cache for layout patterns | -| `/tmp/gh-aw/prompt-cache` | Prompt cache directory | Cache for prompts | -| `/tmp/gh-aw/python/*.py` | Python scripts | Python source files | -| `/tmp/gh-aw/python/charts/*.png` | Python charts | Generated chart images | -| `/tmp/gh-aw/python/data/*` | Python data | Data files | -| `/opt/gh-aw/safe-jobs/` | Safe jobs directory | Safe job handler scripts | -| `sbom.cdx.json` | CycloneDX SBOM file | Software Bill of Materials | +| Path | Type | Description | Context | +|------|------|-------------|---------| +| `.github/workflows/` | Directory | Workflow definition directory | Contains all `.md` (source) and `.lock.yml` (compiled) workflow files | +| `.github/aw/` | Directory | Agentic workflow configuration | Contains `actions-lock.json` and workflow-specific configs | +| `.github/aw/actions-lock.json` | File | Action version lock file | Pins GitHub Actions to specific SHAs for security | +| `.github/agents/` | Directory | Custom agent definitions | Stores agent markdown files referenced in workflows | +| `/tmp/gh-aw/` | Directory | Runtime temporary directory | Primary workspace for agent execution and artifacts | +| `/tmp/gh-aw/agent-stdio.log` | File | Agent standard I/O log | Captures agent execution logs | +| `/tmp/gh-aw/aw-prompts/prompt.txt` | File | Agent prompt file | Stores the prompt sent to the AI engine | +| `/tmp/gh-aw/aw.patch` | File | Git patch file | Contains code changes generated by agent | +| `/tmp/gh-aw/aw_info.json` | File | Workflow metadata JSON | Runtime workflow information | +| `/tmp/gh-aw/cache-memory` | Directory | Cache memory storage | Persistent agent memory | +| `/tmp/gh-aw/cache-memory-chroma` | Directory | Chroma vector database cache | Vector DB for semantic memory | +| `/tmp/gh-aw/cache-memory-focus-areas` | Directory | Focus area cache | Domain-specific memory storage | +| `/tmp/gh-aw/cache-memory-repo-audits` | Directory | Repository audit cache | Audit-specific memory storage | +| `/tmp/gh-aw/layout-cache` | Directory | Layout specification cache | Cache for layout spec generation | +| `/tmp/gh-aw/prompt-cache` | Directory | Prompt cache storage | Caches prompts for reuse | +| `/tmp/gh-aw/mcp-config/logs/` | Directory | MCP server configuration logs | Logs from MCP server setup | +| `/tmp/gh-aw/mcp-logs/` | Directory | MCP server runtime logs | Runtime logs from MCP servers | +| `/tmp/gh-aw/redacted-urls.log` | File | Redacted URL log | URLs that were redacted for security | +| `/tmp/gh-aw/repo-memory/default` | Directory | Default repo memory | Standard repository memory location | +| `/tmp/gh-aw/repo-memory/campaigns` | Directory | Campaign repo memory | Campaign-specific memory storage | +| `/tmp/gh-aw/safe-inputs/logs/` | Directory | Safe inputs logs | Logs from safe-inputs validation | +| `/tmp/gh-aw/safeoutputs/` | Directory | Safe outputs staging | Staging area for safe-output processing | +| `/tmp/gh-aw/safeoutputs/assets/` | Directory | Safe output assets | Assets generated by safe outputs | +| `/tmp/gh-aw/sandbox/agent/logs/` | Directory | Sandboxed agent logs | Logs from sandboxed agent execution | +| `/tmp/gh-aw/sandbox/firewall/logs/` | Directory | Firewall logs | Security firewall execution logs | +| `/tmp/gh-aw/threat-detection/` | Directory | Threat detection workspace | Security analysis workspace | +| `/tmp/gh-aw/threat-detection/detection.log` | File | Threat detection log | Security threat analysis log | +| `/tmp/gh-aw/python/*.py` | File pattern | Python source files | Python scripts for analysis | +| `/tmp/gh-aw/python/charts/*.png` | File pattern | Generated chart images | PNG chart outputs | +| `/tmp/gh-aw/python/data/*` | File pattern | Python data files | Data files for Python processing | +| `/opt/gh-aw/safe-jobs/` | Directory | Safe output job scripts | Pre-installed safe-output handlers | +| `/opt/gh-aw/actions/` | Directory | Action scripts | Pre-installed action JavaScript files | +| `actions/setup/js/` | Directory | Setup action JavaScript | Source JavaScript for setup action | +| `pkg/workflow/` | Directory | Workflow compilation code | Go package for compiling workflows | +| `pkg/workflow/js/` | Directory | JavaScript runtime code | CommonJS modules for GitHub Actions | +| `pkg/constants/` | Directory | Go constants package | Constant definitions for workflows | +| `scratchpad/` | Directory | Specification documents | Documentation and specification directory | +| `licenses.csv` | File | License report CSV | License compliance report output | ## Working Directories -Common working directory patterns: +Common working directories set in workflow steps: -| Working Directory | Description | Context | -|-------------------|-------------|---------| -| `./actions/setup/js` | JavaScript actions directory | Used for JavaScript action execution | -| `actions/setup/js` | JavaScript actions (relative) | Alternative relative path | -| `./docs` | Documentation directory | Used for documentation builds | +| Directory | Description | Context | +|-----------|-------------|---------| +| `actions/setup/js` | Setup action JavaScript source | Used when running setup action scripts | +| `./docs` | Documentation directory | Documentation build and generation steps | -## Folder Patterns +## Environment Variables -Key directories used across the codebase: +Common environment variables used across workflows: -| Folder | Description | Context | -|--------|-------------|---------| -| `.github/workflows/` | Workflow files (source and compiled) | Primary location for all workflows | -| `.github/aw/` | Agentic workflow configuration | Contains actions-lock.json and other configs | -| `pkg/workflow/` | Workflow compilation code | Go package for compiling workflows | -| `pkg/cli/` | CLI command implementations | gh-aw command handlers | -| `pkg/parser/` | Markdown frontmatter parsing | Schema validation and parsing | -| `actions/setup/js/` | JavaScript runtime code | CommonJS modules for GitHub Actions | -| `actions/setup/sh/` | Shell script code | Bash scripts for GitHub Actions | -| `scratchpad/` | Specification documents | Documentation and specs directory | +### Standard Variables -## Constants and Patterns from Go Code +| Variable | Type | Description | Example Value | +|----------|------|-------------|---------------| +| `GH_AW_AGENT_OUTPUT` | Path | Agent output directory | Set by workflow, referenced in artifacts | +| `GH_AW_SAFE_OUTPUTS` | Path | Safe outputs directory | Set by workflow, used by detection job | +| `AGENT_OUTPUT_TYPES` | Output | Types of agent outputs detected | `${{ needs.agent.outputs.output_types }}` | +| `AGENT_CONCLUSION` | Output | Agent job result status | `${{ needs.agent.result }}` | +| `BASH_DEFAULT_TIMEOUT_MS` | Config | Default bash command timeout | `60000`, `300000`, `600000` | +| `BASH_MAX_TIMEOUT_MS` | Config | Maximum bash command timeout | `60000`, `300000`, `600000` | +| `AWF_LOGS_DIR` | Path | Firewall logs directory | `/tmp/gh-aw/sandbox/firewall/logs` | -### Go Code Patterns +### Branch Names -**File Path Patterns:** -```go -// Cache file paths -filepath.Join(repoRoot, ".github", "aw", CacheFileName) +| Variable | Type | Description | Example Value | +|----------|------|-------------|---------------| +| `BRANCH_NAME` | Config | Target branch for memory/updates | `memory/campaigns`, `memory/cli-performance`, `daily/default` | -// Lock file paths -filepath.Join(tmpDir, "test.lock.yml") +### Artifact Directories -// Workflow file paths -filepath.Join(testDir, "test-workflow.md") +| Variable | Type | Description | Example Value | +|----------|------|-------------|---------------| +| `ARTIFACT_DIR` | Path | Directory for artifact storage | `/tmp/gh-aw/repo-memory/campaigns`, `/tmp/gh-aw/repo-memory/default` | -// Agent path resolution -filepath.Join(repoRoot, agentPath) -``` +### Secret References -**Temporary Directory Patterns:** -```go -// Standard temp paths -"/tmp/gh-aw/agent-stdio.log" -"/tmp/gh-aw/mcp-config/logs/" -"/tmp/gh-aw/sandbox/agent/logs/" -"/tmp/gh-aw/sandbox/firewall/logs/" -``` +| Variable | Type | Description | Context | +|----------|------|-------------|---------| +| `ANTHROPIC_API_KEY` | Secret | Anthropic Claude API key | `${{ secrets.ANTHROPIC_API_KEY }}` | +| `AZURE_CLIENT_ID` | Secret | Azure AD client ID | `${{ secrets.AZURE_CLIENT_ID }}` | +| `AZURE_CLIENT_SECRET` | Secret | Azure AD client secret | `${{ secrets.AZURE_CLIENT_SECRET }}` | +| `AZURE_TENANT_ID` | Secret | Azure AD tenant ID | `${{ secrets.AZURE_TENANT_ID }}` | + +### Workflow Inputs + +| Variable | Type | Description | Example Value | +|----------|------|-------------|---------------| +| `ORGANIZATION` | Input | GitHub organization name | `${{ github.event.inputs.organization || 'github' }}` | +| `ADDITIONAL_METRICS` | Input | Additional metrics to collect | `release,pr` | + +## Go Code Constants + +Key constants defined in `pkg/constants/`: -**GitHub Context Patterns:** ```go -// Event name checks -"(github.event_name == 'issue_comment')" -"(github.event_name == 'issues')" -"(github.event_name == 'pull_request')" -"(github.event_name == 'pull_request_review_comment')" - -// Event properties -"github.event.issue.body" -"github.event.pull_request.body" -"github.event.comment.body" -"github.event.pull_request.draft" +// Job Names +const AgentJobName JobName = "agent" +const ActivationJobName JobName = "activation" +const PreActivationJobName JobName = "pre_activation" +const DetectionJobName JobName = "detection" + +// Artifact Names +const SafeOutputArtifactName = "safe-output" +const AgentOutputArtifactName = "agent-output" + +// Step IDs +const CheckMembershipStepID StepID = "check_membership" +const CheckStopTimeStepID StepID = "check_stop_time" +const CheckSkipIfMatchStepID StepID = "check_skip_if_match" +const CheckSkipIfNoMatchStepID StepID = "check_skip_if_no_match" +const CheckCommandPositionStepID StepID = "check_command_position" ``` -## JavaScript Patterns from Actions +## JavaScript Path Patterns -### Common Patterns in `.cjs` Files +Common path patterns in JavaScript files (`actions/setup/js/*.cjs`): -**Artifact References:** ```javascript -// Artifact location patterns -artifactLocation: { uri: finding.file } -core.setOutput("artifact_uploaded", "pending") +// Setup action destination +const SetupActionDestination = "/tmp/gh-aw/actions" + +// Common imports +const { setupGlobals } = require('/tmp/gh-aw/actions/setup_globals.cjs'); +const { main } = require('/opt/gh-aw/actions/assign_issue.cjs'); +const addCommentScript = fs.readFileSync(path.join(__dirname, "add_comment.cjs"), "utf8"); -// Artifact download references -"agent-artifacts" // Downloaded artifacts -"/tmp/gh-aw/threat-detection/" // Artifact extraction location +// Artifact references +const artifactDir = '/tmp/gh-aw/threat-detection/'; +const patchPath = 'agent-artifacts/tmp/gh-aw/aw.patch'; ``` -**File Path Patterns:** -```javascript -// Patch file references -"agent-artifacts/tmp/gh-aw/aw.patch" -"gh run download ${runId} -n agent-artifacts" +## Docker Integration -// Artifact directory listings -"📁 Listing all files in artifact directory: " + artifactDir -``` +Docker-related actions and patterns: + +| Component | Description | Context | +|-----------|-------------|---------| +| `docker/setup-buildx-action` | Docker Buildx setup | Enables multi-platform builds | +| `docker/login-action` | Docker registry authentication | Logs into container registries | +| `docker/metadata-action` | Docker metadata extraction | Generates tags and labels | +| `docker/build-push-action` | Docker build and push | Builds and publishes container images | ## Usage Guidelines ### Artifact Naming -- **Format**: Use descriptive hyphenated names (e.g., `agent-output`, `mcp-logs`) -- **Consistency**: Upload and download names must match exactly -- **Legacy**: Some workflows use underscore naming (`agent_outputs`), but hyphens are preferred +- Use descriptive hyphenated names (e.g., `agent-output`, `mcp-logs`) +- Separate words with hyphens, not underscores (except legacy patterns) +- Use singular nouns (e.g., `safe-output` not `safe-outputs`) +- Prefix with domain when needed (e.g., `cache-memory-focus-areas`) ### Job Naming -- **Format**: Use snake_case for job names (e.g., `create_pull_request`, `safe_outputs`) -- **Dependencies**: Jobs use `needs:` to declare dependencies on other jobs -- **Conditional**: Jobs can use `if:` conditions for conditional execution +- Use snake_case for job names (e.g., `create_pull_request`, `check_membership`) +- Use descriptive verbs (e.g., `update_`, `check_`, `create_`, `send_`) +- Keep names under 30 characters when possible +- Standard suffixes: `_check`, `_status`, `_memory` + +### Step ID Naming +- Use snake_case for step IDs (e.g., `check_actor`, `generate_aw_info`) +- Use descriptive action verbs (e.g., `check_`, `generate_`, `handle_`, `compute_`) +- Keep IDs concise but meaningful +- Standard prefixes: `check_` (validation), `handle_` (error handling), `compute_` (calculation) ### Path References -- **Relative paths**: Use relative paths from repository root (e.g., `./actions/setup`) -- **Environment variables**: Use GitHub Actions expressions for dynamic paths (e.g., `${{ env.GH_AW_AGENT_OUTPUT }}`) -- **Temporary files**: All temporary files go under `/tmp/gh-aw/` for consistency +- Use relative paths from repository root for repo files +- Use absolute paths for `/tmp/gh-aw/` runtime files +- Use `/opt/gh-aw/` for pre-installed scripts +- Always use forward slashes, even on Windows ### Action Pinning -- **Security**: Always pin actions to full commit SHA for security -- **Updates**: Update action SHAs through dependabot or manual review -- **Local actions**: Local actions use relative paths (e.g., `./actions/setup`) +- **Always pin actions to full commit SHA for security** (40-character hex) +- Never use tag references (e.g., `@v3`) in production workflows +- Document the version/tag that corresponds to each SHA in comments +- Update SHAs via `.github/aw/actions-lock.json` configuration + +### Environment Variables +- Use `GH_AW_` prefix for gh-aw specific variables +- Use uppercase with underscores (e.g., `AGENT_OUTPUT_TYPES`) +- Reference other job outputs using `${{ needs.job_name.outputs.output_name }}` +- Reference secrets using `${{ secrets.SECRET_NAME }}` ### File Organization -- **Source files**: Markdown workflows in `.github/workflows/*.md` -- **Compiled files**: Lock files in `.github/workflows/*.lock.yml` -- **JavaScript**: Action scripts in `actions/setup/js/*.cjs` -- **Shell scripts**: Action scripts in `actions/setup/sh/*.sh` -- **Go code**: Compiler in `pkg/workflow/` +- Source workflows: `.github/workflows/*.md` +- Compiled workflows: `.github/workflows/*.lock.yml` +- Configuration: `.github/aw/` +- Runtime: `/tmp/gh-aw/` +- Pre-installed: `/opt/gh-aw/` +- Documentation: `scratchpad/` -## Extraction Summary +## Pattern Analysis + +### Most Common Patterns + +1. **Setup Action**: Nearly every workflow uses `./actions/setup` as first step +2. **Checkout**: `actions/checkout` is used in 95%+ of workflows +3. **Artifact Upload/Download**: Extensive use of artifact passing between jobs +4. **Environment References**: Heavy use of job outputs via `needs.job.outputs.` +5. **Security**: All external actions pinned to full SHAs + +### Workflow Structure Pattern + +Typical workflow job sequence: + +``` +activation → agent → detection → safe_outputs → conclusion + ↓ ↓ ↓ ↓ + ↓ ↓ ↓ (always runs) +(conditional) (uploads artifacts) (dispatches) +``` + +### Artifact Flow Pattern + +``` +agent job → uploads agent-output artifact + → uploads safe-output artifact + +detection job → downloads agent-output + → analyzes outputs + → triggers safe_outputs job + +safe_outputs → downloads safe-output + → dispatches handler jobs + +conclusion → downloads all artifacts (optional) + → generates summary +``` -- **Lock files analyzed**: 137 -- **Actions cataloged**: 25 (24 external + 1 local) -- **Artifacts documented**: 17 -- **Job patterns found**: 20 -- **File paths listed**: 30+ -- **Working directories**: 3 +## Version History -## Source Analysis +- **February 04, 2026**: Updated specification from 145 lock files (previously 137) + - Documented 30 unique GitHub Actions (up from 25) + - Cataloged 18 artifact names (up from 17) + - Listed 24 common job names (up from 20) + - Documented 30+ step IDs + - Extracted 50+ file path patterns + - Analyzed Go constants and JavaScript patterns + - Added comprehensive usage guidelines + - Expanded environment variables section + - Added Docker integration section -This specification was generated by analyzing: -1. All `.lock.yml` files in `.github/workflows/` using `yq` queries -2. Go code in `pkg/workflow/*.go` for path patterns and constants -3. JavaScript code in `actions/setup/js/*.cjs` for artifact patterns -4. File system structure for directory organization +- **January 23, 2026**: Initial specification generated from 137 lock files --- -*Auto-generated by Layout Specification Maintainer workflow - 2026-01-23* +*This document is automatically maintained by the Layout Specification Maintainer workflow.* +*To update this specification, trigger the `layout-spec-maintainer` workflow or run: `gh aw run layout-spec-maintainer.md`*