github-agentic-workflows

Automating cross-repo documentation with GitHub Agentic Workflows (opens in new tab)

The Aspire team used GitHub Agentic Workflows to automate documentation across its product and documentation repositories. For versions 13.3 and 13.4, the system produced 82 documentation pull requests, typically within 44.8 hours of the corresponding product change, with review from the engineer who shipped the feature. The approach combines AI-generated drafts with deterministic branch selection and tightly controlled write permissions. ## The Cross-Repository Documentation Problem - Product code lives in `microsoft/aspire`, while documentation lives in `microsoft/aspire.dev`. - The old process depended on writers discovering changes weeks later and reconstructing intent from closed pull requests. - Engineers often had limited context by the time clarification was requested. - Broad repository tokens were unacceptable, making secure cross-repository automation difficult. ## How GitHub Agentic Workflows Work - Workflows are authored as Markdown files with YAML-style frontmatter and natural-language instructions. - A compiler generates a standard GitHub Actions `.lock.yml` workflow. - An agent analyzes repository data and produces proposed actions as JSON rather than writing directly to GitHub. - A separate “safe-outputs” handler executes only explicitly permitted actions through a narrowly scoped GitHub App. - This separation provides AI flexibility while preserving security controls and auditability. ## The Automated Documentation Pipeline - The `pr-docs-check.md` workflow runs when a pull request is merged into `main` or a `release/*` branch. - A deterministic Bash script resolves the documentation target branch before the agent runs: - Product pull request milestone, such as `13.4`, maps to `release/13.4`. - Linked issue milestones are checked next. - The pull request’s base branch is used if it matches a release pattern. - Otherwise, documentation targets `main`. - The agent: - Reviews the product diff and linked issues. - Determines whether documentation is necessary. - Checks out `microsoft/aspire.dev`. - Writes documentation using the project’s existing writing conventions and Starlight/MDX components. - The workflow creates a draft documentation pull request with: - A `[docs]` title prefix. - The `docs-from-code` label. - A restricted base branch. - The documentation repository as the target. - The subject-matter expert who reviewed the original product pull request as reviewer. - A comment containing the documentation pull request link is posted back to the source pull request, while older workflow comments are minimized on reruns. ## Security Through Safe Outputs - The agent receives constrained GitHub tools and read access. - Repository access is limited through allowed repositories and a dedicated GitHub App. - Actions must use pinned, integrity-checked components through `min-integrity: approved`. - Write operations are restricted to declared safe outputs, such as creating pull requests. - Documentation changes remain drafts and are never auto-merged. ## Results and Broader Fit - The process eliminated the need for additional staff or major process training. - Documentation drafts arrive shortly after the related code is merged, while the implementation context is still fresh. - The workflow preserves human review by routing drafts to the engineer or SME who approved the feature. - Both the automation documentation and `aspire.dev` use Astro and Starlight, making the tooling and publishing environment closely aligned. The practical recommendation is to use agentic automation for drafting and routing documentation, but keep branch resolution, permissions, and final review deterministic and human-controlled. This provides much of the speed of autonomous workflows without granting an AI agent unrestricted repository write access.

Improving token efficiency in GitHub Agentic Workflows (opens in new tab)

