Automate repository tasks with GitHub Agentic Workflows

Repository automation enters the agentic era

GitHub's Agentic Workflows, now in technical preview, bring coding agents into GitHub Actions through plain-Markdown workflow definitions. The model is intentionally simple: you write natural-language instructions describing the result you want, and an AI coding agent executes them with repository context, subject to explicit guardrails.

The intended benefit is that developers wake up to a repository where issues have been triaged and labeled, CI failures have been investigated with proposed fixes, documentation matches recent code changes, and new pull requests await review — all produced under constraints the team controls.

The project originated at GitHub Next from a question about what guarded repository automation should look like in the era of AI agents. By running agentic workflows inside GitHub Actions, GitHub can offer the infrastructure for permissions, logging, auditing, sandboxing, and repository context that already underpins CI/CD.

Defining workflows in Markdown

GitHub Agentic Workflows execute as standard GitHub Actions workflows. A workflow file consists of YAML frontmatter — configuration for triggers, permissions, tools, and allowed outputs — followed by Markdown instructions that describe the job in natural language. The frontmatter binds the agent's autonomy; the Markdown expresses intent.

At runtime, the workflow can use different coding agent engines such as Copilot CLI, Claude Code, or OpenAI Codex, depending on configuration. The definition file compiles to a lock file (.lock.yml) that GitHub Actions executes.

Creating a workflow typically involves letting your coding agent help: you prompt it with your desired outcome, and it writes and validates the Markdown file for review before you commit. Manual creation is also supported using the GitHub CLI extension:

gh extension install github/gh-aw
gh aw compile

The approach aims to handle categories of automation that deterministic YAML workflows handle poorly:

• Continuous triage: summarizing, labeling, and routing new issues.
• Continuous documentation: keeping READMEs and docs aligned with code changes.
• Continuous code simplification: identifying improvements and opening PRs.
• Continuous test improvement: assessing coverage and adding high-value tests.
• Continuous quality hygiene: investigating CI failures and proposing fixes.
• Continuous reporting: producing regular repository health and activity reports.

These parallel what GitHub calls Continuous AI — the integration of AI into the software development lifecycle in a way that resembles how CI/CD extended automation to build and release. Agentic workflows complement, not replace, existing CI/CD pipelines.

Example: a daily repo report

A useful starting point is a workflow that produces a daily status report. The two files generated live in .github/workflows: the Markdown definition (daily-repo-status.md) and the compiled lock file (daily-repo-status.lock.yml).

Generate a workflow that creates a daily repo status report for a maintainer. Use the instructions at https://github.com/github/gh-aw/blob/main/create.md

After review and iteration with your coding agent, the workflow definition resembles:

--- 
on: 
  schedule: daily 
 
permissions: 
  contents: read 
  issues: read 
  pull-requests: read 
 
safe-outputs: 
  create-issue: 
    title-prefix: "[repo status] " 
    labels: [report] 
 
tools: 
  github: 
---  
 
# Daily Repo Status Report 
 
Create a daily status report for maintainers. 
 
Include 
- Recent repository activity (issues, PRs, discussions, releases, code changes) 
- Progress tracking, goal reminders and highlights 
- Project status and recommendations 
- Actionable next steps for maintainers 
 
Keep it concise and link to the relevant issues/PRs.

When the scheduled workflow runs, it opens an issue containing the generated status report:

Safety by design

Guardrails are the core of the architecture. Workflows run with read-only permissions by default. Any write operation must pass through "safe outputs" — pre-approved GitHub operations such as creating a pull request or commenting on an issue — that produce clearly reviewable artifacts. Sandboxed execution, tool allowlisting, and network isolation further constrain what the coding agent can do.

This contrasts with the common alternative of running an agent CLI directly inside a YAML workflow, which tends to grant agents broader permissions than a specific task requires. Agentic workflows instead use read-only access by default and require explicit approval for write actions, producing tighter constraints and clearer review points.

Human review remains central. Pull requests created by agents are never merged automatically; approval and merge always require a person. The broader loop — deciding what matters, what gets merged, and where to steer the repository — stays human.

Practical guidance for teams

Agentic workflows reward goal-focused instructions over engineered prompts. Define what success looks like, then let the workflow explore how to achieve it. Instructions can be broad ("improve the software") or narrow ("check that all error messages target an audience aged 10 or above").

Billing matters: each workflow run typically incurs two premium requests when using Copilot's default settings — one for agentic work and one for the guardrail check through safe outputs. Model configuration offers some cost control, and alternative agent engines have their own pricing details.

Teams adopting agentic workflows should consider these practices:

• Start with low-risk outputs — reports, comments, or drafts — before enabling PR creation.
• For code changes, begin with goal-oriented improvements: routine refactoring, test coverage, simplification.
• Make instructions for reports specific about output criteria: format, tone, links, and stopping conditions.
• Keep humans in the broader loop; approve and review everything important.
• Treat workflow Markdown as code — review it, keep it small, evolve it intentionally.

Agentic workflow designs are available through patterns such as ChatOps, DailyOps, IssueOps, ProjectOps, MultiRepoOps, and Orchestration, offering remixable templates for common scenarios. Because use cases depend heavily on a team's particular priorities, experimentation and imagination play a large part in finding where agentic automation delivers value.

Getting started with Agentic Workflows

GitHub Agentic Workflows are now available in technical preview. The feature is a joint effort between GitHub, Microsoft Research, and Azure Core Upstream, and the team is looking for community input to guide development during the preview period.

To try the workflows in your own repository, start by installing gh-aw. From there, you can add a starter workflow or generate one with AI assistance, then run it directly in your repo.

Resources for early adopters

Several resources are available for teams getting started:

• Documentation: Full API and configuration reference for Agentic Workflows.
• How they work: A technical explainer covering the underlying execution model.
• Quick start guide: Step-by-step setup instructions for your first workflow.
• Workflow gallery: A collection of example workflows from the community.

Sharing feedback and connecting with the community

Feedback is a core part of the technical preview. You can participate in the Community discussion to share your experiences and suggest what should come next. For real-time conversation, the #agentic-workflows channel in the GitHub Next Discord hosts both the team and other developers building with the platform.

The preview is open now, and the project team is eager to see what you build with GitHub Agentic Workflows.