Agentic Workflows¶

ContextHarness uses GitHub Agentic Workflows to keep documentation automatically in sync with code changes. When a pull request is opened against main, an AI agent reviews the diff and updates the docs as part of the same PR.

What Are Agentic Workflows?¶

GitHub Agentic Workflows (gh-aw) are AI-powered automation that run in response to repository events. Unlike traditional GitHub Actions that execute scripts, agentic workflows give an AI agent access to tools (GitHub API, file editing, bash) and let it reason about what to do.

Key characteristics:

• Markdown-based: Workflows are defined as .md files in .github/workflows/ with YAML frontmatter
• Tool-equipped: Agents can use GitHub API, edit files, and run commands
• Safe outputs: Write operations (pushing to branches, commenting on PRs) go through a safety layer
• Defense-in-depth: Sandboxed execution, tool allowlisting, network isolation, and output sanitization

Continuous Documentation¶

The update-docs.md agentic workflow implements continuous documentation — a pattern where documentation is treated as a living artifact that evolves with the code, not as an afterthought.

How It Works¶

Developer opens PR → Agentic Workflow triggers → AI reviews diff
                                                        │
                                    ┌───────────────────┴───────────────────┐
                                    │                                       │
                              Code changes?                          Docs-only change?
                                    │                                       │
                                    ▼                                       ▼
                          Update relevant docs                        Skip (no-op)
                                    │
                                    ▼
                          Commit docs back to PR

1. A developer opens or updates a PR against main
2. The agentic workflow triggers on pull_request events (opened, synchronize)
3. The AI agent analyzes the code diff to understand what changed
4. It checks all documentation pages for gaps or outdated content
5. If updates are needed, it edits the docs and commits them back to the PR branch
6. The developer reviews both code and doc changes together

What Gets Updated¶

The agent monitors and updates these documentation files:

Skip Conditions¶

The agent intentionally skips documentation updates when a PR only contains:

• CI/CD workflow changes (.github/workflows/*.yml)
• Test-only changes (tests/)
• Dependency updates with no API changes
• Formatting or linting fixes

Setup¶

Prerequisites¶

• A GitHub repository with GitHub Copilot enabled
• The gh-aw CLI extension installed locally

Install the gh-aw Extension¶

gh extension install github/gh-aw

Compile the Lock File¶

Agentic workflows require a compiled .lock.yml file alongside the .md workflow file. The lock file is generated from the frontmatter:

gh aw compile

This creates .github/workflows/update-docs.lock.yml from .github/workflows/update-docs.md.

Verify¶

After committing both files and pushing to a branch, open a PR against main. The agentic workflow should appear in the PR's checks.

Workflow File Reference¶

The agentic workflow is defined in .github/workflows/update-docs.md:

---
name: Update Documentation
on:
  pull_request:
    types: [opened, synchronize]
    branches: [main]
tools:
  github:
  edit:
  bash: true
safe-outputs:
  push-to-pull-request-branch:
    max: 1
permissions:
  contents: read
  pull-requests: read
  issues: read
---

Frontmatter Fields¶

Tools¶

Safe Outputs¶

Safe outputs are the mechanism for write operations. The agent runs with read-only permissions by default; write operations go through a safety layer that validates them.

For this workflow, we use push-to-pull-request-branch to commit documentation updates back to the PR.

Customization¶

Modifying the Workflow¶

Edit .github/workflows/update-docs.md to change the agent's behavior:

• Add or remove documentation files from the monitoring list
• Adjust skip conditions
• Change quality standards
• Add project-specific instructions

After editing, recompile the lock file:

gh aw compile

Adding More Agentic Workflows¶

You can create additional agentic workflows for other tasks:

• Code review: Automated code review on PRs
• Issue triage: Automatically label and categorize issues
• Release notes: Generate release notes from commit history
• Test generation: Suggest tests for uncovered code

Each workflow follows the same pattern: a .md file with frontmatter + instructions, compiled to a .lock.yml.

Billing¶

Each agentic workflow run consumes approximately 2 premium Copilot requests:

1. One request for the actual work
2. One request for a guardrail safety check

This is billed against your GitHub Copilot subscription's premium request quota.

Security¶

Agentic workflows use a defense-in-depth security model:

• Sandboxed execution: Workflows run in isolated environments
• Tool allowlisting: Only explicitly declared tools are available
• Network isolation: Limited network access
• Output sanitization: All outputs are validated before being applied
• Read-only by default: Write operations require explicit safe-outputs declaration
• Guardrail checks: An independent AI verifies the safety of each run's output

Troubleshooting¶

Workflow Not Triggering¶

• Verify both .md and .lock.yml files are committed
• Check that the PR targets the main branch
• Ensure GitHub Copilot is enabled for the repository
• Verify the gh aw compile output matches the current .md file

Workflow Runs but Makes No Changes¶

This is expected when:

• The PR only contains skip-condition changes (tests, CI, formatting)
• Documentation is already up to date
• The diff doesn't introduce user-facing changes

Lock File Out of Sync¶

If the workflow behaves unexpectedly, recompile:

gh aw compile

Then commit and push the updated .lock.yml.