From c7da9a16cf7e9a394e37b5cc2791572e7c724d4e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Jan 2026 21:44:59 +0000 Subject: [PATCH 1/5] Initial plan From 8c8bfc474ba493e42cf7fecad6f0152f784cadc8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Jan 2026 21:50:35 +0000 Subject: [PATCH 2/5] Initial plan for updating agentic authoring documentation Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .github/aw/actions-lock.json | 5 +++++ .github/workflows/go-pattern-detector.lock.yml | 2 +- .github/workflows/release.lock.yml | 4 ++-- .github/workflows/super-linter.lock.yml | 2 +- .github/workflows/unbloat-docs.lock.yml | 2 +- 5 files changed, 10 insertions(+), 5 deletions(-) diff --git a/.github/aw/actions-lock.json b/.github/aw/actions-lock.json index 6e52975040..fb2eed827c 100644 --- a/.github/aw/actions-lock.json +++ b/.github/aw/actions-lock.json @@ -30,6 +30,11 @@ "version": "v5", "sha": "93cb6efe18208431cddfb8368fd83d5badbf9bfd" }, + "actions/checkout@v6": { + "repo": "actions/checkout", + "version": "v6", + "sha": "8e8c483db84b4bee98b60c0593521ed34d9990e8" + }, "actions/checkout@v6.0.2": { "repo": "actions/checkout", "version": "v6.0.2", diff --git a/.github/workflows/go-pattern-detector.lock.yml b/.github/workflows/go-pattern-detector.lock.yml index 390d9b5a58..0e09ce4394 100644 --- a/.github/workflows/go-pattern-detector.lock.yml +++ b/.github/workflows/go-pattern-detector.lock.yml @@ -951,7 +951,7 @@ jobs: found_patterns: ${{ steps.detect.outputs.found_patterns }} steps: - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 with: persist-credentials: false - name: Install ast-grep diff --git a/.github/workflows/release.lock.yml b/.github/workflows/release.lock.yml index 08717f4bea..87c57e3088 100644 --- a/.github/workflows/release.lock.yml +++ b/.github/workflows/release.lock.yml @@ -993,7 +993,7 @@ jobs: release_tag: ${{ steps.compute_config.outputs.release_tag }} steps: - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 with: fetch-depth: 0 persist-credentials: false @@ -1286,7 +1286,7 @@ jobs: release_id: ${{ steps.get_release.outputs.release_id }} steps: - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 with: fetch-depth: 0 persist-credentials: true diff --git a/.github/workflows/super-linter.lock.yml b/.github/workflows/super-linter.lock.yml index 3e413207fb..31bf2569a5 100644 --- a/.github/workflows/super-linter.lock.yml +++ b/.github/workflows/super-linter.lock.yml @@ -1291,7 +1291,7 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 with: fetch-depth: 0 persist-credentials: false diff --git a/.github/workflows/unbloat-docs.lock.yml b/.github/workflows/unbloat-docs.lock.yml index 490741fd6e..00edb73121 100644 --- a/.github/workflows/unbloat-docs.lock.yml +++ b/.github/workflows/unbloat-docs.lock.yml @@ -132,7 +132,7 @@ jobs: - name: Create gh-aw temp directory run: bash /opt/gh-aw/actions/create_gh_aw_tmp_dir.sh - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6 with: persist-credentials: false - name: Setup Node.js From d25700fafe706a67e56fa6bd171d91115b32433c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Jan 2026 21:52:53 +0000 Subject: [PATCH 3/5] Update agentic authoring documentation with new title and GitHub web interface approach Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/astro.config.mjs | 2 +- .../content/docs/setup/agentic-authoring.mdx | 84 ++++++++++++++++--- 2 files changed, 72 insertions(+), 14 deletions(-) diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 05097a202c..736cca125a 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -155,7 +155,7 @@ export default defineConfig({ label: 'Setup', items: [ { label: 'Quick Start', link: '/setup/quick-start/' }, - { label: 'Creating Workflows', link: '/setup/agentic-authoring/' }, + { label: 'Agentic Authoring', link: '/setup/agentic-authoring/' }, { label: 'CLI Commands', link: '/setup/cli/' }, { label: 'VS Code Integration', link: '/setup/vscode/' }, ], diff --git a/docs/src/content/docs/setup/agentic-authoring.mdx b/docs/src/content/docs/setup/agentic-authoring.mdx index e28e8f0823..d6eb320dec 100644 --- a/docs/src/content/docs/setup/agentic-authoring.mdx +++ b/docs/src/content/docs/setup/agentic-authoring.mdx @@ -1,30 +1,34 @@ --- -title: Creating Workflows -description: How to create agentic workflows using the custom agent in VS Code to author workflows in natural language. +title: Agentic Authoring of Workflows +description: How to create agentic workflows using GitHub Copilot through the GitHub web interface to author workflows in natural language. sidebar: order: 1 --- import CopyEntireFileButton from '../../../components/CopyEntireFileButton.astro'; -GitHub Agentic Workflows provide agents that turn GitHub Copilot into -a powerful workflow authoring tool. This guide explains how to use these agents to author agentic workflows in natural language. +GitHub Agentic Workflows enable you to create powerful automation workflows using natural language through GitHub Copilot. Everything can be done through the **GitHub web interface** - no local development environment or VS Code is required. ## Quick Start -Initialize your repository to set up GitHub Copilot instructions and prompts for authoring agentic workflows: +Initialize your repository for agentic workflows by starting a GitHub Copilot agent session in **github.com** with this prompt: -```bash wrap -gh aw init +```text wrap +Initialize the repository for GitHub Agentic Workflows using https://github.com/githubnext/gh-aw/blob/main/copilot-setup.md ``` -This creates: +This will guide the Copilot agent to: +1. Install the `gh-aw` CLI extension +2. Run `gh aw init` to create necessary configuration files +3. Commit and push the changes + +After initialization, you'll have: - `.github/aw/github-agentic-workflows.instructions.md` - Custom Copilot instructions for better workflow authoring - `.github/agents/agentic-workflows.agent.md` - [Agent file](/gh-aw/reference/glossary/#agent-files) (custom AI instructions) for the `/agent agentic-workflows` command in Copilot Chat +- Additional configuration files for workflow authoring -:::tip[VS Code integration] -Once initialized, GitHub Copilot will automatically use these instructions when you edit workflow files in VS Code. See [VS Code Integration](/gh-aw/setup/vscode/) for more details. -::: +> [!TIP] +> While VS Code integration is available for advanced workflows, it's entirely optional. You can create and manage all workflows directly through the GitHub web interface using Copilot agent sessions. ## What is the `agentic-workflows` agent? @@ -40,7 +44,7 @@ The agent intelligently determines your intent and loads the appropriate special ## How to use the `agentic-workflows` agent -In Visual Studio Code with GitHub Copilot Chat, or in the interactive Copilot CLI session, invoke the agent with the `/agent` command and specify your intent: +In GitHub Copilot Chat (on github.com or in VS Code), or in the interactive Copilot CLI session, invoke the agent with the `/agent` command and specify your intent: ```sh wrap # Create a new workflow @@ -94,6 +98,60 @@ To use the agentic-chat instructions: The assistant uses a neutral, technical tone and focuses on what needs to be done rather than how to implement it, making it ideal for creating specifications that AI coding agents can execute. -## After compiling +## Editing Workflows: Prompt vs Frontmatter + +When working with workflow files (`.md` files), it's important to understand the difference between the two main components: + +### Workflow Prompt (Markdown Body) + +The **workflow prompt** is the main markdown content that describes what you want the agent to do. This is the natural language task description. + +- **Location**: The main body of the `.md` file (below the frontmatter) +- **Purpose**: Describes the task for the AI agent to execute +- **Editing**: Can be edited directly without recompilation +- **Example**: + ```markdown + Triage the issue by analyzing its content, assigning appropriate labels, + and adding a comment with your analysis. + ``` + +> [!TIP] +> You can edit the workflow prompt directly through the GitHub web interface. Changes to the prompt take effect immediately in the next workflow run - no compilation needed. + +### Frontmatter Configuration + +The **frontmatter** is the YAML configuration block at the top of the workflow file that defines triggers, tools, permissions, and other settings. + +- **Location**: Between `---` delimiters at the top of the `.md` file +- **Purpose**: Configures how the workflow runs (triggers, tools, permissions, etc.) +- **Editing**: **Requires recompilation** after changes +- **Example**: + ```yaml + --- + engine: copilot + on: + issues: + types: [opened] + tools: + github: + toolsets: [issues] + --- + ``` + +> [!WARNING] +> After editing frontmatter configuration, you **must recompile** the workflow to regenerate the `.lock.yml` file: +> ```bash +> gh aw compile workflow-name.md +> ``` +> The `.lock.yml` file is the compiled GitHub Actions workflow that actually runs. Changes to frontmatter won't take effect until you recompile and commit the updated `.lock.yml` file. + +### Quick Reference + +| What you're editing | Needs recompilation? | What it affects | +|---------------------|---------------------|-----------------| +| Markdown body (prompt) | ❌ No | The task description the agent receives | +| Frontmatter (YAML config) | ✅ Yes | Triggers, tools, permissions, and workflow settings | + +## After Compiling Commit the generated files ([`.lock.yml`](/gh-aw/reference/glossary/#workflow-lock-file-lockyml), the compiled GitHub Actions workflow file) if they are part of the project's tracked artifacts. The project uses compiled workflows in version control. From 381a3af9b90c2fd89558a4fe05fd2ca61d5c7f67 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Jan 2026 22:01:10 +0000 Subject: [PATCH 4/5] Address PR feedback: remove TIP and emphasize GitHub Copilot usage Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/src/content/docs/setup/agentic-authoring.mdx | 5 +---- pkg/workflow/data/action_pins.json | 5 +++++ 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/setup/agentic-authoring.mdx b/docs/src/content/docs/setup/agentic-authoring.mdx index d6eb320dec..a026fcfe04 100644 --- a/docs/src/content/docs/setup/agentic-authoring.mdx +++ b/docs/src/content/docs/setup/agentic-authoring.mdx @@ -7,7 +7,7 @@ sidebar: import CopyEntireFileButton from '../../../components/CopyEntireFileButton.astro'; -GitHub Agentic Workflows enable you to create powerful automation workflows using natural language through GitHub Copilot. Everything can be done through the **GitHub web interface** - no local development environment or VS Code is required. +This experience uses GitHub Copilot to create powerful automation workflows using natural language. Everything can be done through the **GitHub web interface** - no local development environment or VS Code is required. ## Quick Start @@ -27,9 +27,6 @@ After initialization, you'll have: - `.github/agents/agentic-workflows.agent.md` - [Agent file](/gh-aw/reference/glossary/#agent-files) (custom AI instructions) for the `/agent agentic-workflows` command in Copilot Chat - Additional configuration files for workflow authoring -> [!TIP] -> While VS Code integration is available for advanced workflows, it's entirely optional. You can create and manage all workflows directly through the GitHub web interface using Copilot agent sessions. - ## What is the `agentic-workflows` agent? `.github/agents/agentic-workflows.agent.md` is a unified dispatcher agent that routes your workflow requests to specialized prompts based on your intent. An [agent file](/gh-aw/reference/glossary/#agent-files) is a specialized instruction set that customizes AI behavior for specific tasks. diff --git a/pkg/workflow/data/action_pins.json b/pkg/workflow/data/action_pins.json index 6e52975040..fb2eed827c 100644 --- a/pkg/workflow/data/action_pins.json +++ b/pkg/workflow/data/action_pins.json @@ -30,6 +30,11 @@ "version": "v5", "sha": "93cb6efe18208431cddfb8368fd83d5badbf9bfd" }, + "actions/checkout@v6": { + "repo": "actions/checkout", + "version": "v6", + "sha": "8e8c483db84b4bee98b60c0593521ed34d9990e8" + }, "actions/checkout@v6.0.2": { "repo": "actions/checkout", "version": "v6.0.2", From 7d618df86f8ce23108a224d2eb0e69620cd8881c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 26 Jan 2026 22:10:31 +0000 Subject: [PATCH 5/5] Add recommended approach: use agentic-workflows agent for editing workflows Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../content/docs/setup/agentic-authoring.mdx | 26 ++++++++++++++----- 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/docs/src/content/docs/setup/agentic-authoring.mdx b/docs/src/content/docs/setup/agentic-authoring.mdx index a026fcfe04..67ba784429 100644 --- a/docs/src/content/docs/setup/agentic-authoring.mdx +++ b/docs/src/content/docs/setup/agentic-authoring.mdx @@ -95,9 +95,21 @@ To use the agentic-chat instructions: The assistant uses a neutral, technical tone and focuses on what needs to be done rather than how to implement it, making it ideal for creating specifications that AI coding agents can execute. -## Editing Workflows: Prompt vs Frontmatter +## Editing Workflows -When working with workflow files (`.md` files), it's important to understand the difference between the two main components: +### Using the Agentic-Workflows Agent (Recommended) + +The easiest way to edit your workflows is to use the `/agent agentic-workflows` command in GitHub Copilot Chat: + +```sh wrap +/agent agentic-workflows update add web-fetch tool to my-workflow +``` + +This approach automatically handles both content changes and recompilation, ensuring your workflow is ready to use. + +### Manual Editing: Understanding Prompt vs Frontmatter + +When manually editing workflow files (`.md` files in the `.github/workflows/` directory), it's important to understand the difference between the two main components: ### Workflow Prompt (Markdown Body) @@ -105,7 +117,7 @@ The **workflow prompt** is the main markdown content that describes what you wan - **Location**: The main body of the `.md` file (below the frontmatter) - **Purpose**: Describes the task for the AI agent to execute -- **Editing**: Can be edited directly without recompilation +- **Editing**: Can be edited directly from the GitHub web interface without recompilation - **Example**: ```markdown Triage the issue by analyzing its content, assigning appropriate labels, @@ -113,7 +125,7 @@ The **workflow prompt** is the main markdown content that describes what you wan ``` > [!TIP] -> You can edit the workflow prompt directly through the GitHub web interface. Changes to the prompt take effect immediately in the next workflow run - no compilation needed. +> You can edit the workflow prompt directly through the GitHub web interface in your repository's `.github/workflows/*.md` files. Changes to the prompt take effect immediately in the next workflow run - no compilation needed. ### Frontmatter Configuration @@ -121,7 +133,7 @@ The **frontmatter** is the YAML configuration block at the top of the workflow f - **Location**: Between `---` delimiters at the top of the `.md` file - **Purpose**: Configures how the workflow runs (triggers, tools, permissions, etc.) -- **Editing**: **Requires recompilation** after changes +- **Editing**: **Requires recompilation** after manual changes - **Example**: ```yaml --- @@ -136,11 +148,13 @@ The **frontmatter** is the YAML configuration block at the top of the workflow f ``` > [!WARNING] -> After editing frontmatter configuration, you **must recompile** the workflow to regenerate the `.lock.yml` file: +> After manually editing frontmatter configuration, you **must recompile** the workflow to regenerate the `.lock.yml` file: > ```bash > gh aw compile workflow-name.md > ``` > The `.lock.yml` file is the compiled GitHub Actions workflow that actually runs. Changes to frontmatter won't take effect until you recompile and commit the updated `.lock.yml` file. +> +> **Recommended**: Use the `/agent agentic-workflows` command instead, which handles recompilation automatically. ### Quick Reference