Skip to content

Add verification steps and troubleshooting guidance to documentation #6549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Dec 15, 2025
Merged

Add verification steps and troubleshooting guidance to documentation #6549

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8484276
Initial plan
Copilot Dec 15, 2025
3a77bea
Add verification steps and troubleshooting context to documentation
Copilot Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions docs/src/content/docs/reference/safe-outputs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,21 @@ sidebar:

The [`safe-outputs:`](/gh-aw/reference/glossary/#safe-outputs) element of your workflow's frontmatter declares that your agentic workflow should conclude with optional automated actions based on the agentic workflow's output. This enables your workflow to write content that is then automatically processed to create GitHub issues, comments, pull requests, or add labels—all without giving the agentic portion of the workflow any write permissions.

## Why Safe Outputs?

**Safe outputs are a security feature.** Your AI agent runs with minimal permissions (read-only access by default). When the agent wants to make changes to your repository—like creating an issue, adding a comment, or opening a pull request—it cannot do so directly. Instead, it "requests" that action by writing structured output to a file.

A separate, permission-controlled job then reviews and executes these requests. This architecture provides:

- **Principle of least privilege**: The AI never has write permissions during execution
- **Defense against prompt injection**: Malicious inputs cannot trick the AI into making unauthorized changes
- **Auditability**: All requested actions are logged and can be reviewed before execution
- **Controlled blast radius**: Each safe output type has strict limits (e.g., maximum number of issues to create)

**How It Works:**
1. The agentic part of your workflow runs with minimal read-only permissions. It is given additional prompting to write its output to the special known files
1. The agentic part of your workflow runs with minimal read-only permissions. It is given additional prompting to write its output to special known files
2. The compiler automatically generates additional jobs that read this output and perform the requested actions
3. Only these generated jobs receive the necessary write permissions
3. Only these generated jobs receive the necessary write permissions—scoped precisely to what each safe output type requires

For example:

Expand All @@ -19,7 +30,7 @@ safe-outputs:
create-issue:
```

This declares that the workflow should create at most one new issue.
This declares that the workflow should create at most one new issue. The AI agent can request issue creation, but a separate job with `issues: write` permission actually creates it.

## Available Safe Output Types

Expand Down
49 changes: 49 additions & 0 deletions docs/src/content/docs/setup/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,56 @@ Start here! These commands cover the essential workflow lifecycle from setup to

**Complete command reference below** ↓

## Common Workflows for Beginners

Learn how to use CLI commands together for common development tasks:

### After creating a new workflow

```bash wrap
gh aw compile my-workflow # Check for syntax errors
gh aw run my-workflow # Test it manually (if workflow_dispatch enabled)
gh aw logs my-workflow # See what happened
```

**What each command does:**
- **`compile`**: Validates your markdown and generates the `.lock.yml` file—catches errors before running
- **`run`**: Triggers the workflow immediately in GitHub Actions (requires `workflow_dispatch` trigger)
- **`logs`**: Downloads and analyzes execution logs to see what the AI did

### When something goes wrong

```bash wrap
gh aw status # Check configuration and workflow state
gh aw logs my-workflow # Review recent execution logs
gh aw audit (run-id) # Analyze specific run in detail
```

**Finding the run-id:**
1. Go to your repository on GitHub.com
2. Click the **Actions** tab
3. Click on a workflow run from the list
4. The run-id is the number in the URL: `github.com/owner/repo/actions/runs/12345678` → run-id is `12345678`

**What each command reveals:**
- **`status`**: Shows if workflows are enabled, compiled, and their schedules
- **`logs`**: Reveals AI decisions, tool usage, network activity, and errors
- **`audit`**: Provides deep analysis of a specific run including execution metrics, failed tools, and artifacts

### Fixing common issues

```bash wrap
# Token or secret issues
gh aw secrets bootstrap --engine copilot # Check token configuration

# Workflow not found or disabled
gh aw status # List all workflows
gh aw enable my-workflow # Enable if disabled

# Syntax errors in workflow markdown
gh aw compile my-workflow --validate # Detailed validation output
gh aw fix my-workflow --write # Auto-fix deprecated fields
```

## Installation

Expand Down
32 changes: 32 additions & 0 deletions docs/src/content/docs/setup/quick-start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,38 @@ Repository secrets are encrypted and never exposed in workflow logs. Only workfl

For more information, see the [GitHub Copilot CLI documentation](https://github.com/github/copilot-cli?tab=readme-ov-file#authenticate-with-a-personal-access-token-pat).

#### Verify your setup

Before running workflows, verify everything is configured correctly:

```bash wrap
gh aw status
```

**Expected output:**
```
Workflow Engine State Enabled Schedule
──────────────────────────────────────────────────────────────
daily-team-status copilot ✓ Yes 0 9 * * 1-5
```

This confirms:
- ✓ The workflow is compiled and ready
- ✓ It's enabled for execution
- ✓ The schedule is configured correctly

:::tip[Troubleshooting]
**If the workflow isn't listed:**
- Run `gh aw compile` to compile the workflow
- Check that `.github/workflows/daily-team-status.md` exists

**If you see errors when running the workflow:**
- Verify `COPILOT_GITHUB_TOKEN` secret is set correctly in repository settings
- Check that your token has "Copilot Requests" permission
- Ensure your token hasn't expired
- Run `gh aw secrets bootstrap --engine copilot` to check token configuration
:::

### Step 4 — Trigger a workflow run

Trigger the workflow immediately in GitHub Actions:
Expand Down