diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md index b57c301694..88d9fc0817 100644 --- a/docs/src/content/docs/reference/faq.md +++ b/docs/src/content/docs/reference/faq.md @@ -12,13 +12,9 @@ sidebar: ### I like deterministic CI/CD. Isn't this non-deterministic? -We fully embrace the need for deterministic CI/CD, especially in build, release, and test pipelines. Agentic workflows are **100% additive** to your existing CI/CD - they don't replace or modify your deterministic pipelines. +Agentic workflows are **100% additive** to your existing CI/CD - they don't replace your deterministic build, test, or release pipelines. Think of it as **Continuous AI** alongside Continuous Integration and Continuous Deployment: a new automation layer running in GitHub Actions where security, permissions, and repository context already exist. -This is about something new and additive: **Continuous AI** in addition to **Continuous Integration** and **Continuous Deployment** - a new leg to make a trifecta. It just happens to run in GitHub Actions because that's where infrastructure for secure execution, permissions, and repository context is found. It's a new addition to your automation toolkit, not a replacement for existing workflows. - -Your build, test, and release workflows should remain fully deterministic and reproducible. Agentic workflows complement these by handling tasks that are inherently non-deterministic anyway - like triaging issues, drafting documentation, researching dependencies, or proposing code improvements for human review. Many valuable automation tasks don't require determinism. When a coding agent reviews an issue and suggests a label, or drafts release notes from commits, the exact wording doesn't need to be reproducible - it needs to be helpful. Agentic workflows excel at these judgment-based tasks while your critical CI/CD pipelines remain unchanged. - -Your first call should be reliable, deterministic CI/CD. If you use agentic workflows, you should use them for tasks that benefit from a coding agent's flexibility, not for core build and release processes that require strict reproducibility. +Your deterministic pipelines stay unchanged. Agentic workflows handle tasks where exact reproducibility doesn't matter - triaging issues, drafting documentation, researching dependencies, or proposing code improvements for human review. ## Capabilities @@ -189,18 +185,12 @@ Lockdown mode is **automatically enabled** for public repositories if [Additiona ### What is a workflow lock file? -A **workflow lock file** (`.lock.yml`) is a traditional GitHub Actions workflow generated for your workflow markdown file (`.md`). It basically contains scaffolding and guardrails around a coding agent that is going to execute your workflow prompting in GitHub Actions. When you run `gh aw compile`, the lock file will appear or update and contain a complete GitHub Actions YAML file with all guradrail hardening applied. +A **workflow lock file** (`.lock.yml`) is the compiled GitHub Actions workflow generated from your `.md` file by `gh aw compile`. It contains SHA-pinned actions, resolved imports, configured permissions, and all guardrail hardening - inspect it to see exactly what will run, with no hidden configuration. Both files should be committed to version control: -- **`.md` file**: Your source file - easy to read, edit, and understand -- **`.lock.yml` file**: The lock file - what GitHub Actions actually runs - -The lock file contains SHA-pinned actions, resolved imports, configured permissions, and all the infrastructure needed for secure execution. You can inspect it to see exactly what will run - there's no hidden configuration. - -The naming convention (`.lock.yml`) reflects that this file "locks in" the exact workflow configuration at compile time, ensuring reproducibility and auditability. If you modify the frontmatter in your `.md` file, you must recompile to update the lock file. - -When the workflow runs, the prompt itself is taken from the markdown file at runtime, so you can edit the markdown without recompiling and see changes in the next run. However, any changes to frontmatter (permissions, tools, triggers) require recompilation to update the lock file. +- **`.md` file**: Your source - edit the prompt body freely; changes take effect at the next run without recompiling +- **`.lock.yml` file**: The compiled workflow GitHub Actions actually runs; must be regenerated after any frontmatter changes (permissions, tools, triggers) ### Why do I need a token or key? @@ -245,59 +235,22 @@ If discussions are not enabled or the category lacks announcement capabilities, ### Why is my create-pull-request workflow failing with "GitHub Actions is not permitted to create or approve pull requests"? -Some organizations disable pull request creation by GitHub Actions workflows through repository or organization settings. This security policy prevents automation from creating PRs, resulting in the error: **"GitHub Actions is not permitted to create or approve pull requests."** - -**Organization Setting Location:** -- Navigate to your organization's **Settings** → **Actions** → **General** -- Look for **"Workflow permissions"** section -- Check if **"Allow GitHub Actions to create and approve pull requests"** is disabled +Some organizations block PR creation by GitHub Actions via **Settings → Actions → General → Workflow permissions**. If you can't enable it, use one of these alternatives: -**Workaround Options:** +**Automatic issue fallback (default)** — `fallback-as-issue: true` is the default; when PR creation is blocked an issue with the branch link is created instead. Requires `contents: write`, `pull-requests: write`, and `issues: write`. -If you cannot enable PR creation or prefer to keep it disabled for security reasons, you have two alternatives: - -**Option 1: Use create-issue with automatic fallback (default)** - -The `create-pull-request` safe output automatically falls back to creating an issue when PR creation is blocked: - -```yaml wrap -safe-outputs: - create-pull-request: - # fallback-as-issue: true is the default behavior - # When PR creation fails, an issue is created with branch link -``` - -This requires both `contents: write` + `pull-requests: write` (for PR attempt) and `issues: write` (for fallback). - -**Option 2: Use create-issue directly with Copilot coding agent assignment** - -Create an issue describing the desired changes and assign it to Copilot coding agent for automated implementation: +**Assign to Copilot** — create an issue assigned to `copilot` for automated implementation: ```yaml wrap safe-outputs: create-issue: - assignees: [copilot] # Assign to Copilot for PR creation - labels: [automation, enhancement] # Add tracking labels + assignees: [copilot] + labels: [automation, enhancement] ``` -When assigned to Copilot, the issue can be automatically picked up for processing in a separate workflow or manually reviewed by the Copilot coding agent to create the PR. - -**Option 3: Disable issue fallback to save permissions** - -If you only want PR creation (no fallback), disable the issue fallback to avoid requiring `issues: write`: - -```yaml wrap -safe-outputs: - create-pull-request: - fallback-as-issue: false # Only attempt PR creation -``` - -This requires only `contents: write` + `pull-requests: write`, but workflows will fail if PR creation is blocked at the organization level. - -> [!TIP] -> For workflows that need to work across different organizations with varying PR policies, use the default `fallback-as-issue: true` behavior. This ensures workflows gracefully adapt to organization settings. +**Disable fallback** — set `fallback-as-issue: false` to skip the issue fallback and only attempt PR creation. Requires only `contents: write` and `pull-requests: write`, but the workflow will fail if PR creation is blocked. -See [Pull Request Creation](/gh-aw/reference/safe-outputs/#pull-request-creation-create-pull-request) for complete configuration details and the fallback mechanism explanation. +See [Pull Request Creation](/gh-aw/reference/safe-outputs/#pull-request-creation-create-pull-request) for details. ### Why don't pull requests created by agentic workflows trigger my CI checks?