diff --git a/.github/workflows/glossary-maintainer.md b/.github/workflows/glossary-maintainer.md index 30904cd7d7a..b062e544b1a 100644 --- a/.github/workflows/glossary-maintainer.md +++ b/.github/workflows/glossary-maintainer.md @@ -114,9 +114,8 @@ Based on the scope (daily or weekly): - List recent commits using `list_commits` for the appropriate timeframe - Get detailed commit information using `get_commit` for commits that might introduce new terminology - Search for merged pull requests using `search_pull_requests` -- Review PR descriptions and comments for new terminology -**Look for:** +**Look for new terminology in `docs/**/*.{md,mdx}` (and nowhere else)** - New configuration fields in frontmatter (YAML keys) - New CLI commands or flags - New tool names or MCP servers @@ -178,12 +177,14 @@ Based on your scan of recent changes, create a list of: - The term requires explanation (not self-evident) - The term is specific to GitHub Agentic Workflows - The term is likely to confuse users without a definition +- The term is used somewhere in `docs/**/*.{md,mdx}` files **Do NOT add:** - Generic programming terms (unless used in a specific way) - Self-evident terms - Internal implementation details - Terms only used in code comments +- Terms not used in documentation ### 7. Update the Glossary diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index d614656a88e..97ea510c8df 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -295,10 +295,7 @@ export default defineConfig({ { label: 'Compilation Process', link: '/reference/compilation-process/' }, { label: 'Concurrency', link: '/reference/concurrency/' }, { label: 'Cost Management', link: '/reference/cost-management/' }, - { label: 'Copilot Agent Files', link: '/reference/copilot-custom-agents/' }, - { label: 'Cross-Repository', link: '/reference/cross-repository/' }, { label: 'Custom Safe Outputs', link: '/reference/custom-safe-outputs/' }, - { label: 'Dependabot', link: '/reference/dependabot/' }, { label: 'Environment Variables', link: '/reference/environment-variables/' }, { label: 'FAQ', link: '/reference/faq/' }, { label: 'Footers', link: '/reference/footers/' }, @@ -306,15 +303,22 @@ export default defineConfig({ { label: 'Frontmatter (Full)', link: '/reference/frontmatter-full/' }, { label: 'GH-AW Agent', link: '/reference/custom-agent-for-aw/' }, { label: 'GH-AW as MCP Server', link: '/reference/gh-aw-as-mcp-server/' }, - { label: 'GitHub Lockdown Mode', link: '/reference/lockdown-mode/' }, - { label: 'GitHub Tools', link: '/reference/github-tools/' }, + { label: 'GitHub (Checkout)', link: '/reference/checkout/' }, + { label: 'GitHub (Read Tools)', link: '/reference/github-tools/' }, + { label: 'GitHub (Read Permissions)', link: '/reference/permissions/' }, + { label: 'GitHub (Integrity Filtering)', link: '/reference/integrity/' }, + { label: 'GitHub (Cross-Repository)', link: '/reference/cross-repository/' }, + { label: 'GitHub (Fork Support)', link: '/reference/fork-support/' }, { label: 'Glossary', link: '/reference/glossary/' }, { label: 'Imports', link: '/reference/imports/' }, + { label: 'Imports (APM)', link: '/reference/dependencies/' }, + { label: 'Imports (Copilot Agent Files)', link: '/reference/copilot-custom-agents/' }, + { label: 'Imports (Dependabot)', link: '/reference/dependabot/' }, { label: 'Markdown', link: '/reference/markdown/' }, { label: 'MCP Gateway', link: '/reference/mcp-gateway/' }, { label: 'Network Access', link: '/reference/network/' }, - { label: 'Permissions', link: '/reference/permissions/' }, - { label: 'Rate Limiting Controls', link: '/reference/rate-limiting-controls/' }, + { label: 'Playwright', link: '/reference/playwright/' }, + { label: 'Rate Limiting', link: '/reference/rate-limiting-controls/' }, { label: 'Repo Memory', link: '/reference/repo-memory/' }, { label: 'MCP Scripts', link: '/reference/mcp-scripts/' }, { label: 'MCP Scripts (Spec)', link: '/reference/mcp-scripts-specification/' }, @@ -329,9 +333,7 @@ export default defineConfig({ { label: 'Tools', link: '/reference/tools/' }, { label: 'Triggering CI', link: '/reference/triggering-ci/' }, { label: 'Triggers', link: '/reference/triggers/' }, - { label: 'WASM Compilation', link: '/reference/wasm-compilation/' }, { label: 'Workflow Structure', link: '/reference/workflow-structure/' }, - { label: 'Fork Support', link: '/reference/fork-support/' }, ], }, { diff --git a/docs/interactive-run-mode.md b/docs/interactive-run-mode.md index f4e9321bf22..bb211c9fa3c 100644 --- a/docs/interactive-run-mode.md +++ b/docs/interactive-run-mode.md @@ -51,7 +51,6 @@ All standard `run` command flags work in interactive mode: - `--repo owner/repo` - Target a different repository - `--ref branch` - Run on a specific branch - `--engine copilot` - Override AI engine -- `--auto-merge-prs` - Auto-merge created PRs - `--push` - Push changes before running ## Limitations diff --git a/docs/slides/index.md b/docs/slides/index.md index 5d5d7f95024..568d976fd3a 100644 --- a/docs/slides/index.md +++ b/docs/slides/index.md @@ -538,7 +538,7 @@ External services accessed only through proxies — multiple controls before rea | **Network** | Proxy/firewall at every layer, domain allowlisting | | **Permissions** | Read-only default, safe outputs for writes | | **Supply Chain** | Pinned action SHAs, protected CI/CD files | -| **GitHub Guard** | `min-integrity`, secrecy & integrity metadata | +| **Integrity** | `min-integrity`, access & integrity metadata | | **Monitoring** | Threat detection, audit logs, run analysis | --- diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx index 2c551ac7a4f..775ae863287 100644 --- a/docs/src/content/docs/agent-factory-status.mdx +++ b/docs/src/content/docs/agent-factory-status.mdx @@ -51,6 +51,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Daily CLI Performance Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-cli-performance.md) | copilot | [![Daily CLI Performance Agent](https://github.com/github/gh-aw/actions/workflows/daily-cli-performance.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-cli-performance.lock.yml) | - | - | | [Daily CLI Tools Exploratory Tester](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-cli-tools-tester.md) | copilot | [![Daily CLI Tools Exploratory Tester](https://github.com/github/gh-aw/actions/workflows/daily-cli-tools-tester.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-cli-tools-tester.lock.yml) | - | - | | [Daily Code Metrics and Trend Tracking Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-code-metrics.md) | claude | [![Daily Code Metrics and Trend Tracking Agent](https://github.com/github/gh-aw/actions/workflows/daily-code-metrics.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-code-metrics.lock.yml) | - | - | +| [Daily Community Attribution Updater](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-community-attribution.md) | copilot | [![Daily Community Attribution Updater](https://github.com/github/gh-aw/actions/workflows/daily-community-attribution.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-community-attribution.lock.yml) | - | - | | [Daily Compiler Quality Check](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-compiler-quality.md) | copilot | [![Daily Compiler Quality Check](https://github.com/github/gh-aw/actions/workflows/daily-compiler-quality.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-compiler-quality.lock.yml) | - | - | | [Daily Copilot PR Merged Report](https://github.com/github/gh-aw/blob/main/.github/workflows/copilot-pr-merged-report.md) | copilot | [![Daily Copilot PR Merged Report](https://github.com/github/gh-aw/actions/workflows/copilot-pr-merged-report.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/copilot-pr-merged-report.lock.yml) | `0 15 * * 1-5` | - | | [Daily Copilot Token Consumption Report](https://github.com/github/gh-aw/blob/main/.github/workflows/daily-copilot-token-report.md) | copilot | [![Daily Copilot Token Consumption Report](https://github.com/github/gh-aw/actions/workflows/daily-copilot-token-report.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/daily-copilot-token-report.lock.yml) | `0 11 * * 1-5` | - | @@ -105,7 +106,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Go Logger Enhancement](https://github.com/github/gh-aw/blob/main/.github/workflows/go-logger.md) | claude | [![Go Logger Enhancement](https://github.com/github/gh-aw/actions/workflows/go-logger.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/go-logger.lock.yml) | - | - | | [Go Pattern Detector](https://github.com/github/gh-aw/blob/main/.github/workflows/go-pattern-detector.md) | claude | [![Go Pattern Detector](https://github.com/github/gh-aw/actions/workflows/go-pattern-detector.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/go-pattern-detector.lock.yml) | `0 14 * * 1-5` | - | | [GPL Dependency Cleaner (gpclean)](https://github.com/github/gh-aw/blob/main/.github/workflows/gpclean.md) | copilot | [![GPL Dependency Cleaner (gpclean)](https://github.com/github/gh-aw/actions/workflows/gpclean.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/gpclean.lock.yml) | - | - | -| [Grumpy Code Reviewer 🔥](https://github.com/github/gh-aw/blob/main/.github/workflows/grumpy-reviewer.md) | copilot | [![Grumpy Code Reviewer 🔥](https://github.com/github/gh-aw/actions/workflows/grumpy-reviewer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/grumpy-reviewer.lock.yml) | - | `/grumpy` | +| [Grumpy Code Reviewer 🔥](https://github.com/github/gh-aw/blob/main/.github/workflows/grumpy-reviewer.md) | codex | [![Grumpy Code Reviewer 🔥](https://github.com/github/gh-aw/actions/workflows/grumpy-reviewer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/grumpy-reviewer.lock.yml) | - | `/grumpy` | | [Instructions Janitor](https://github.com/github/gh-aw/blob/main/.github/workflows/instructions-janitor.md) | claude | [![Instructions Janitor](https://github.com/github/gh-aw/actions/workflows/instructions-janitor.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/instructions-janitor.lock.yml) | - | - | | [Issue Arborist](https://github.com/github/gh-aw/blob/main/.github/workflows/issue-arborist.md) | codex | [![Issue Arborist](https://github.com/github/gh-aw/actions/workflows/issue-arborist.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/issue-arborist.lock.yml) | - | - | | [Issue Monster](https://github.com/github/gh-aw/blob/main/.github/workflows/issue-monster.md) | copilot | [![Issue Monster](https://github.com/github/gh-aw/actions/workflows/issue-monster.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/issue-monster.lock.yml) | - | - | diff --git a/docs/src/content/docs/blog/2026-01-13-meet-the-workflows.md b/docs/src/content/docs/blog/2026-01-13-meet-the-workflows.md index ebdc4a12192..e537d38c687 100644 --- a/docs/src/content/docs/blog/2026-01-13-meet-the-workflows.md +++ b/docs/src/content/docs/blog/2026-01-13-meet-the-workflows.md @@ -76,7 +76,7 @@ Note how concise this is - it's like reading a to-do list for the agent. The wor In the frontmatter, we define [permissions](/gh-aw/reference/frontmatter/#permissions-permissions), [tools](/gh-aw/reference/tools/), and [safe outputs](/gh-aw/reference/safe-outputs/). This ensures the agent only has access to what it needs and can't perform any unsafe actions. The natural language instructions in the body guide the agent's behavior in a clear, human-readable way. -Issue triage workflows in public repositories are one of the [rare cases where you might disable lockdown mode](/gh-aw/reference/faq/#what-is-github-lockdown-mode-and-when-is-it-enabled) to process issues from all contributors. If you are a maintainer in a public repository and need your triage agent to see and label issues from users without push access, configure `lockdown: false` in your GitHub tools configuration. See [Lockdown Mode](/gh-aw/reference/lockdown-mode/) for security considerations and best practices. +Issue triage workflows in public repositories may need to process issues from all contributors. By default, `min-integrity: approved` restricts agent visibility to owners, members, and collaborators. If you are a maintainer in a public repository and need your triage agent to see and label issues from users without push access, set `min-integrity: none` in your GitHub tools configuration. See [Integrity Filtering](/gh-aw/reference/integrity/) for security considerations and best practices. We've deliberately kept this workflow ultra-simple. In practice, in your own repo, **customization** is key. Triage differs in every repository. Tailoring workflows to your specific context will make them more effective. Generic agents are okay, but customized ones are often a better fit. diff --git a/docs/src/content/docs/blog/2026-01-24-design-patterns.md b/docs/src/content/docs/blog/2026-01-24-design-patterns.md index 3c7cf135a21..c58a3c7c065 100644 --- a/docs/src/content/docs/blog/2026-01-24-design-patterns.md +++ b/docs/src/content/docs/blog/2026-01-24-design-patterns.md @@ -182,7 +182,7 @@ Some key characteristics are: - Often includes intelligent classification - Maintains issue relationships - Respects user intent and context -- **For public repo triage**: May need [lockdown mode disabled](/gh-aw/reference/lockdown-mode/) to process issues from all users +- **For public repo triage**: Set `min-integrity: none` to process issues from all users (default is `approved`, which restricts to trusted contributors) — see [Integrity Filtering](/gh-aw/reference/integrity/) --- diff --git a/docs/src/content/docs/blog/2026-01-27-operational-patterns.md b/docs/src/content/docs/blog/2026-01-27-operational-patterns.md index eaca7c0f333..a74d689d74e 100644 --- a/docs/src/content/docs/blog/2026-01-27-operational-patterns.md +++ b/docs/src/content/docs/blog/2026-01-27-operational-patterns.md @@ -173,7 +173,7 @@ Here are our tips! - Allow manual override - Track triage accuracy - Update classification rules based on feedback -- **For public repos**: Consider if you need to [disable lockdown mode](/gh-aw/reference/faq/#what-is-github-lockdown-mode-and-when-is-it-enabled) to process issues from all users (this is one of the rare safe use cases - see [Lockdown Mode](/gh-aw/reference/lockdown-mode/) for security guidance) +- **For public repos**: By default, `min-integrity: approved` restricts agent visibility to owners, members, and collaborators. For triage workflows that need to process issues from all users, set `min-integrity: none` explicitly — see [Integrity Filtering](/gh-aw/reference/integrity/) for guidance. **Learn more**: [IssueOps Examples](https://github.github.com/gh-aw/patterns/issue-ops/) diff --git a/docs/src/content/docs/guides/getting-started-mcp.md b/docs/src/content/docs/guides/getting-started-mcp.md index 66b272108c1..b640633b31d 100644 --- a/docs/src/content/docs/guides/getting-started-mcp.md +++ b/docs/src/content/docs/guides/getting-started-mcp.md @@ -101,7 +101,7 @@ The `default` toolset includes: `context`, `repos`, `issues`, `pull_requests`. W ### Operating Modes -Remote mode (`mode: remote`) connects to a hosted server for faster startup with no Docker required. Local mode (`mode: local`) runs in Docker, enabling version pinning for offline or restricted environments. See [Remote vs Local Mode](/gh-aw/reference/github-tools/#remote-vs-local-mode). +Remote mode (`mode: remote`) connects to a hosted server for faster startup with no Docker required. Local mode (`mode: local`) runs in Docker, enabling version pinning for offline or restricted environments. See [Remote vs Local Mode](/gh-aw/reference/github-tools/#github-tools-remote-mode). The GitHub MCP server always operates read-only. Write operations are handled through [safe outputs](/gh-aw/reference/safe-outputs/), which run in a separate permission-controlled job. diff --git a/docs/src/content/docs/introduction/architecture.mdx b/docs/src/content/docs/introduction/architecture.mdx index 9821afa357e..bb7f073719d 100644 --- a/docs/src/content/docs/introduction/architecture.mdx +++ b/docs/src/content/docs/introduction/architecture.mdx @@ -554,17 +554,14 @@ XML and HTML tags are converted to a safe parentheses format to prevent injectio Workflows should use `${{ needs.activation.outputs.text }}` instead of raw `github.event` fields to ensure proper sanitization of user-provided content. -## GitHub Lockdown Mode +## Integrity Filtering -GitHub lockdown mode is a security feature of the GitHub MCP server that filters content in public repositories to only surface items from users with push access. This protects workflows from processing potentially malicious or misleading input from untrusted users. +Integrity filtering controls which GitHub content an agent can access during a workflow run, based on **author trust** and **merge status** rather than push access alone. The MCP gateway intercepts tool calls and filters content below the configured `min-integrity` threshold before the AI engine sees it — items from blocked users or below the minimum trust level are removed transparently. -When **lockdown mode is enabled**, the GitHub MCP server: -- Only returns issues, PRs, comments, and discussions from users with push, maintain, or admin access -- Blocks coding agent from seeing content from other users -- Has no particular effect for private or internal repos +For public repositories, `min-integrity: approved` is applied automatically — restricting content to owners, members, and collaborators — even without additional authentication. The four configurable levels (`merged`, `approved`, `unapproved`, `none`) are cumulative from most to least restrictive. Individual users can be blocked unconditionally, and trusted reviewers can promote specific items via approval labels. ## Secret Redaction @@ -797,7 +794,7 @@ gh aw status | **Configuration** | Action SHA pinning | Supply chain attacks, tag hijacking | | **Configuration** | Security scanners (actionlint, zizmor, poutine) | Privilege escalation, misconfigurations, supply chain risks | | **Configuration** | Pre-activation checks (role/permission) | Unauthorized users, expired workflows | -| **Plan** | GitHub lockdown mode | Untrusted user input, context poisoning, social engineering | +| **Plan** | Integrity filtering (`min-integrity`) | Untrusted user input, context poisoning, social engineering | | **Plan** | Content sanitization | @mention abuse, bot triggers | | **Plan** | Secret redaction | Credential leakage in logs/artifacts | | **Plan** | Threat detection | Malicious patches, secret leaks | @@ -807,7 +804,7 @@ gh aw status ## Related Documentation -- [Lockdown Mode](/gh-aw/reference/lockdown-mode/) - GitHub content filtering for public repositories +- [Integrity Filtering](/gh-aw/reference/integrity/) - Author-trust and merge-status content filtering - [Threat Detection Guide](/gh-aw/reference/threat-detection/) - Configuring threat analysis - [Network Permissions](/gh-aw/reference/network/) - Network access control - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Output processing configuration diff --git a/docs/src/content/docs/patterns/multi-repo-ops.md b/docs/src/content/docs/patterns/multi-repo-ops.md index 53bbae87ac0..997261d1e1a 100644 --- a/docs/src/content/docs/patterns/multi-repo-ops.md +++ b/docs/src/content/docs/patterns/multi-repo-ops.md @@ -143,7 +143,7 @@ tools: ``` > [!IMPORTANT] -> When reading from repositories other than the workflow's repository, you must configure additional authentication. The default `GITHUB_TOKEN` only has access to the current repository. Use a PAT, GitHub App token, or the magic secret `GH_AW_GITHUB_MCP_SERVER_TOKEN`. See [GitHub Tools Reference](/gh-aw/reference/github-tools/#cross-repository-reading) for details. +> When reading from repositories other than the workflow's repository, you must configure additional authentication. The default `GITHUB_TOKEN` only has access to the current repository. Use a PAT, GitHub App token, or the magic secret `GH_AW_GITHUB_MCP_SERVER_TOKEN`. See [GitHub Tools Reference](/gh-aw/reference/cross-repository/#cross-repository-reading) for details. Agent instructions can reference remote repositories: diff --git a/docs/src/content/docs/patterns/trial-ops.md b/docs/src/content/docs/patterns/trial-ops.md index 16818f2ea75..3dbe43d925f 100644 --- a/docs/src/content/docs/patterns/trial-ops.md +++ b/docs/src/content/docs/patterns/trial-ops.md @@ -5,7 +5,7 @@ sidebar: badge: { text: 'Testing', variant: 'tip' } --- -TrialOps extends [SideRepoOps](/gh-aw/patterns/side-repo-ops/) with temporary trial repositories for safely validating and iterating on workflows before production deployment. The `trial` command creates isolated private repos where workflows execute and capture safe outputs (issues, PRs, comments) without affecting your actual codebase. +TrialOps uses temporary trial repositories for safely validating and iterating on workflows before deployment to target repositories. The `trial` command creates isolated private repos where workflows execute and capture safe outputs (issues, PRs, comments) without affecting your actual codebase. ## How Trial Mode Works @@ -24,9 +24,6 @@ The CLI creates a temporary private repository (default: `gh-aw-trial`), install | Logical | `--logical-repo myorg/target-repo` | Simulates running against specified repo; outputs in trial repo | | Clone | `--clone-repo myorg/real-repo` | Clones repo contents so workflows can analyze actual code | -> [!WARNING] -> Direct mode creates real issues and PRs in the target repository. Only use with test repositories. - ## Basic Usage ### Dry-Run Mode @@ -69,9 +66,6 @@ gh aw trial githubnext/agentics/my-workflow --host-repo my-custom-trial gh aw trial ./my-workflow.md --host-repo . # Use current repo ``` -> [!TIP] -> Trial repositories persist between runs. Reuse the same `--host-repo` name across test sessions. - ## Advanced Patterns ### Issue Context @@ -83,14 +77,6 @@ gh aw trial githubnext/agentics/triage-workflow \ --trigger-context "https://github.com/myorg/repo/issues/123" ``` -### Auto-merge PRs - -Automatically merge created PRs (useful for testing multi-step workflows): - -```bash -gh aw trial githubnext/agentics/feature-workflow --auto-merge-prs -``` - ### Append Instructions Test workflow responses to additional constraints without modifying the source: @@ -134,6 +120,7 @@ Results are saved in `trials/*.json` with workflow runs, issues, PRs, and commen **Success indicators:** Green checkmark, expected outputs created, no errors in logs. **Common issues:** + - **Workflow dispatch failed** - Add `workflow_dispatch` trigger - **No safe outputs** - Configure safe outputs in workflow - **Permission errors** - Verify API keys @@ -148,70 +135,6 @@ gh aw trial v1.md v2.md v3.md --repeat 2 cat trials/combined-results.*.json | jq '.results[] | {workflow: .workflow_name, issues: .safe_outputs.issues_created | length}' ``` -## Trial Mode Limitations - -- **Requires `workflow_dispatch` trigger** - Add to workflows that only trigger on issues/PRs/schedules -- **Safe outputs needed** - Workflows without safe outputs execute but create no visible results -- **No simulated events** - Use `--trigger-context` to provide event context like issue payloads -- **Private repositories** - Trial repos count toward your private repository quota -- **API rate limits** - Space out large runs or use `--repeat` instead of separate invocations - -## Best Practices - -### Development Workflow - -Iterate locally: write the workflow, preview with `--dry-run`, run a trial, adjust, compare variants side-by-side, validate consistency with `--repeat`, then deploy. - -### Testing Strategy - -```bash -# Unit testing - individual workflows -gh aw trial ./workflows/triage.md --delete-host-repo-after - -# Integration testing - with actual content -gh aw trial ./workflows/code-review.md --clone-repo myorg/real-repo - -# Regression testing - before/after comparison -gh aw trial ./workflow.md --host-repo regression-baseline -gh aw trial ./workflow.md --host-repo regression-test - -# Performance testing - execution time and tokens -gh aw trial ./workflow.md --repeat 5 -``` - -### Prompt Engineering - -Iteratively refine prompts: run baseline → modify prompt → test variant → compare outputs → repeat. - -### CI/CD Integration - -```yaml -name: Test Workflows -on: [pull_request] -jobs: - trial: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v6 - - name: Install gh-aw - run: gh extension install github/gh-aw - - name: Trial workflow - env: - COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }} - run: gh aw trial ./.github/workflows/my-workflow.md --delete-host-repo-after --yes -``` - -## Troubleshooting - -| Issue | Solution | -|-------|----------| -| `workflow not found` | Use correct format: `owner/repo/workflow-name`, `owner/repo/.github/workflows/workflow.md`, or `./local-workflow.md` | -| `workflow_dispatch not supported` | Add `workflow_dispatch:` to workflow frontmatter `on:` section | -| `authentication failed` | See [Authentication](/gh-aw/reference/auth/). Trial automatically prompts for missing secrets and uploads them to the trial repo | -| `failed to create trial repository` | Check `gh auth status`, verify quota with `gh api user \| jq .plan`, try explicit `--host-repo name` | -| `execution timed out` | Increase with `--timeout 60` (minutes, default: 30) | -| No issues/PRs created | Configure `safe-outputs` in workflow frontmatter, check Actions logs for errors | - ## Related Documentation - [SideRepoOps](/gh-aw/patterns/side-repo-ops/) - Run workflows from separate repositories diff --git a/docs/src/content/docs/reference/auth.mdx b/docs/src/content/docs/reference/auth.mdx index 185281dcea1..a1aebb5c3c1 100644 --- a/docs/src/content/docs/reference/auth.mdx +++ b/docs/src/content/docs/reference/auth.mdx @@ -29,7 +29,6 @@ Workflows using the following **read** operations from GitHub require [Additiona - **Read from multiple repositories** - **Read from projects** - **GitHub tools remote mode** -- **GitHub tools lockdown mode** Workflows using the following features of [Safe Outputs](/gh-aw/reference/safe-outputs/) require additional authentication, via either a secret containing a PAT or GitHub App: - [**Safe outputs writing cross-repo**](/gh-aw/reference/safe-outputs/#cross-repository-operations) diff --git a/docs/src/content/docs/reference/checkout.md b/docs/src/content/docs/reference/checkout.md new file mode 100644 index 00000000000..898d94223fe --- /dev/null +++ b/docs/src/content/docs/reference/checkout.md @@ -0,0 +1,139 @@ +--- +title: GitHub Repository Checkout +description: Configure how actions/checkout is invoked in the agent job — disable checkout, override settings, check out multiple repositories, fetch additional refs, and mark a primary target repository. +sidebar: + order: 852 +--- + +The `checkout:` frontmatter field controls how `actions/checkout` is invoked in the agent job. Configure custom checkout settings, check out multiple repositories, or disable checkout entirely. + +By default, the agent checks out the repository where the workflow is running with a shallow fetch (`fetch-depth: 1`). If triggered by a pull request event, it also checks out the PR head ref. For most workflows, this default checkout is sufficient and no `checkout:` configuration is necessary. + +Use `checkout:` when you need to check out additional branches, check out multiple repositories, or to disable checkout entirely for workflows that don't need to access code or can access code dynamically through the GitHub Tools. + +## Custom Checkout Settings + +You can use `checkout:` to override default checkout settings (e.g., fetch depth, sparse checkout) without needing to define a custom job: + +```yaml wrap +checkout: + fetch-depth: 0 # Full git history + github-token: ${{ secrets.MY_TOKEN }} # Custom authentication +``` + +Or use GitHub App authentication: + +```yaml wrap +checkout: + fetch-depth: 0 + github-app: + app-id: ${{ vars.APP_ID }} + private-key: ${{ secrets.APP_PRIVATE_KEY }} +``` + +You can also use `checkout:` to check out additional repositories alongside the main repository: + +```yaml wrap +checkout: + - fetch-depth: 0 + - repository: owner/other-repo + path: ./libs/other + ref: main + github-token: ${{ secrets.CROSS_REPO_PAT }} +``` + +## Configuration Options + +| Field | Type | Description | +|-------|------|-------------| +| `repository` | string | Repository in `owner/repo` format. Defaults to the current repository. | +| `ref` | string | Branch, tag, or SHA to checkout. Defaults to the triggering ref. | +| `path` | string | Path within `GITHUB_WORKSPACE` to place the checkout. Defaults to workspace root. | +| `github-token` | string | Token for authentication. Use `${{ secrets.MY_TOKEN }}` syntax. | +| `github-app` | object | GitHub App credentials (`app-id`, `private-key`, optional `owner`, `repositories`). Mutually exclusive with `github-token`. `app` is a deprecated alias. | +| `fetch-depth` | integer | Commits to fetch. `0` = full history, `1` = shallow clone (default). | +| `fetch` | string \| string[] | Additional Git refs to fetch after checkout. See [Fetching Additional Refs](#fetching-additional-refs). | +| `sparse-checkout` | string | Newline-separated patterns for sparse checkout (e.g., `.github/\nsrc/`). | +| `submodules` | string/bool | Submodule handling: `"recursive"`, `"true"`, or `"false"`. | +| `lfs` | boolean | Download Git LFS objects. | +| `current` | boolean | Marks this checkout as the primary working repository. The agent uses this as the default target for all GitHub operations. Only one checkout may set `current: true`; the compiler rejects workflows where multiple checkouts enable it. | + +## Fetching Additional Refs + +By default, `actions/checkout` performs a shallow clone (`fetch-depth: 1`) of a single ref. For workflows that need to work with other branches — for example, a scheduled workflow that must push changes to open pull-request branches — use the `fetch:` option to retrieve additional refs after the checkout step. + +A dedicated git fetch step is emitted after the `actions/checkout` step. Authentication re-uses the checkout token (or falls back to `github.token`) via a transient `http.extraheader` credential — no credentials are persisted to disk, consistent with the enforced `persist-credentials: false` policy. + +| Value | Description | +|-------|-------------| +| `"*"` | All remote branches. | +| `"refs/pulls/open/*"` | All open pull-request head refs (GH-AW shorthand). | +| `"main"` | A specific branch name. | +| `"feature/*"` | A glob pattern matching branch names. | + +```yaml wrap +checkout: + - fetch: ["*"] # fetch all branches (default checkout) + fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details +``` + +```yaml wrap +checkout: + - repository: githubnext/gh-aw-side-repo + github-token: ${{ secrets.GH_AW_SIDE_REPO_PAT }} + fetch: ["refs/pulls/open/*"] # fetch all open PR refs after checkout + fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details +``` + +```yaml wrap +checkout: + - repository: org/target-repo + github-token: ${{ secrets.CROSS_REPO_PAT }} + fetch: ["main", "feature/*"] # fetch specific branches + fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details +``` + +:::note +If a branch you need is not available after checkout and is not covered by a `fetch:` pattern, and you're in a private or internal repo, then the agent cannot access its Git history except inefficiently, file by file, via the GitHub MCP. For private repositories, it will be unable to fetch or explore additional branches. If the branch is required and unavailable, configure the appropriate pattern in `fetch:` (e.g., `fetch: ["*"]` for all branches, or `fetch: ["refs/pulls/open/*"]` for PR branches) and recompile the workflow. +::: + +## Disabling Checkout (`checkout: false`) + +Set `checkout: false` to suppress the default `actions/checkout` step entirely. Use this for workflows that access repositories through MCP servers or other mechanisms that do not require a local clone: + +```yaml wrap +checkout: false +``` + +This is equivalent to omitting the checkout step from the agent job. Custom dev-mode steps (such as "Checkout actions folder") are unaffected. + +## Checkout Merging + +Multiple `checkout:` configurations can target the same path and repository. This is useful for monorepos where different parts of the repository must be merged into the same workspace directory with different settings (e.g., sparse checkout for some paths, full checkout for others). + +When multiple `checkout:` entries target the same repository and path, their configurations are merged with the following rules: + +- **Fetch depth**: Deepest value wins (`0` = full history always takes precedence) +- **Fetch refs**: Merged (union of all patterns; duplicates are removed) +- **Sparse patterns**: Merged (union of all patterns) +- **LFS**: OR-ed (if any config enables `lfs`, the merged configuration enables it) +- **Submodules**: First non-empty value wins for each `(repository, path)`; once set, later values are ignored +- **Ref/Token/App**: First-seen wins + +## Marking a Primary Repository (`current: true`) + +When a workflow running from a central repository targets a different repository, use `current: true` to tell the agent which repository to treat as its primary working target. The agent uses this as the default for all GitHub operations (creating issues, opening PRs, reading content) unless the prompt instructs otherwise. When omitted, the agent defaults to the repository where the workflow is running. + +```yaml wrap +checkout: + - repository: org/target-repo + path: ./target + github-token: ${{ secrets.CROSS_REPO_PAT }} + current: true # agent's primary target +``` + +## Related Documentation + +- [Cross-Repository Operations](/gh-aw/reference/cross-repository/) - Reading and writing across multiple repositories +- [Authentication Reference](/gh-aw/reference/auth/) - PAT and GitHub App setup +- [Multi-Repository Examples](/gh-aw/examples/multi-repo/) - Complete working examples diff --git a/docs/src/content/docs/reference/cross-repository.md b/docs/src/content/docs/reference/cross-repository.md index d56df7d985a..2c614c47c84 100644 --- a/docs/src/content/docs/reference/cross-repository.md +++ b/docs/src/content/docs/reference/cross-repository.md @@ -7,146 +7,36 @@ sidebar: Cross-repository operations enable workflows to access code from multiple repositories and create resources (issues, PRs, comments) in external repositories. This page documents all declarative frontmatter features for cross-repository workflows. -## Overview - Cross-repository features fall into three categories: -1. **Code access** - Check out code from multiple repositories into the workflow workspace using the `checkout:` frontmatter field -2. **GitHub tools** - Read information from other repositories using GitHub Tools with additional authentication -3. **Safe outputs** - Create issues, PRs, comments, and other resources in external repositories using `target-repo` and `allowed-repos` in safe outputs - -All require authentication beyond the default `GITHUB_TOKEN`, which is scoped to the current repository only. - -## Cross-repository Checkout (`checkout:`) - -The `checkout:` frontmatter field controls how `actions/checkout` is invoked in the agent job. Configure custom checkout settings, check out multiple repositories, or disable checkout entirely. - -### Disabling Checkout (`checkout: false`) - -Set `checkout: false` to suppress the default `actions/checkout` step entirely. Use this for workflows that access repositories through MCP servers or other mechanisms that do not require a local clone: - -```yaml wrap -checkout: false -``` - -This is equivalent to omitting the checkout step from the agent job. Custom dev-mode steps (such as "Checkout actions folder") are unaffected. - -### Custom Checkout Settings - -If only using the current repository, you can use `checkout:` to override default checkout settings (e.g., fetch depth, sparse checkout) without needing to define a custom job: - -```yaml wrap -checkout: - fetch-depth: 0 # Full git history - github-token: ${{ secrets.MY_TOKEN }} # Custom authentication -``` - -Or use GitHub App authentication: - -```yaml wrap -checkout: - fetch-depth: 0 - github-app: - app-id: ${{ vars.APP_ID }} - private-key: ${{ secrets.APP_PRIVATE_KEY }} -``` - -You can also use `checkout:` to check out additional repositories alongside the main repository: - -```yaml wrap -checkout: - - fetch-depth: 0 - - repository: owner/other-repo - path: ./libs/other - ref: main - github-token: ${{ secrets.CROSS_REPO_PAT }} -``` - -### Checkout Configuration Options - -| Field | Type | Description | -|-------|------|-------------| -| `repository` | string | Repository in `owner/repo` format. Defaults to the current repository. | -| `ref` | string | Branch, tag, or SHA to checkout. Defaults to the triggering ref. | -| `path` | string | Path within `GITHUB_WORKSPACE` to place the checkout. Defaults to workspace root. | -| `github-token` | string | Token for authentication. Use `${{ secrets.MY_TOKEN }}` syntax. | -| `app` | object | GitHub App credentials (`app-id`, `private-key`, optional `owner`, `repositories`). Mutually exclusive with `github-token`. | -| `fetch-depth` | integer | Commits to fetch. `0` = full history, `1` = shallow clone (default). | -| `fetch` | string \| string[] | Additional Git refs to fetch after checkout. See [Fetching Additional Refs](#fetching-additional-refs). | -| `sparse-checkout` | string | Newline-separated patterns for sparse checkout (e.g., `.github/\nsrc/`). | -| `submodules` | string/bool | Submodule handling: `"recursive"`, `"true"`, or `"false"`. | -| `lfs` | boolean | Download Git LFS objects. | -| `current` | boolean | Marks this checkout as the primary working repository. The agent uses this as the default target for all GitHub operations. Only one checkout may set `current: true`; the compiler rejects workflows where multiple checkouts enable it. | - -### Fetching Additional Refs +1. **Cross-Repository Checkout** - Check out code from other repositories +2. **Cross-Repository Reading** - Read issues, pull requests and other information from other repositories +3. **Cross-Repository Safe Outputs** - Create issues, PRs, comments, and other resources in external repositories using `target-repo` and `allowed-repos` in safe outputs -By default, `actions/checkout` performs a shallow clone (`fetch-depth: 1`) of a single ref. For workflows that need to work with other branches — for example, a scheduled workflow that must push changes to open pull-request branches — use the `fetch:` option to retrieve additional refs after the checkout step. +All require additional authentication. -A dedicated git fetch step is emitted after the `actions/checkout` step. Authentication re-uses the checkout token (or falls back to `github.token`) via a transient `http.extraheader` credential — no credentials are persisted to disk, consistent with the enforced `persist-credentials: false` policy. +## Cross-Repository Checkout (`checkout:`) -| Value | Description | -|-------|-------------| -| `"*"` | All remote branches. | -| `"refs/pulls/open/*"` | All open pull-request head refs (GH-AW shorthand). | -| `"main"` | A specific branch name. | -| `"feature/*"` | A glob pattern matching branch names. | - -```yaml wrap -checkout: - - fetch: ["*"] # fetch all branches (default checkout) - fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details -``` +The `checkout:` frontmatter field controls how `actions/checkout` is invoked in the agent job. Use it to check out one or more repositories, override fetch depth or sparse-checkout settings, fetch additional refs (e.g., all open PR branches), or disable checkout entirely with `checkout: false`. -```yaml wrap -checkout: - - repository: githubnext/gh-aw-side-repo - github-token: ${{ secrets.GH_AW_SIDE_REPO_PAT }} - fetch: ["refs/pulls/open/*"] # fetch all open PR refs after checkout - fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details -``` +For multi-repository workflows, list multiple entries to clone several repos into the workspace. Mark the agent's primary target with `current: true` when working from a central repository that targets a different repo. ```yaml wrap checkout: - - repository: org/target-repo - github-token: ${{ secrets.CROSS_REPO_PAT }} - fetch: ["main", "feature/*"] # fetch specific branches - fetch-depth: 0 # fetch full history to ensure we can see all commits and PR details + - fetch-depth: 0 # checkout this repository with full history + fetch: ["refs/pulls/open/*"] # fetch all open PR branches after checkout + - repository: owner/other-repo # another repository to check out + path: ./libs/other # path within workspace to check out to + github-token: ${{ secrets.CROSS_REPO_PAT }} # additional auth for cross-repo access ``` -:::note -If a branch you need is not available after checkout and is not covered by a `fetch:` pattern, and you're in a private or internal repo, then the agent cannot access its Git history except inefficiently, file by file, via the GitHub MCP. For private repositories, it will be unable to fetch or explore additional branches. If the branch is required and unavailable, configure the appropriate pattern in `fetch:` (e.g., `fetch: ["*"]` for all branches, or `fetch: ["refs/pulls/open/*"]` for PR branches) and recompile the workflow. -::: - -### Checkout Merging - -Multiple `checkout:` configurations can target the same path and repository. This is useful for monorepos where different parts of the repository must be merged into the same workspace directory with different settings (e.g., sparse checkout for some paths, full checkout for others). - -When multiple `checkout:` entries target the same repository and path, their configurations are merged with the following rules: - -- **Fetch depth**: Deepest value wins (`0` = full history always takes precedence) -- **Fetch refs**: Merged (union of all patterns; duplicates are removed) -- **Sparse patterns**: Merged (union of all patterns) -- **LFS**: OR-ed (if any config enables `lfs`, the merged configuration enables it) -- **Submodules**: First non-empty value wins for each `(repository, path)`; once set, later values are ignored -- **Ref/Token/App**: First-seen wins - -### Marking a Primary Repository (`current: true`) - -When a workflow running from a central repository targets a different repository, use `current: true` to tell the agent which repository to treat as its primary working target. The agent uses this as the default for all GitHub operations (creating issues, opening PRs, reading content) unless the prompt instructs otherwise. When omitted, the agent defaults to the repository where the workflow is running. - -```yaml wrap -checkout: - - repository: org/target-repo - path: ./target - github-token: ${{ secrets.CROSS_REPO_PAT }} - current: true # agent's primary target -``` +See [GitHub Repository Checkout](/gh-aw/reference/checkout/) for the full configuration reference, including fetch options, sparse checkout, merging rules, and examples. -## GitHub Tools - Reading Other Repositories +## Cross-Repository Reading -When using [GitHub Tools](/gh-aw/reference/github-tools/) to read information from repositories other than the one where the workflow is running, you must configure additional authorization. The default `GITHUB_TOKEN` is scoped to the current repository only and cannot access other repositories. +The [GitHub Tools](/gh-aw/reference/github-tools/) are used to read information such as issues and pull requests from repositories. By default, these tools can access the current repository and all public repositories (if permitted by the network firewall). This set can be further restricted by using [GitHub Repository Access Restrictions](/gh-aw/reference/github-tools/#github-repository-access-restrictions-toolsgithubrepos). -Configure the additional authentication in your GitHub Tools configuration. For example, using a PAT: +To read from other private repositories, you must configure additional authorization. Configure a PAT or GitHub App in your GitHub Tools configuration: ```yaml wrap tools: @@ -155,10 +45,14 @@ tools: github-token: ${{ secrets.CROSS_REPO_PAT }} ``` +This enables operations like: -See [GitHub Tools Reference](/gh-aw/reference/github-tools/#cross-repository-reading) for complete details on configuring cross-repository read access for GitHub Tools. +- Reading files and searching code in external repositories dynamically, even if the repository is not checked out +- Querying issues and pull requests from other repos +- Accessing commits, releases, and workflow runs across repositories +- Reading organization-level information -This authentication is for **reading** information from GitHub. Authorization for **writing** to other repositories (creating issues, PRs, comments) is configured separately, see below. +See [Additional Authentication for GitHub Tools](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools) for full details on creating a PAT, using a GitHub App, or using the magic secret `GH_AW_GITHUB_MCP_SERVER_TOKEN`. ## Cross-Repository Safe Outputs @@ -384,6 +278,7 @@ updates to each PR branch. ## Related Documentation +- [GitHub Repository Checkout](/gh-aw/reference/checkout/) - Full checkout configuration reference - [MultiRepoOps Pattern](/gh-aw/patterns/multi-repo-ops/) - Cross-repository workflow pattern - [CentralRepoOps Pattern](/gh-aw/patterns/central-repo-ops/) - Central control plane pattern - [GitHub Tools Reference](/gh-aw/reference/github-tools/) - Complete GitHub Tools configuration diff --git a/docs/src/content/docs/reference/dependabot.md b/docs/src/content/docs/reference/dependabot.md index 586623a97c1..b79fae046f1 100644 --- a/docs/src/content/docs/reference/dependabot.md +++ b/docs/src/content/docs/reference/dependabot.md @@ -1,5 +1,5 @@ --- -title: Dependabot Support +title: Dependabot Manifest Generation description: Automatic dependency manifest generation for tracking runtime dependencies in agentic workflows, enabling Dependabot to detect and update outdated tools. sidebar: order: 750 diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md index 6b6d2f2d788..1b2a14f2ffa 100644 --- a/docs/src/content/docs/reference/faq.md +++ b/docs/src/content/docs/reference/faq.md @@ -268,13 +268,21 @@ network: See [Network Permissions](/gh-aw/reference/network/) for complete configuration options. -### What is GitHub lockdown mode and when is it enabled? +### How does integrity filtering protect my workflow? -[GitHub lockdown mode](/gh-aw/reference/lockdown-mode/) is a security feature that filters content in public repositories to only show issues, pull requests, and comments from users with push access. This protects workflows from processing potentially malicious input from untrusted users. +[Integrity filtering](/gh-aw/reference/integrity/) controls which GitHub content the agent can see, filtering by **author trust** and **merge status**. The MCP gateway silently removes content below the configured `min-integrity` threshold before the AI engine sees it. -Lockdown mode is **automatically enabled** for public repositories if [Additional Authentication for GitHub Tools](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools) is configured. It is not in effect for private or internal repositories. +For **public repositories**, `min-integrity: approved` is automatically applied at runtime — restricting content to owners, members, and collaborators — even without additional authentication. -In addition, for **public repositories** where the GitHub MCP server is not explicitly configured with `lockdown` or `min-integrity`, `min-integrity: approved` is automatically applied at runtime. This provides equivalent protection — restricting content to owners, members, and collaborators — even without additional authentication. +For triage or spam-detection workflows that need to process content from all users, set `min-integrity: none` explicitly: + +```yaml wrap +tools: + github: + min-integrity: none +``` + +See [Integrity Filtering](/gh-aw/reference/integrity/) for available levels, user blocking, and approval labels. ## Configuration & Setup @@ -384,44 +392,9 @@ See [Footer Control](/gh-aw/reference/footers/) for complete documentation inclu ### My workflow fails with "Runtime import file not found" when used in a repository ruleset -When a workflow is configured as a **required status check** in a [repository ruleset](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), it runs in a restricted context that does not have access to other files in the repository. Shared files imported with the `imports:` field are loaded at runtime from the repository checkout, but this checkout is not available in the ruleset context. - -This produces an error such as: - -``` -ERR_SYSTEM: Runtime import file not found: workflows/shared/file.md -``` - -The fix is to enable `inlined-imports: true` in your workflow frontmatter. This causes the compiler to bundle all imported content directly into the compiled `.lock.yml` at compile time, so no file system access is needed at runtime: - -```aw wrap ---- -on: pull_request -engine: copilot -inlined-imports: true -imports: - - shared/common-tools.md - - shared/security-setup.md ---- - -# My Workflow - -Workflow instructions here. -``` - -After adding `inlined-imports: true`, recompile the workflow: - -```bash -gh aw compile my-workflow -``` - -> [!NOTE] -> With `inlined-imports: true`, any change to an imported file requires recompiling the workflow to take effect. The compiled `.lock.yml` must be committed and pushed for the updated content to run. - -> [!NOTE] -> `inlined-imports: true` cannot be combined with agent file imports (`.github/agents/` files). If your workflow imports a custom agent file, remove it before enabling inlined imports. +This happens because workflows configured as required status checks run in a restricted context without access to the repository file system, so runtime imports cannot be resolved. -See [Imports](/gh-aw/reference/imports/) for full documentation on the `imports:` field. +The fix is to enable `inlined-imports: true` in your workflow frontmatter so the compiler bundles all imported content into the compiled `.lock.yml` at compile time. See [Using Imports in Repository Rulesets](/gh-aw/reference/imports/#using-imports-in-repository-rulesets-inlined-imports-true) for the full details. ### My workflow checkout is very slow because my repository is a large monorepo. How can I speed it up? @@ -451,7 +424,7 @@ checkout: defaults/ ``` -The `sparse-checkout` field accepts newline-separated path patterns compatible with `actions/checkout`. See [Cross-Repository Operations](/gh-aw/reference/cross-repository/#checkout-configuration-options) for the full list of checkout configuration options. +The `sparse-checkout` field accepts newline-separated path patterns compatible with `actions/checkout`. See [GitHub Repository Checkout](/gh-aw/reference/checkout/#configuration-options) for the full list of checkout configuration options. ## Workflow Design diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md index d2ff3cc23b2..4771069bde2 100644 --- a/docs/src/content/docs/reference/frontmatter-full.md +++ b/docs/src/content/docs/reference/frontmatter-full.md @@ -1672,8 +1672,9 @@ tools: # (optional) read-only: true - # Enable lockdown mode to limit content surfaced from public repositories (only - # items authored by users with push access). Default: false + # DEPRECATED: Use 'min-integrity: approved' instead. Enable lockdown mode to limit + # content surfaced from public repositories (only items authored by users with push + # access). Default: false # (optional) lockdown: true @@ -1695,7 +1696,7 @@ tools: mounts: [] # Array of Mount specification in format 'host:container:mode' - # Guard policy: repository access configuration. Restricts which repositories the + # GitHub Tools repository access configuration. Restricts which repositories the # agent can access. Use 'all' to allow all repos, 'public' for public repositories # only, or an array of repository patterns (e.g., 'owner/repo', 'owner/*', # 'owner/prefix*'). @@ -1712,7 +1713,7 @@ tools: # Array items: Repository pattern in the format 'owner/repo', 'owner/*' (all repos # under owner), or 'owner/prefix*' (repos with name prefix) - # Guard policy: minimum required integrity level for repository access. Restricts + # GitHub Tools minimum required integrity level for repository access. Restricts # the agent to users with at least the specified permission level. # (optional) min-integrity: "none" diff --git a/docs/src/content/docs/reference/github-tools.md b/docs/src/content/docs/reference/github-tools.md index 76a11b8473c..0e632e39618 100644 --- a/docs/src/content/docs/reference/github-tools.md +++ b/docs/src/content/docs/reference/github-tools.md @@ -1,25 +1,17 @@ --- -title: GitHub Tools -description: Configure GitHub API operations, toolsets, modes, and authentication for your agentic workflows +title: GitHub Tools (for reading from GitHub) +description: Configure reading information from GitHub, including integrity filtering, repository access restrictions, cross-repository access, remote mode, and additional authentication. sidebar: order: 710 --- -Configure GitHub API operations available to your workflow through the Model Context Protocol (MCP). +The GitHub Tools (`tools.github`) allow the agentic step of your workflow to read information such as issues and pull requests from GitHub. -```yaml wrap -tools: - github: # Default read-only access (always enforced) - github: - toolsets: [repos, issues, pull_requests] # Recommended: toolset groups - mode: remote # "local" (Docker) or "remote" (hosted) - read-only: true # Always true; false is not permitted - github-token: "${{ secrets.CUSTOM_PAT }}" # Custom token -``` +In most workflows, no configuration of the GitHub Tools is necessary since they are included by default with the default toolsets. By default, this provides access to the current repository and all public repositories (if permitted by the network firewall). ## GitHub Toolsets -Enable specific API groups to improve tool selection and reduce context size: +You can enable specific API groups to increase the available tools or narrow the default selection: ```yaml wrap tools: @@ -31,50 +23,28 @@ tools: **Default**: `context`, `repos`, `issues`, `pull_requests`, `users` -Note `toolsets: [default]` expands to `[context, repos, issues, pull_requests]` (excluding `users`) since `GITHUB_TOKEN` lacks user permissions. Use a PAT for the full default set. +Some key toolsets are: -Key toolsets: **context** (user/team info), **repos** (repository operations, code search, commits, releases), **issues** (issue management, comments, reactions), **pull_requests** (PR operations), **actions** (workflows, runs, artifacts), **code_security** (scanning alerts), **discussions**, **labels**. +- `context` (user/team info) +- `repos` (repository operations, code search, commits, releases) +- `issues` (issue management, comments, reactions) +- `pull_requests` (PR operations) +- `actions` (workflows, runs, artifacts) +- `code_security` (scanning alerts) +- `discussions` (discussions and comments) +- `labels` (labels management) -## Remote vs Local Mode +Some toolsets requuire [additional authentication](#additional-authentication-for-github-tools). -**Remote Mode**: Use hosted MCP server for faster startup (no Docker). Requires [Additional Authentication for GitHub Tools](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools): +## GitHub Integrity Filtering (`tools.github.min-integrity`) -```yaml wrap -tools: - github: - mode: remote # Default: "local" (Docker) - github-token: ${{ secrets.CUSTOM_PAT }} # Required for remote mode -``` +Sets the minimum integrity level required for content the agent can access. For public repositories, `min-integrity: approved` is applied automatically. See [Integrity Filtering](/gh-aw/reference/integrity/) for levels, examples, user blocking, and approval labels. -**Local Mode**: Use Docker container for isolation. Requires `docker` tool and appropriate permissions: +## GitHub Repository Access Restrictions (`tools.github.repos`) -```yaml wrap -tools: - docker: - github: - mode: local -``` - -## Guard Policies - -Restrict which repositories and integrity levels the GitHub MCP server can access during agent execution. Guard policies apply fine-grained access control at the MCP gateway level. +You can configure the GitHub Tools to be restricted in which repositories can be accessed via the GitHub tools during AI engine execution. -For **public repositories** without explicit guard policy configuration, `min-integrity: approved` is applied automatically at runtime, ensuring content is filtered to owners, members, and collaborators even without additional authentication. See [Automatic Minimum-Integrity Protection](/gh-aw/reference/lockdown-mode/#automatic-minimum-integrity-protection) for details. - -```yaml wrap -tools: - github: - mode: remote - toolsets: [default] - repos: "all" - min-integrity: unapproved -``` - -`min-integrity` can be specified alone; `repos` defaults to `"all"` when omitted. If `repos` is also specified, both fields must be valid. - -### `repos` - -Specifies which repositories the agent can access through GitHub tools: +The setting `tools.github.repos` specifies which repositories the agent can access through GitHub tools: - `"all"` — All repositories accessible by the configured token - `"public"` — Public repositories only @@ -83,7 +53,9 @@ Specifies which repositories the agent can access through GitHub tools: - `"owner/*"` — All repositories under an owner - `"owner/prefix*"` — Repositories with a name prefix under an owner -Patterns must be lowercase. Wildcards are only permitted at the end of the repository name component. +This defaults to `"all"` when omitted. Patterns must be lowercase. Wildcards are only permitted at the end of the repository name component. + +For example: ```yaml wrap tools: @@ -97,98 +69,19 @@ tools: min-integrity: approved ``` -### `min-integrity` - -Sets the minimum integrity level required for repository access. - -#### Integrity Level Definitions - -Integrity levels are determined based on the combination of the `author_association` field associated with GitHub objects (issues, pull requests, comments, etc.) and whether an object is reachable from the main branch: - -| Level | Criteria | -|-------|----------| -| `merged` | Objects reachable from the main branch (regardless of authorship) | -| `approved` | Objects with `author_association` of `OWNER`, `MEMBER`, or `COLLABORATOR` | -| `unapproved` | Objects with `author_association` of `CONTRIBUTOR` or `FIRST_TIME_CONTRIBUTOR` | -| `none` | Objects with `author_association` of `FIRST_TIMER` or `NONE` | +### GitHub Cross-Repository Reading -**How it works:** -- **Merged content** has the highest integrity because it has been reviewed and merged into the main branch -- **Approved contributors** (owners, members, collaborators) have established trust relationships with the repository -- **Unapproved contributors** have made contributions but lack formal repository access -- **None level** includes first-time interactions and users with no prior contribution history +By default, the GitHub Tools can read from the current repository and all public repositories (if permitted by the network firewall). To read from other private repositories, you must configure additional authentication. See [Cross-Repository Operations](/gh-aw/reference/cross-repository/) for details and examples. -### Examples +## GitHub Tools Remote Mode -**Restrict to public repositories only:** +By default the GitHub Tools run in "local mode", where the GitHub MCP Server runs within the GitHub Actions VM hosting your agentic workflow. You can switch to "remote mode", which uses a hosted MCP server managed by GitHub. Remote mode requires [additional authentication](#additional-authentication-for-github-tools) and enables additional filtering and capabilities. ```yaml wrap tools: github: - repos: "public" - min-integrity: none -``` - -**Restrict to repositories in multiple organizations:** - -```yaml wrap -tools: - github: - mode: remote - toolsets: [repos, issues] - repos: - - "frontend-org/*" - - "backend-org/*" - min-integrity: approved -``` - -### Non-GitHub MCP Server Integration - -When you configure `repos` in the GitHub guard policy, the compiler automatically derives a linked write-sink guard-policy for **all non-GitHub MCP servers** — including [safe outputs](/gh-aw/reference/safe-outputs/), playwright, serena, mcp-scripts, agentic-workflows, web-fetch, and any custom tools. This ensures that as guard policies are applied to GitHub inputs, the corresponding write operations to non-GitHub servers are permitted. - -The transformation rules are: - -- **`repos: "all"` or `repos: "public"`**: Creates a write-sink policy with `accept: ["*"]` to allow all write operations -- **`repos: [patterns]`**: Each entry is transformed and added as an accept entry: - - `"owner/*"` → `"private:owner"` (owner wildcard → strip wildcard) - - `"owner/prefix*"` → `"private:owner/prefix*"` (prefix wildcard → keep as-is) - - `"owner/repo"` → `"private:owner/repo"` (specific repo → keep as-is) - -This derivation happens at compile time and requires no additional configuration, allowing the MCP gateway to read repository data through the GitHub tools and write outputs to any configured non-GitHub MCP server. - -```yaml wrap -tools: - github: - mode: remote - toolsets: [default] - repos: "public" # Creates write-sink with accept: ["*"] - min-integrity: approved -safe-outputs: - create-issue: # safe outputs can write with accept: ["*"] -``` - -```yaml wrap -tools: - github: - mode: remote - toolsets: [default] - repos: - - "myorg/private-repo" # → accept: ["private:myorg/private-repo"] - - "myorg/another-repo" # → accept: ["private:myorg/another-repo"] - min-integrity: approved -safe-outputs: - create-issue: # safe outputs can write to the guard-policy repos -``` - -## Lockdown Mode for Public Repositories - -Lockdown Mode is a security feature that filters public repository content to only show issues, PRs, and comments from users with push access. Automatically enabled for public repositories when using custom tokens. See [Lockdown Mode](/gh-aw/reference/lockdown-mode/) for complete documentation. - -```yaml wrap -tools: - github: - lockdown: true # Force enable (automatic for public repos) - lockdown: false # Disable (for workflows processing all user input) + mode: remote # Default: "local" (Docker) + github-token: ${{ secrets.CUSTOM_PAT }} # Required for remote mode ``` ## Additional Authentication for GitHub Tools @@ -202,8 +95,7 @@ This is required when your workflow requires any of the following: - Read access to GitHub org or user information - Read access to other private repos - Read access to projects -- GitHub tools [Lockdown Mode](/gh-aw/reference/lockdown-mode/) -- GitHub tools [Remote Mode](#remote-vs-local-mode) +- GitHub tools [Remote Mode](#github-tools-remote-mode) ### Using a Personal Access Token (PAT) @@ -219,12 +111,8 @@ If additional authentication is required, one way is to create a fine-grained PA - Pull requests: Read (for toolset: pull_requests) - Projects: Read (for toolset: projects) - Security Events: Read (for toolset: dependabot, code_security, secret_protection, security_advisories) - - Lockdown mode: no additional permissions required - Remote mode: no additional permissions required - Adjust based on the toolsets you configure in your workflow - - > [!NOTE] - > The `dependabot` toolset also requires the `vulnerability-alerts` GitHub App permission. If you are using a GitHub App (rather than a PAT), add `vulnerability-alerts: read` to your workflow's `permissions:` field and ensure the GitHub App is configured with this permission. See [GitHub App-Only Permissions](/gh-aw/reference/permissions/#github-app-only-permissions). - **Organization permissions** (if accessing org-level info): - Members: Read (for org member info in context) - Teams: Read (for team info in context) @@ -256,33 +144,13 @@ Alternatively, you can set the magic secret `GH_AW_GITHUB_MCP_SERVER_TOKEN` to a gh aw secrets set GH_AW_GITHUB_MCP_SERVER_TOKEN --value "" ``` -## Cross-Repository Reading - -When GitHub Tools need to read information from repositories other than the one where the workflow is running, additional authorization is required. The default `GITHUB_TOKEN` only has access to the current repository. - -Configure cross-repository read access using the same authentication methods described above: - -```yaml wrap -tools: - github: - toolsets: [repos, issues, pull_requests] - github-token: ${{ secrets.CROSS_REPO_PAT }} -``` - -This enables operations like: -- Reading files and searching code in external repositories -- Querying issues and pull requests from other repos -- Accessing commits, releases, and workflow runs across repositories -- Reading organization-level information - -> [!NOTE] -> This authorization is for **reading** from GitHub. For **writing** to other repositories (creating issues, PRs, comments), configure authentication separately through [Safe Outputs](/gh-aw/reference/safe-outputs/) with cross-repository operations. +### Using the `dependabot` toolset -For complete cross-repository workflow patterns and examples, see [Cross-Repository Operations](/gh-aw/reference/cross-repository/). +The `dependabot` toolset can only be used if authenticating with a PAT or GitHub App and also requires the `vulnerability-alerts` GitHub App permission. If you are using a GitHub App (rather than a PAT), add `vulnerability-alerts: read` to your workflow's `permissions:` field and ensure the GitHub App is configured with this permission. See [GitHub App-Only Permissions](/gh-aw/reference/permissions/#github-app-only-permissions). ## Related Documentation - [Tools Reference](/gh-aw/reference/tools/) - All tool configurations - [Authentication Reference](/gh-aw/reference/auth/) - Token setup and permissions -- [Lockdown Mode](/gh-aw/reference/lockdown-mode/) - Public repository security +- [Integrity Filtering](/gh-aw/reference/integrity/) - Public repository content filtering - [MCPs Guide](/gh-aw/guides/mcps/) - Model Context Protocol setup diff --git a/docs/src/content/docs/reference/glossary.md b/docs/src/content/docs/reference/glossary.md index b555cfccff5..787274d1202 100644 --- a/docs/src/content/docs/reference/glossary.md +++ b/docs/src/content/docs/reference/glossary.md @@ -7,10 +7,6 @@ sidebar: This glossary provides definitions for key technical terms and concepts used in GitHub Agentic Workflows. -> [!TIP] -> New to GitHub Agentic Workflows? -> Technical terms throughout the documentation link to their definitions here. Click any glossary link to understand unfamiliar concepts. Bookmark this page for quick reference! - ## Core Concepts ### Agentic @@ -71,10 +67,6 @@ A service that implements the Model Context Protocol to provide specific capabil Capabilities that an AI agent can use during workflow execution. Tools are configured in the frontmatter and include GitHub operations ([`github:`](/gh-aw/reference/github-tools/)), file editing (`edit:`), web access (`web-fetch:`, `web-search:`), shell commands (`bash:`), browser automation ([`playwright:`](/gh-aw/reference/playwright/)), and custom MCP servers. -### Guard Policy - -An access control configuration for the GitHub MCP server that restricts which repositories and content integrity levels the agent can read. Configured via `tools.github.repos` (repository scope: `"all"`, `"public"`, or a list of patterns) and `tools.github.min-integrity` (minimum required integrity level). `min-integrity` can be specified alone; `repos` defaults to `"all"` when omitted. Integrity levels by trust: `merged` (content reachable from the main branch) > `approved` (owners, members, collaborators) > `unapproved` (contributors) > `none` (first-time users). See [GitHub Tools Reference](/gh-aw/reference/github-tools/#guard-policies). - ## Security and Outputs ### MCP Scripts @@ -85,10 +77,6 @@ Custom MCP tools defined inline in workflow frontmatter using JavaScript or shel Static Analysis Results Interchange Format - a standardized JSON format for reporting results from static analysis tools. Used by GitHub Code Scanning to display security vulnerabilities and code quality issues. Workflows can generate SARIF files using the `create-code-scanning-alert` safe output. -### SBOM - -Software Bill of Materials - a comprehensive inventory of all components, libraries, and dependencies in a software project. Used for security auditing, vulnerability tracking, and compliance. Common formats include SPDX and CycloneDX. - ### Safe Outputs Pre-approved actions the AI can take without elevated permissions. The AI generates structured output describing what to create (issues, comments, pull requests), processed by separate permission-controlled jobs. Configured via `safe-outputs:` section, letting AI agents create GitHub content without direct write access. @@ -97,32 +85,18 @@ Pre-approved actions the AI can take without elevated permissions. The AI genera Automated security analysis that scans agent output and code changes for potential security issues before application. When safe outputs are configured, a threat detection job automatically runs between the agent job and safe output processing to identify prompt injection attempts, secret leaks, and malicious code patches. See [Threat Detection Reference](/gh-aw/reference/threat-detection/). -### Secrecy - -An optional field on safe output tool calls indicating the confidentiality level of the message content. Accepted values include `"public"`, `"internal"`, and `"private"`. Used alongside [`integrity`](#integrity) as security metadata displayed in safe output step summaries and available to [Threat Detection](#threat-detection) scanning. - ### Staged Mode A preview mode where workflows simulate actions without making changes. The AI generates output showing what would happen, but no GitHub API write operations are performed. Use for testing before production runs. See [Staged Mode](/gh-aw/reference/staged-mode/) for details. -### Integrity - -An optional field on safe output tool calls indicating the trustworthiness level of the message source. Accepted values include `"low"`, `"medium"`, and `"high"`. Used alongside [`secrecy`](#secrecy) as security metadata displayed in safe output step summaries and available to [Threat Detection](#threat-detection) scanning. - -### Lockdown Mode +### Integrity Filtering -A security feature of the GitHub MCP server that filters content in public repositories to only surface items (issues, pull requests, comments, discussions) from users with push access. Protects agentic workflows from processing potentially malicious or misleading content submitted by untrusted users. - -For **public repositories**, `min-integrity: approved` is automatically applied at runtime when no explicit `lockdown` or `min-integrity` guard policy is configured — providing the same filtering level as lockdown without requiring additional authentication. Explicit `lockdown: true` requires a custom `github-token` and is automatically enabled for public repositories when one is configured. Set `min-integrity: none` or `lockdown: false` to disable for workflows designed to process content from all users. See [Lockdown Mode](/gh-aw/reference/lockdown-mode/). +A guardrail feature that controls which GitHub content an agent can access, filtering by author trust and merge status. Content below the configured `min-integrity` threshold is silently removed before the AI engine sees it. The four levels are `merged`, `approved`, `unapproved`, and `none` (most to least restrictive). For public repositories, `min-integrity: approved` is applied automatically — restricting content to owners, members, and collaborators — even without additional authentication. Set `min-integrity: none` to allow all content through for workflows designed to process untrusted input (e.g., triage bots). See [Integrity Filtering](/gh-aw/reference/integrity/). ### Status Comment A comment posted on the triggering issue or pull request that shows workflow run status (started and completed). Configured via `status-comment: true` in `safe-outputs`. Must be explicitly enabled — it is not automatically bundled with `ai-reaction`. -### XPIA (Cross-Prompt Injection Attack) - -A security attack where malicious instructions embedded in external data (issue bodies, PR descriptions, file contents) attempt to hijack an AI agent's behavior. GitHub Agentic Workflows mitigates XPIA through system prompt hardening and [Threat Detection](#threat-detection) scanning. See also [Lockdown Mode](#lockdown-mode). - ### Permissions Access controls defining workflow operations. Workflows follow least privilege, starting with read-only access by default. Write operations are typically handled through safe outputs. diff --git a/docs/src/content/docs/reference/imports.md b/docs/src/content/docs/reference/imports.md index b687232cd5e..de509086019 100644 --- a/docs/src/content/docs/reference/imports.md +++ b/docs/src/content/docs/reference/imports.md @@ -214,6 +214,43 @@ Imports are processed in breadth-first order: direct imports first, then nested Remote imports are cached by commit SHA in `.github/aw/imports/`. Keep import chains shallow, use shared workflows for reusable configurations, and consolidate related imports. Every compilation records imports in the lock file manifest for dependency tracking. + +## Using Imports in Repository Rulesets (`inlined-imports: true`) + +When a workflow is configured as a **required status check** in a [repository ruleset](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets), it runs in a restricted context that does not have access to other files in the repository. Shared files imported with the `imports:` field are loaded at runtime from the repository checkout, but this checkout is not available in the ruleset context, producing an error such as: + +``` +ERR_SYSTEM: Runtime import file not found: workflows/shared/file.md +``` + +The fix is to enable `inlined-imports: true` in your workflow frontmatter. This causes the compiler to bundle all imported content directly into the compiled `.lock.yml` at compile time, so no file system access is needed at runtime: + +```aw wrap +--- +on: pull_request +engine: copilot +inlined-imports: true +imports: + - shared/common-tools.md + - shared/security-setup.md +--- + +# My Workflow + +Workflow instructions here. +``` + +After adding `inlined-imports: true`, recompile the workflow: + +```bash +gh aw compile my-workflow +``` + +> [!NOTE] +> With `inlined-imports: true`, any change to an imported file requires recompiling the workflow to take effect. The compiled `.lock.yml` must be committed and pushed for the updated content to run. +> +> `inlined-imports: true` cannot be combined with agent file imports (`.github/agents/` files). If your workflow imports a custom agent file, remove it before enabling inlined imports. + ## Best Practices **Layer configurations by scope**: Create base configurations with core tools, then extend with specialized imports. Use nested imports to build layered configurations. diff --git a/docs/src/content/docs/reference/integrity.md b/docs/src/content/docs/reference/integrity.md index 682e7e38f63..2316e1bb93a 100644 --- a/docs/src/content/docs/reference/integrity.md +++ b/docs/src/content/docs/reference/integrity.md @@ -1,11 +1,11 @@ --- -title: Integrity Filtering +title: GitHub Integrity Filtering description: How integrity filtering restricts agent access to GitHub content based on author trust and merge status, and how filtered events appear in logs. sidebar: order: 680 --- -Integrity filtering controls which GitHub content an agent can access during a workflow run. Rather than filtering by permissions, it filters by **trust**: the author association of an issue, pull request, or comment, and whether that content has been merged into the main branch. +Integrity filtering (`tools.github.min-integrity`) controls which GitHub content an agent can access during a workflow run. Rather than filtering by permissions, it filters by **trust**: the author association of an issue, pull request, or comment, and whether that content has been merged into the main branch. ## How It Works @@ -109,7 +109,7 @@ The `min-integrity` threshold check is applied after this computation. ## Default Behavior -For **public repositories**, if no `min-integrity` or `lockdown` is configured, the runtime automatically applies `min-integrity: approved`. This protects public workflows even when additional authentication has not been set up. See [Automatic Minimum-Integrity Protection](/gh-aw/reference/lockdown-mode/#automatic-minimum-integrity-protection) for details. +For **public repositories**, if no `min-integrity` is configured, the runtime automatically applies `min-integrity: approved`. This protects public workflows even when additional authentication has not been set up. For **private and internal repositories**, no guard policy is applied automatically. Content from all users is accessible by default. @@ -122,8 +122,8 @@ The right level depends on who you want the agent to see content from: - **Community triage or planning workflows**: `unapproved` — allow contributor input while excluding anonymous or first-time interactions. - **Public-data workflows or spam detection**: `none` — see all activity, but ensure the workflow's outputs are not directly applied without review. -> [!WARNING] -> Setting `min-integrity: none` on a public repository disables the automatic protection. Only use it when the workflow is explicitly designed to handle untrusted input. +> [!NOTE] +> Setting `min-integrity: none` on a public repository disables the automatic protection. Only use it when the workflow is designed to handle untrusted input. ## Examples @@ -152,7 +152,7 @@ tools: min-integrity: unapproved ``` -**Explicitly disable filtering on a public repository:** +**Explicitly disable filtering on a public repository, apart from blocked users:** ```aw wrap tools: @@ -230,18 +230,8 @@ gh aw logs --filtered-integrity This is useful when investigating whether your `min-integrity` configuration is filtering expected content or when tuning the level after observing real traffic patterns. -## Relationship to Lockdown Mode - -[Lockdown Mode](/gh-aw/reference/lockdown-mode/) is a separate but related feature of the GitHub MCP server. It filters content to users with push access. The two features can coexist: - -- `lockdown: true` filters using the GitHub MCP server's own content filter (based on push access). -- `min-integrity` filters using the MCP gateway's DIFC mechanism (based on author association and merge status). - -For most public repository workflows, `min-integrity: approved` provides equivalent protection to lockdown mode without requiring additional authentication. - ## Related Documentation -- [GitHub Tools Reference](/gh-aw/reference/github-tools/) — Full `tools.github` configuration including `repos` and guard policies -- [Lockdown Mode](/gh-aw/reference/lockdown-mode/) — GitHub MCP server content filtering for public repositories +- [GitHub Tools Reference](/gh-aw/reference/github-tools/) — Full `tools.github` configuration - [MCP Gateway](/gh-aw/reference/mcp-gateway/) — Gateway architecture and log format - [CLI Reference: logs](/gh-aw/setup/cli/#logs) — Downloading and analyzing workflow run logs diff --git a/docs/src/content/docs/reference/lockdown-mode.md b/docs/src/content/docs/reference/lockdown-mode.md index c08b045928a..c8eb1baf26a 100644 --- a/docs/src/content/docs/reference/lockdown-mode.md +++ b/docs/src/content/docs/reference/lockdown-mode.md @@ -1,129 +1,44 @@ --- title: GitHub Lockdown Mode -description: Security feature of GitHub that filters public repository content to only show items from users with push access, protecting workflows from unauthorized input manipulation. +description: GitHub lockdown mode has been superseded by Integrity Filtering, which provides finer-grained content filtering based on author trust and merge status. sidebar: order: 660 --- -**GitHub lockdown mode** is [a security feature of the GitHub MCP server](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md#lockdown-mode) that filters content in public repositories to only surface items (issues, pull requests, comments, discussions, etc.) from users with **push access** to the repository. This protects agentic workflows from processing potentially malicious or misleading content from untrusted users. +> [!NOTE] +> **GitHub Lockdown Mode is now replaced by GitHub Integrity Filtering.** Use [Integrity Filtering](/gh-aw/reference/integrity/) instead. Integrity filtering provides finer-grained control over which content the agent can see, based on author trust and merge status, and works without requiring additional authentication. -> [!IMPORTANT] -> Workflows running on public repositories must be compiled with strict mode enabled. If `strict: false` is set in the frontmatter, the workflow will fail at runtime on public repositories. See [Strict Mode](/gh-aw/reference/frontmatter/#strict-mode-strict) for details. +## Migrating to Integrity Filtering -## Automatic Minimum-Integrity Protection - -For **public repositories** where the GitHub MCP server is configured **without** explicit `lockdown` or `min-integrity` guard policy settings, `min-integrity: approved` is automatically applied at runtime. This ensures the guardrail is always in place — even when additional authentication has not been configured. - -`min-integrity: approved` restricts content to objects authored by owners, members, and collaborators (users with push access), providing the same level of content filtering as enabling lockdown mode explicitly. - -- **Public repositories**: `min-integrity: approved` is applied automatically (same filtering level as explicit lockdown mode). -- **Private/internal repositories**: No guard policy is applied automatically (`min-integrity: none`). - -The automatic guard policy does **not** apply when: -- An explicit `lockdown` or `min-integrity` value is set in the workflow frontmatter. - -To override or disable the automatic guard policy, set an explicit value: +Replace `lockdown: true` with `min-integrity: approved`: ```yaml wrap +# Before (deprecated) tools: github: - min-integrity: none # Disable automatic guard for public repo workflows that process all users -``` - -## Lockdown Mode (Content Filter) - -To enable lockdown mode for your workflow: - -1. **Set `lockdown: true` in your workflow frontmatter** -2. **Configure [Additional Authentication for GitHub Tools](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools) - -Lockdown Mode is **automatically enabled** for public repositories if [Additional Authentication for GitHub Tools](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools) is configured. It is not in effect for private or internal repositories. - -## Security Benefits - -GitHub lockdown mode protects against several attack vectors: - -### Input Manipulation - -Without lockdown, an attacker could: - -1. Create an issue with malicious code snippets or links -2. Trigger an agentic workflow (e.g., issue triage, planning assistant) -3. Attempt to hijack the workflow through prompt-injection - -**With lockdown**: Only trusted contributors' issues are visible to workflows. - -### Context Poisoning - -Attackers could flood public repositories with spam issues to: - -- Overwhelm the AI context window with noise -- Manipulate AI decisions through volume of malicious suggestions -- Exhaust rate limits or credits - -**With lockdown**: Only legitimate contributor content consumes workflow resources. - -### Social Engineering - -Malicious users could craft issues that: - -- Impersonate maintainers -- Request sensitive information -- Trick AI into revealing secrets or internal data - -**With lockdown**: Only verified contributors can interact with workflows. - -## Example - -```yaml wrap ---- -engine: copilot + lockdown: true +# After (recommended) tools: github: - lockdown: true - github-token: ${{ secrets.CUSTOM_TOKEN }} # Required for lockdown, and causes lockdown in public repos - mode: remote - toolsets: [repos, issues, pull_requests] ---- - -# Your workflow that requires lockdown protection + min-integrity: approved ``` -```bash -# Configure the required token -gh aw secrets set GH_AW_GITHUB_TOKEN --value "YOUR_FINE_GRAINED_PAT" -``` - -## Disabling Lockdown Mode - -Explicitly disable lockdown for workflows designed to process content from all users: +Replace `lockdown: false` with `min-integrity: none`: ```yaml wrap +# Before (deprecated) tools: github: - lockdown: false # Explicitly disable (see "When to Disable" below) -``` - -## When to Disable Lockdown + lockdown: false -If working in a public repository, it is recommended that you use an explicit `lockdown: true` or `lockdown: false`. - -Some workflows are **designed** to process content from all users and include appropriate safety controls. Safe use cases for `lockdown: false` in public repositories: - -- **Issue Triage**: Workflows that label, categorize, or route issues from all users -- **Issue Organization**: Workflows that add issues to projects or milestones based on labels or content -- **Issue Planning**: Workflows that estimate complexity, suggest related issues, or draft implementation plans based on issue content -- **Spam Detection**: Workflows that identify and flag spam issues or comments -- **Public Dashboards**: Workflows that generate public reports or metrics based on all repository activity -- **Command Workflows**: Workflows that respond to specific commands in issue comments (e.g., `/plan`, `/analyze`) and verify user permissions before taking action +# After (recommended) +tools: + github: + min-integrity: none +``` -## Related Documentation +## See Also -- [Authentication](/gh-aw/reference/auth/) - Token configuration and security -- [Tools](/gh-aw/reference/tools/) - GitHub tools configuration -- [Safe Outputs](/gh-aw/reference/safe-outputs/) - Write operation controls -- [Permissions](/gh-aw/reference/permissions/) - GitHub Actions permissions -- [FAQ: Lockdown Mode](/gh-aw/reference/faq/#what-is-github-lockdown-mode-and-when-is-it-enabled) - Common questions -- [Troubleshooting: Access Issues](/gh-aw/troubleshooting/common-issues/#github-lockdown-mode-blocking-expected-content) - Resolving access problems -- [GitHub MCP Server Documentation](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md#lockdown-mode) - Upstream reference +- [Integrity Filtering](/gh-aw/reference/integrity/) — Complete reference for `min-integrity`, integrity levels, user blocking, and approval labels +- [GitHub Tools Reference](/gh-aw/reference/github-tools/) — Full `tools.github` configuration diff --git a/docs/src/content/docs/reference/permissions.md b/docs/src/content/docs/reference/permissions.md index e25fc38540f..3b65e44704c 100644 --- a/docs/src/content/docs/reference/permissions.md +++ b/docs/src/content/docs/reference/permissions.md @@ -1,5 +1,5 @@ --- -title: Permissions +title: GitHub (Read Permissions) description: Configure GitHub Actions permissions for agentic workflows sidebar: order: 500 @@ -16,36 +16,33 @@ safe-outputs: add-comment: ``` -## Permission Model - -Agentic workflows follow a principle of least privilege: the main job runs read-only, and all write operations happen in separate [safe outputs](/gh-aw/reference/safe-outputs/) jobs with sanitized content. - This separation provides an audit trail, limits blast radius if an agent misbehaves, supports compliance approval gates, and defends against prompt injection. Safe outputs add one extra job but provide critical safety guarantees. ## Permission Scopes -Key permissions include `contents` (code access), `issues` (issue management), `pull-requests` (PR management), `discussions`, `actions` (workflow control), `checks`, `deployments`, `packages`, `pages`, and `statuses`. Each has read and write levels. See [GitHub's permissions reference](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) for the complete list. - -### Special Permission: `id-token` - -The `id-token` permission controls access to GitHub's OIDC token service for [OpenID Connect (OIDC) authentication](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) with cloud providers (AWS, GCP, Azure). +Key read permission scopes include: -The only valid values are `write` and `none`. `id-token: read` is not a valid permission and will be rejected at compile time. +- `contents` (code access) +- `issues` (issue management) +- `pull-requests` (PR management) +- `discussions` (discussions and comments) +- `actions` (workflow control) +- `checks` (checks and statuses) +- `deployments` (deployment management) +- `packages` (package management) +- `pages` (GitHub Pages management) +- `statuses` (commit status management) -Unlike other write permissions, `id-token: write` does not grant any ability to modify repository content. It only allows the workflow to request a short-lived OIDC token from GitHub's token service for authentication with external cloud providers. +See [GitHub's permissions reference](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) for the complete list. -```yaml wrap -# Example: Deploy to AWS using OIDC authentication -permissions: - id-token: write # Allowed for OIDC authentication - contents: read # Read repository code -``` +**Shorthand Options:** -This permission is safe to use and does not require safe-outputs, even in strict mode. +- **`read-all`**: Read access to all scopes (useful for inspection workflows) +- **`{}`**: No permissions (for computation-only workflows) ### GitHub App-Only Permissions -Certain permission scopes cannot be granted to `GITHUB_TOKEN` and are forwarded instead as inputs to [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token) when a GitHub App is configured. These scopes are omitted from the compiled workflow's `permissions:` block. +Certain permission scopes require [additional authentication](/gh-aw/reference/github-tools/#additional-authentication-for-github-tools). These include: **Repository-level:** `administration`, `environments`, `git-signing`, `vulnerability-alerts`, `workflows`, `repository-hooks`, `single-file`, `codespaces`, `repository-custom-properties` @@ -53,128 +50,24 @@ Certain permission scopes cannot be granted to `GITHUB_TOKEN` and are forwarded **User-level:** `email-addresses`, `codespaces-lifecycle-admin`, `codespaces-metadata` -These scopes must always be declared as `read`. Declaring `write` is a compile error; write operations through a GitHub App must go through [safe outputs](/gh-aw/reference/safe-outputs/), which provide a separate sanitized job for write operations. - -Declaring any of these scopes without a configured `github-app` causes a compile error. The GitHub App can be configured in `tools.github.github-app`, `safe-outputs.github-app`, or the top-level `github-app:` field — see [Tools](/gh-aw/reference/tools/) for configuration details. - -```aw wrap -permissions: - contents: read - workflows: read # GitHub App-only scope - members: read # GitHub App-only scope -tools: - github: - github-app: - app-id: ${{ vars.APP_ID }} - private-key: ${{ secrets.APP_PRIVATE_KEY }} -``` - -> [!NOTE] -> Shorthand permissions (`read-all`, `write-all`, `all: read`) do not trigger the "GitHub App required" validation. - -## Configuration - -Specify individual permission levels: - -```yaml wrap -permissions: - contents: read - actions: read -safe-outputs: - create-issue: -``` - -### Shorthand Options +These scopes must always be declared as `read`. -- **`read-all`**: Read access to all scopes (useful for inspection workflows) -- **`{}`**: No permissions (for computation-only workflows) +### Special Permission: `id-token` -> [!CAUTION] -> Avoid using `write-all` or direct write permissions in agentic workflows. Use [safe outputs](/gh-aw/reference/safe-outputs/) instead for secure write operations. +The `id-token` permission controls access to GitHub's OIDC token service for [OpenID Connect (OIDC) authentication](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect) with cloud providers (AWS, GCP, Azure). -## Common Patterns +The only valid values are `write` and `none`. `id-token: read` is not a valid permission and will be rejected at compile time. -All workflows should use read-only permissions with safe outputs for write operations: +Unlike other write permissions, `id-token: write` does not grant any ability to modify repository content. It only allows the workflow to request a short-lived OIDC token from GitHub's token service for authentication with external cloud providers. ```yaml wrap -# IssueOps: Read code, comment via safe outputs -permissions: - contents: read - actions: read -safe-outputs: - add-comment: - max: 5 - -# PR Review: Read code, review via safe outputs -permissions: - contents: read - actions: read -safe-outputs: - create-pr-review-comment: - max: 10 - -# Scheduled: Analysis with issue creation via safe outputs -permissions: - contents: read - actions: read -safe-outputs: - create-issue: - max: 3 - -# Manual: Admin tasks with approval gate -permissions: read-all -manual-approval: production -``` - -## Permission Validation - -Run `gh aw compile workflow.md` to validate permissions. Common errors include undefined permissions, direct write permissions in the main job (use safe outputs instead), and insufficient permissions for declared tools. Use `--strict` mode to enforce read-only permissions and require explicit network configuration. - -### Write Permission Policy - -Write permissions are blocked by default to enforce the security-first design. Workflows with write permissions will fail compilation with an error: - -``` -Write permissions are not allowed. - -Found write permissions: - - contents: write - -To fix this issue, change write permissions to read: +# Example: Deploy to AWS using OIDC authentication permissions: - contents: read -``` - -**Exceptions:** -- `id-token: write` is allowed for OIDC authentication with cloud providers and does not grant repository write access. -- GitHub App-only scopes (see above) always refuse `write` at compile time regardless of this policy; use [safe outputs](/gh-aw/reference/safe-outputs/) for write operations that require a GitHub App. - -#### Migrating Existing Workflows - -To migrate workflows with write permissions, use the automated codemod (recommended): -```bash -# Check what would be changed (dry-run) -gh aw fix workflow.md - -# Apply the fix -gh aw fix workflow.md --write + id-token: write # Allowed for OIDC authentication + contents: read # Read repository code ``` -This automatically converts all write permissions to read permissions. - -> [!TIP] -> For workflows that need to make changes to your repository, use [safe outputs](/gh-aw/reference/safe-outputs/) instead of write permissions. - -This validation applies only to the top-level `permissions:` configuration. Custom jobs (`jobs:`) and safe outputs jobs (`safe-outputs.job:`) can have their own permission requirements. - -### Tool-Specific Requirements - -Some tools require specific permissions to function: - -- **`agentic-workflows`**: Requires `actions: read` to access workflow logs and run data. Additionally, the `logs` and `audit` tools require the workflow actor to have **write, maintain, or admin** repository role. -- **GitHub Model Context Protocol (MCP) toolsets**: See [Tools](/gh-aw/reference/tools/) for GitHub API permission requirements - -The compiler validates these requirements and provides clear error messages when permissions are missing. +This permission does not require safe-outputs. ## Related Documentation diff --git a/docs/src/content/docs/setup/cli.md b/docs/src/content/docs/setup/cli.md index 5e9db7b497d..5b5a3876afd 100644 --- a/docs/src/content/docs/setup/cli.md +++ b/docs/src/content/docs/setup/cli.md @@ -296,7 +296,7 @@ gh aw trial ./workflow.md --host-repo owner/repo # Run directly in repository gh aw trial ./workflow.md --dry-run # Preview without executing ``` -**Options:** `-e`, `--engine`, `--auto-merge-prs`, `--repeat`, `--delete-host-repo-after`, `--logical-repo`, `--clone-repo`, `--trigger-context`, `--host-repo`, `--dry-run` +**Options:** `-e`, `--engine`, `--repeat`, `--delete-host-repo-after`, `--logical-repo`, `--clone-repo`, `--trigger-context`, `--host-repo`, `--dry-run` **Secret Handling:** API keys required for the selected engine are automatically checked. If missing from the target repository, they are prompted for interactively and uploaded. @@ -313,7 +313,7 @@ gh aw run workflow --push --ref main # Push to specific branch gh aw run workflow --json # Output triggered workflow results as JSON ``` -**Options:** `--repeat`, `--push` (see [--push flag](#the---push-flag)), `--ref`, `--auto-merge-prs`, `--enable-if-needed`, `--json/-j` +**Options:** `--repeat`, `--push` (see [--push flag](#the---push-flag)), `--ref`, `--enable-if-needed`, `--json/-j` When `--json` is set, a JSON array of triggered workflow results is written to stdout. @@ -394,7 +394,7 @@ gh aw audit 12345678 --repo owner/repo # Specify repository f The `--repo` flag accepts `owner/repo` format and is required when passing a bare numeric run ID without a full URL, allowing the command to locate the correct repository. -Logs are saved to `logs/run-{id}/` with filenames indicating the extraction level. Pre-agent failures (lockdown validation, missing secrets, binary install) surface the actual error in `failure_analysis.error_summary`. Invalid run IDs return a human-readable error. +Logs are saved to `logs/run-{id}/` with filenames indicating the extraction level. Pre-agent failures (integrity filtering, missing secrets, binary install) surface the actual error in `failure_analysis.error_summary`. Invalid run IDs return a human-readable error. #### `health` diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md index 789934af0a8..8547e6baff4 100644 --- a/docs/src/content/docs/troubleshooting/common-issues.md +++ b/docs/src/content/docs/troubleshooting/common-issues.md @@ -472,9 +472,9 @@ tools: key: memory-${{ github.workflow }}-${{ github.run_id }} ``` -## GitHub Lockdown Mode Blocking Expected Content +## Integrity Filtering Blocking Expected Content -Lockdown mode filters public repository content to show only items from users with push access. +Integrity filtering controls which content the agent can see, based on author trust and merge status. ### Symptoms @@ -482,27 +482,27 @@ Workflows can't see issues/PRs/comments from external contributors, status repor ### Cause -Lockdown is enabled by default for public repositories to protect against untrusted input. +For public repositories, `min-integrity: approved` is applied automatically, restricting visibility to owners, members, and collaborators. ### Solution -**Option 1: Keep Lockdown Enabled (Recommended)** +**Option 1: Keep the default level (Recommended)** For sensitive operations (code generation, repository updates, web access), use separate workflows, manual triggers, or approval stages. -**Option 2: Disable Lockdown (Safe Public Workflows Only)** +**Option 2: Lower the integrity level (For workflows processing all users)** -Disable only if your workflow validates input, uses restrictive safe outputs, and doesn't access secrets: +Lower the level only if your workflow validates input, uses restrictive safe outputs, and doesn't access secrets: ```yaml wrap tools: github: - lockdown: false + min-integrity: none ``` -Safe use cases: issue triage, spam detection, public dashboards with permission verification. +For community triage workflows that need contributor input but not anonymous users, `min-integrity: unapproved` is a useful middle ground. -See [Lockdown Mode](/gh-aw/reference/lockdown-mode/) for details. +See [Integrity Filtering](/gh-aw/reference/integrity/) for details. ## Workflow Failures and Debugging