GitHub’s Agentic Workflows can quietly accumulate substantial token costs because they run automatically in CI. GitHub improved efficiency by instrumenting token usage, auditing workflows, pruning unused MCP tools, and replacing many MCP data-fetching calls with deterministic GitHub CLI commands. Early results show that reducing context and removing unnecessary LLM reasoning can save thousands of tokens per run, though measuring true efficiency requires accounting for model choice and workload quality. ## Logging Token Usage - GitHub runs hundreds of agentic workflows against real GitHub Actions limits. - Different agent frameworks produced incompatible usage logs, so GitHub used its API proxy to normalize data across Claude CLI, Copilot CLI, and Codex CLI. - Each workflow now emits a `token-usage.jsonl` artifact containing: - Input, output, cache-read, and cache-write tokens - Model and provider - Timestamps - One record per API call - These records make it possible to compare historical runs and identify recurring sources of waste. ## Automated Auditing and Optimization - A daily **Token Usage Auditor** aggregates recent usage by workflow and reports: - Significant increases in token consumption - The most expensive workflows - Anomalous runs, such as a workflow taking 18 LLM turns instead of its usual four - A daily **Token Optimizer** examines flagged workflows, their source YAML, and recent logs. - It creates GitHub Issues with concrete inefficiencies and recommended fixes. - The auditing workflows also consume tokens, creating a feedback loop in which their own costs are monitored. ## Removing Unused MCP Tools - MCP tool names and JSON schemas are typically included in every stateless LLM request. - A GitHub MCP server with roughly 40 tools can add 10–15 KB of schema to every turn. - If a workflow uses only two tools, the other 38 create repeated overhead without adding value. - GitHub compares configured tools with actual tool calls and recommends removing unused registrations. - In smoke tests, pruning tools reduced each call’s context by 8–12 KB and saved several thousand tokens per run without changing behavior. ## Replacing MCP Calls with GitHub CLI - GitHub found larger savings by replacing MCP calls for predictable data retrieval—such as pull request diffs, file contents, and review comments—with `gh` commands. - MCP calls require an additional reasoning cycle: the model chooses a tool, constructs arguments, and processes the response. - Commands such as `gh pr diff` make deterministic API requests without involving the LLM in the retrieval step. Two migration patterns were used: - **Pre-agentic downloads** - Workflow setup steps run `gh` commands before the agent starts. - Results such as diffs and changed-file lists are saved to workspace files. - The agent reads the files directly, eliminating MCP round trips. - **In-agent CLI proxy substitution** - When data must be selected dynamically, the agent runs commands such as `gh pr view --json`. - A transparent proxy routes CLI requests to GitHub’s API without exposing credentials. - This preserves the zero-secrets security model while avoiding MCP overhead. ## Measuring Efficiency - Lower token counts do not necessarily mean better workflows; a workflow may simply be doing less work. - Model selection also affects cost. Claude Haiku and Sonnet may use similar numbers of tokens, but Haiku is substantially cheaper. - GitHub therefore uses an **Effective Tokens (ET)** metric that weights usage by token type and model cost: ```text ET = m × (1.0 × I + 0.1 × C + 4.0 × O) ``` - `m` represents the model multiplier: Haiku `0.25×`, Sonnet `1.0×`, and Opus `5.0×`. - `I` is newly processed input, `C` is cache-read tokens, and `O` is output tokens. - Output tokens receive greater weight because they are typically the most expensive component. GitHub’s experience suggests that agentic workflow authors should measure usage continuously, remove tools that workflows do not actually use, and move routine API retrieval outside the LLM reasoning loop wherever possible.

Automate repository tasks with GitHub Agentic Workflows (opens in new tab)

GitHub Agentic Workflows bring coding agents into GitHub Actions, allowing developers to describe repository tasks in Markdown instead of complex YAML. They can automate issue triage, documentation, testing, code cleanup, CI investigation, and reporting while preserving human oversight through permissions, sandboxing, logging, and review. The post presents the technology, now in technical preview, as an extension of CI/CD rather than a replacement for deterministic build and release pipelines. ## Markdown-Defined Repository Automation - Developers describe desired outcomes in plain Markdown and add the workflow to a repository. - The workflow runs in GitHub Actions using configurable coding agents such as: - GitHub Copilot CLI - Claude Code - OpenAI Codex - Because workflows operate within GitHub Actions, they benefit from repository context, audit logs, permission controls, and sandboxed execution. ## Examples of Continuous AI GitHub describes these workflows as “Continuous AI”: AI-powered automation integrated throughout the software development lifecycle. - **Issue triage:** Summarize, label, and route new issues. - **Documentation maintenance:** Update READMEs and documentation after code changes. - **Code simplification:** Find opportunities for improvement and open pull requests. - **Test improvement:** Evaluate coverage and add valuable tests. - **Quality hygiene:** Investigate CI failures and suggest targeted fixes. - **Reporting:** Produce recurring reports on repository health, activity, and trends. These tasks are difficult to implement with traditional deterministic YAML workflows because they require interpretation, judgment, and code changes. ## Relationship to CI/CD - Agentic workflows are intended to augment, not replace, existing CI/CD systems. - Traditional pipelines remain responsible for deterministic builds, tests, and releases. - Agentic workflows handle higher-level tasks involving analysis, recommendations, and repository maintenance. - GitHub Actions provides the infrastructure needed for controlled execution and observability. ## Guardrails and Human Control - Security is presented as a core design requirement, particularly against unintended behavior and prompt injection. - Workflows run with read-only permissions by default. - Write operations require explicit approval through “safe outputs,” which are designed to make changes pre-approved and reviewable. - The overall approach emphasizes inspectability, defined boundaries, and human review rather than unrestricted autonomous changes. ## Adoption Across Teams - GitHub Next reports using workflows to replace repetitive chores and assemble useful information for developers. - Home Assistant uses them to analyze large numbers of issues and identify important trends. - The Cloud Native Computing Foundation applies them to documentation automation and organizational reporting. - Carvana uses them for engineering work spanning multiple repositories. GitHub Agentic Workflows are best viewed as a controlled way to add AI judgment to repository operations. Teams should begin with focused, reviewable maintenance tasks and expand usage as they gain confidence in the workflows’ behavior and safeguards.