From 2ee329786877051c5cb6de13a09264af85e7a8a2 Mon Sep 17 00:00:00 2001 From: Bruno Borges Date: Fri, 27 Feb 2026 17:00:55 -0500 Subject: [PATCH 1/2] Add Agentic Workflows article to Learning Hub Covers what agentic workflows are, how to consume community workflows from Awesome Copilot, and how to contribute new ones. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- website/src/config/learning-hub.ts | 1 + .../content/learning-hub/agentic-workflows.md | 219 ++++++++++++++++++ 2 files changed, 220 insertions(+) create mode 100644 website/src/content/learning-hub/agentic-workflows.md diff --git a/website/src/config/learning-hub.ts b/website/src/config/learning-hub.ts index 0fbe9dc2e..b68a57e38 100644 --- a/website/src/config/learning-hub.ts +++ b/website/src/config/learning-hub.ts @@ -10,6 +10,7 @@ export const fundamentalsOrder = [ 'building-custom-agents', 'understanding-mcp-servers', 'automating-with-hooks', + 'agentic-workflows', 'using-copilot-coding-agent', 'installing-and-using-plugins', 'before-after-customization-examples', diff --git a/website/src/content/learning-hub/agentic-workflows.md b/website/src/content/learning-hub/agentic-workflows.md new file mode 100644 index 000000000..a9d8f61ac --- /dev/null +++ b/website/src/content/learning-hub/agentic-workflows.md @@ -0,0 +1,219 @@ +--- +title: 'Agentic Workflows' +description: 'Learn what GitHub Agentic Workflows are, how to use community workflows from Awesome Copilot, and how to contribute your own.' +authors: + - GitHub Copilot Learning Hub Team +lastUpdated: '2026-02-27' +estimatedReadingTime: '7 minutes' +tags: + - workflows + - automation + - github-actions + - fundamentals +relatedArticles: + - ./automating-with-hooks.md + - ./using-copilot-coding-agent.md +prerequisites: + - Basic understanding of GitHub Actions + - Basic understanding of GitHub Copilot +--- + +Agentic Workflows are AI-powered repository automations that run coding agents in GitHub Actions. Written in markdown with natural language instructions, they let you automate tasks like issue triage, daily reports, and compliance checks — triggered by schedules, events, or slash commands. + +This article covers what agentic workflows are, how to install and use workflows from the Awesome Copilot community, and how to contribute your own. + +## What Are Agentic Workflows? + +An agentic workflow is a markdown file that combines YAML frontmatter (triggers, permissions, safe outputs) with natural language instructions that a coding agent follows at runtime. When triggered, GitHub Actions compiles the workflow and runs a Copilot coding agent that executes the instructions autonomously. + +**Key characteristics**: +- Defined in a single `.md` file — no YAML actions syntax required +- Triggered by schedules, repository events, or slash commands +- Run inside GitHub Actions with the Copilot coding agent +- Use least-privilege permissions and safe outputs for security +- Compiled to `.lock.yml` files via the `gh aw` CLI + +### Anatomy of a Workflow File + +```markdown +--- +name: "Daily Issues Report" +description: "Generates a daily summary of open issues" +on: + schedule: daily on weekdays +permissions: + contents: read + issues: read +safe-outputs: + create-issue: + title-prefix: "[daily-report] " + labels: [report] +--- + +## Daily Issues Report + +Create a daily summary of open issues for the team. + +## What to Include + +- New issues opened in the last 24 hours +- Issues closed or resolved +- Stale issues that need attention +``` + +The **frontmatter** declares the workflow's triggers, permissions, and safe outputs. The **body** contains the natural language instructions the agent follows. + +### When to Use Agentic Workflows + +| Use Case | Example | +|----------|---------| +| Scheduled reports | Daily issue summaries, weekly org health checks | +| Event-driven automation | Triage new issues, check PR relevance | +| Slash commands | `/relevance-check` on an issue or PR | +| Compliance checks | License audits, release readiness reviews | +| Repository maintenance | Identify stale repos, track contributor activity | + +Agentic Workflows are ideal when you need **autonomous, event-driven automation** that goes beyond what static GitHub Actions can do — tasks that require reasoning, summarization, or context-aware decisions. + +## Using Workflows from Awesome Copilot + +The [Awesome Copilot workflows page](../../workflows/) hosts a growing collection of community-contributed workflows. Here's how to install and use them. + +### Prerequisites + +Install the `gh aw` CLI extension: + +```bash +gh extension install github/gh-aw +``` + +### Installing a Workflow + +1. **Browse** the [workflows collection](../../workflows/) and find one that fits your needs +2. **Copy** the workflow `.md` file into your repository's `.github/workflows/` directory +3. **Compile** the workflow to generate the Actions lock file: + +```bash +gh aw compile +``` + +4. **Commit** both the `.md` source and the generated `.lock.yml` file: + +```bash +git add .github/workflows/daily-issues-report.md +git add .github/workflows/daily-issues-report.lock.yml +git commit -m "Add daily issues report workflow" +``` + +### Running a Workflow + +Workflows run automatically based on their configured triggers. You can also: + +- **Trigger manually**: `gh aw run ` +- **Monitor runs**: `gh aw status` and `gh aw logs` +- **Validate locally**: `gh aw compile --validate --no-emit .md` + +### Customizing a Workflow + +Since workflows are plain markdown, customizing them is straightforward: + +- **Edit the instructions** in the body to adjust what the agent does +- **Change triggers** in the `on:` frontmatter to control when it runs +- **Adjust permissions** to match your repository's needs +- **Modify safe outputs** to control what the agent can create or update + +After editing, recompile with `gh aw compile` to regenerate the lock file. + +## Contributing Workflows + +Sharing your workflows with the community helps others automate their repositories. Here's how to contribute. + +### Step 1: Create the Workflow File + +Create a new `.md` file in the `workflows/` directory of the [Awesome Copilot repository](https://github.com/github/awesome-copilot). Use a descriptive, lowercase, hyphenated filename: + +``` +workflows/my-new-workflow.md +``` + +### Step 2: Add Frontmatter + +Include the required frontmatter fields: + +```yaml +--- +name: "My New Workflow" +description: "A clear description of what this workflow does" +on: + schedule: daily +permissions: + contents: read +safe-outputs: + create-issue: + title-prefix: "[my-workflow] " + labels: [automated] +--- +``` + +**Required fields**: +- `name` — human-readable workflow name +- `description` — concise summary of the workflow's purpose + +**Workflow fields**: +- `on` — trigger configuration (schedules, events, slash commands) +- `permissions` — GitHub API scopes (use least-privilege) +- `safe-outputs` — guardrails for what the agent can create or modify + +### Step 3: Write Clear Instructions + +The body of the file contains the natural language instructions the agent follows. Be specific and structured: + +```markdown +## Task Overview + +Describe the main goal clearly. + +## Steps + +1. First, gather the relevant data +2. Then, analyze and summarize +3. Finally, create the output (issue, comment, etc.) + +## Output Format + +Describe the expected format of the result. +``` + +### Step 4: Validate and Test + +```bash +# Validate the workflow compiles correctly +gh aw compile --validate --no-emit workflows/my-new-workflow.md +``` + +### Step 5: Submit Your Contribution + +1. Fork the repository and create a new branch +2. Add your workflow `.md` file to the `workflows/` directory +3. Run `npm run build` to update the README +4. Submit a pull request targeting the `staged` branch + +> **Important:** Only submit the `.md` source file. Do not include compiled `.lock.yml` or `.yml` files — CI will block them. + +### Workflow Contribution Guidelines + +- **Security first** — use least-privilege permissions and safe outputs instead of direct write access +- **Clear instructions** — write specific, unambiguous natural language in the workflow body +- **Descriptive names** — use lowercase filenames with hyphens (e.g., `daily-issues-report.md`) +- **Test locally** — validate with `gh aw compile --validate` before submitting +- **Document the purpose** — the `description` field should make it clear what the workflow does and when to use it + +## Learn More + +- **Official documentation**: [GitHub Agentic Workflows](https://gh.io/gh-aw) — full specification and reference +- **Browse workflows**: [Awesome Copilot Workflows](../../workflows/) — community-contributed collection +- **Contributing guide**: [CONTRIBUTING.md](https://github.com/github/awesome-copilot/blob/main/CONTRIBUTING.md#adding-agentic-workflows) — detailed contribution guidelines +- **Related**: [Automating with Hooks](../automating-with-hooks/) — deterministic automation for Copilot agent sessions +- **Related**: [Using the Copilot Coding Agent](../using-copilot-coding-agent/) — the agent that powers agentic workflows + +--- From bf996cf7e0d5e367ec98d5ae05705240102eae40 Mon Sep 17 00:00:00 2001 From: Bruno Borges Date: Fri, 27 Feb 2026 17:05:31 -0500 Subject: [PATCH 2/2] Update website/src/content/learning-hub/agentic-workflows.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- website/src/content/learning-hub/agentic-workflows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/src/content/learning-hub/agentic-workflows.md b/website/src/content/learning-hub/agentic-workflows.md index a9d8f61ac..ccc95a162 100644 --- a/website/src/content/learning-hub/agentic-workflows.md +++ b/website/src/content/learning-hub/agentic-workflows.md @@ -24,7 +24,7 @@ This article covers what agentic workflows are, how to install and use workflows ## What Are Agentic Workflows? -An agentic workflow is a markdown file that combines YAML frontmatter (triggers, permissions, safe outputs) with natural language instructions that a coding agent follows at runtime. When triggered, GitHub Actions compiles the workflow and runs a Copilot coding agent that executes the instructions autonomously. +An agentic workflow is a markdown file that combines YAML frontmatter (triggers, permissions, safe outputs) with natural language instructions that a coding agent follows at runtime. The markdown file is the source: you use the `gh aw` CLI to compile it into a `.lock.yml` workflow file, and GitHub Actions runs that compiled workflow to execute a Copilot coding agent that follows the instructions autonomously. **Key characteristics**: - Defined in a single `.md` file — no YAML actions syntax required