examples/runnable/github-agentic-workflow.md

GitHub Agentic Workflow Variant

Template, not a guarantee of product behavior. GitHub Agentic Workflows are evolving; confirm syntax, permissions, and triggers in the official docs before relying on this. The block below is an illustrative shape, not a copy-paste workflow file.

A scheduled or event-triggered loop that runs a coding agent inside GitHub Actions. Use it when the work is tied to a repository and you want CI-style guardrails, required checks, and a pull request as the escalation path.

When to use

• The loop's intake and output are GitHub-native: issues, PRs, releases, checks.
• You want the run isolated in a container and gated by repository permissions.
• A pull request is the right place for a human to take over.

Shape

The intent is usually written in Markdown and compiled to a locked Actions workflow. The illustrative shape:

on:
  schedule: weekly
  pull_request: [opened, synchronize]   # optional event trigger
permissions: read-only by default; request the minimum the job needs
engine: a coding agent (for example Copilot CLI, Claude Code, or Codex)

job: docs-drift-check
  intake:
    - changed files since the last run
    - public docs, examples, and CLI help
  steps:
    1. For each candidate drift item, verify it against code, schema, or runtime output.
    2. Patch only verified mismatches in a new branch.
    3. Run the docs build, link check, and example checks. These are the verification gate.
  output:
    - open a pull request with the verified patches and the check results
  guardrails:
    - never edit generated files by hand
    - never push to a protected branch
    - if the checks fail, open the PR as draft and label it "needs-human"

How it maps to the Loop Contract

Contract part	In this template
Trigger	schedule: weekly, optionally plus PR events
Workspace	Containerized Actions job, isolated per run
Verification	Docs build, link check, and example checks as required gates
Durable state	The branch, the PR, and run artifacts
Budget	The Actions job timeout
Escalation	A pull request, drafted and labeled when checks fail

Guardrails

• Default to read-only permissions and request only the minimum scopes the job needs; see Securing Unattended Loops.
• Make the verification gate a real status check, not a model summary.
• Keep the escalation path a reviewable PR; never let the workflow merge its own changes to a protected branch.
• This template mirrors the docs drift pattern; start from that contract for the full version.