From 1d01b7e5cf24fe7751a248e3ab20c5adcec3443e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 12:54:39 +0000 Subject: [PATCH 1/7] Initial plan From d2109f3d59401a53c56ed9669dc8fe051bb321ec Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:01:48 +0000 Subject: [PATCH 2/7] Optimize install.md for smooth first-time user experience Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- install.md | 274 ++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 240 insertions(+), 34 deletions(-) diff --git a/install.md b/install.md index a966855c716..cb3cbad5966 100644 --- a/install.md +++ b/install.md @@ -1,79 +1,285 @@ # GitHub Agentic Workflows: Interactive Setup Wizard -Use this guided, prompt-driven wizard to install gh-aw, initialize your repo, configure secrets, and create or add your first agentic workflow. Copy the commands and respond to the prompts as you go. +You are an AI assistant helping the user set up **GitHub Agentic Workflows (gh-aw)** in their repository. -## Role +## What is GitHub Agentic Workflows? -You are an AI assistant helping the user set up GitHub Agentic Workflows (gh-aw) in their repository. Assume that the user has a basic understanding of GitHub and the command line, but has never worked with Agentic Workflows or GitHub Actions. +GitHub Agentic Workflows lets you write AI-powered automation in natural language markdown files that run as GitHub Actions. Instead of complex YAML workflows, you write instructions in plain English, and AI agents (like GitHub Copilot) execute them. -## 1) Verify Installation +**Example workflow:** +```markdown +--- +on: + issues: + types: [opened] +permissions: read-all +safe-outputs: + add-comment: +--- + +# Issue Clarifier + +Analyze the current issue and ask for additional details if the issue is unclear. +``` + +This markdown compiles to a GitHub Actions workflow that automatically responds to new issues. + +## Setup Overview + +This wizard will guide you through: +1. ✅ Installing gh-aw extension +2. 🔧 Initializing your repository +3. 🔑 Configuring AI engine secrets +4. 🚀 Adding your first workflow +5. ✨ Running and testing it + +**Assumptions:** You have basic GitHub and command line knowledge, but have never used Agentic Workflows before. + +Let's get started! 🎯 + +## Step 1: Install gh-aw Extension + +First, let's check if gh-aw is already installed: ```bash -gh aw version || echo "gh-aw not found" +gh aw version ``` -- If you see a version: continue. -- If not found: choose one install path and rerun `gh aw version`. +**✅ Success if you see:** A version number like `gh-aw version 1.x.x` +**❌ Not installed if you see:** `unknown command "aw"` or `gh-aw not found` + +### Install gh-aw +**Recommended method (GitHub CLI extension):** ```bash -# Install as GitHub CLI extension (recommended) gh extension install githubnext/gh-aw +``` + +Then verify the installation: +```bash +gh aw version +``` -# Or: standalone installer (Codespaces/fallback) +**Alternative method (if extension install fails in Codespaces):** +```bash curl -sL https://raw.githubusercontent.com/githubnext/gh-aw/main/install-gh-aw.sh | bash ``` -## 2) Initialize Your Repository +**✨ Checkpoint:** Before proceeding, confirm you can run `gh aw version` successfully. + +## Step 2: Initialize Your Repository + +Navigate to your repository directory and run: ```bash gh aw init ``` -What this does: +**What this does:** +- ✅ Configures `.gitattributes` to mark `.lock.yml` files as generated (these are compiled workflows) +- ✅ Creates `.github/aw/github-agentic-workflows.md` with comprehensive gh-aw documentation +- ✅ Creates `.github/agents/*.agent.md` files with specialized AI assistants for workflow creation and debugging +- ✅ Prepares your repository structure for agentic workflows + +**Expected output:** +``` +✓ .gitattributes configured +✓ Created .github/aw/github-agentic-workflows.md +✓ Created .github/agents/create-agentic-workflow.agent.md +✓ Created .github/agents/debug-agentic-workflow.agent.md +``` + +**✨ Checkpoint:** Verify that `.github/aw/` and `.github/agents/` directories were created with the files listed above. -- Configures `.gitattributes` to mark `.lock.yml` as generated -- Adds Copilot custom instructions and agents -- Prepares repo structure for agentic workflows +## Step 3: Configure AI Engine (GitHub Copilot) -## 3) AI Engine (Default: Copilot) +Agentic workflows use AI agents to execute your instructions. The default engine is **GitHub Copilot CLI**. -This wizard assumes GitHub Copilot as the default engine. No need to choose an agent; workflows will use `engine: copilot` unless you explicitly change them later. +### Prerequisites +- ✅ Active GitHub Copilot subscription (individual or organization) +- ✅ Admin or write access to your repository -## 4) Configure Secrets (Copilot) +### Create a Personal Access Token (PAT) + +**Important:** The token needs the **"Copilot Requests"** permission to communicate with GitHub Copilot's AI agent. + +1. **Create a fine-grained token:** Visit + +2. **Configure the token:** + - **Resource owner:** Select your personal user account (not an organization) + - **Repository access:** Select "Public repositories" (required for Copilot Requests permission to appear) + - **Permissions:** Click "Add permissions" and select **"Copilot Requests"** + +3. **Generate and copy the token** (you'll use it in the next step) + +**⚠️ Troubleshooting:** Can't find "Copilot Requests" permission? +- Ensure you have an [active Copilot subscription](https://github.com/settings/copilot) +- Verify you selected your **user account** (not an organization) as Resource owner +- Confirm you're creating a **fine-grained token** (not a classic token) +- Check that **"Public repositories"** is selected under Repository access + +### Add the Secret to Your Repository + +**⚠️ Security Warning:** Never paste your token in this chat or commit it to your repository. Use your terminal directly for this step. + +In your terminal, run: ```bash -# Create a GitHub Personal Access Token (Classic) with an active Copilot subscription -# Then set it as a secret for Actions -gh secret set COPILOT_GITHUB_TOKEN -a actions --body "YOUR_GITHUB_PAT" +gh secret set COPILOT_GITHUB_TOKEN -a actions ``` -Reference: +When prompted, paste your token and press Enter. -IMPORTANT: TELL USER TO NOT PASTE SECRET HERE, USE ANOTHER TERMINAL. +**Expected output:** +``` +✓ Set Actions secret COPILOT_GITHUB_TOKEN for / +``` -Activate `.github/aw/github-agentic-workflows.md` to learn more about the agentic workflow format. +**✨ Checkpoint:** Verify the secret was added: +```bash +gh secret list +``` + +You should see `COPILOT_GITHUB_TOKEN` in the list. + +**📚 Reference:** [GitHub Copilot CLI documentation](https://github.com/github/copilot-cli?tab=readme-ov-file#authenticate-with-a-personal-access-token-pat) -### Ask the user to add an existing workflow or create a new one +## Step 4: Add Your First Workflow -To add, go to (5) or to create, go to (6) +Now you're ready to add a workflow! You have two options: -## 5) Add a Workflow from the Agentics Catalog +### Option A: Add a Workflow from the Agentics Catalog (Recommended for First-Time Users) -Browse and add proven workflows interactively. +The [agentics catalog](https://github.com/githubnext/agentics) contains proven, ready-to-use workflows. +**Browse available workflows:** ```bash -# List catalog items gh aw add githubnext/agentics +``` + +This shows an interactive list of available workflows. You can also visit the catalog directly at: + +**Add a specific workflow:** + +For example, to add a daily team status workflow: +```bash +gh aw add githubnext/agentics/daily-team-status --create-pull-request +``` + +This creates a pull request that adds: +- `.github/workflows/daily-team-status.md` (the human-readable workflow) +- `.github/workflows/daily-team-status.lock.yml` (the compiled GitHub Actions workflow) -# Add a specific workflow or all -gh aw add githubnext/agentics/ +**Review and merge the PR** to add the workflow to your repository. + +**Other useful commands:** +```bash +# Add all workflows from the catalog gh aw add githubnext/agentics/* -# Optional: pin version or open a PR automatically +# Add a specific version gh aw add githubnext/agentics/ci-doctor@v1.0.0 -gh aw add githubnext/agentics/ci-doctor --create-pull-request ``` -## 6) Create a New Workflow (Agentic Experience) +**✨ Checkpoint:** After merging the PR, verify the workflow files exist: +```bash +ls .github/workflows/ +``` + +You should see both the `.md` and `.lock.yml` files. + +### Option B: Create a New Workflow with AI Assistance + +If you want to create a custom workflow, you can use the GitHub Copilot CLI with the workflow creation agent: + +**Prerequisites:** +```bash +# Install GitHub Copilot CLI if you haven't already +npm install -g @github/copilot-cli +``` + +**Create a workflow interactively:** +```bash +copilot +``` + +Then in the Copilot chat: +``` +/create-agentic-workflow +``` + +Follow the interactive prompts to design your workflow. The agent will help you: +- Choose the right trigger (issues, PRs, schedule, etc.) +- Configure permissions and tools +- Write the workflow instructions +- Compile and test the workflow + +**Alternative:** You can also manually create a workflow file at `.github/workflows/my-workflow.md` and then compile it: +```bash +gh aw compile my-workflow +``` + +## Step 5: Test Your Workflow + +Once you've added a workflow, test it to ensure everything works: + +### Trigger the workflow manually: +```bash +gh aw run +``` + +For example: +```bash +gh aw run daily-team-status +``` + +### Check the workflow status: +```bash +gh aw status +``` + +### View detailed logs: +```bash +gh aw logs +``` + +**✅ Success:** Your workflow should complete and perform its intended action (create an issue comment, discussion post, etc.) + +**❌ Troubleshooting:** If the workflow fails: + +1. **Check the logs:** + ```bash + gh aw logs + ``` + +2. **Common issues:** + - **Authentication error:** Verify your `COPILOT_GITHUB_TOKEN` secret is set correctly + - **Permission denied:** Check that your workflow has the necessary permissions in the frontmatter + - **Compilation error:** Run `gh aw compile --strict` to validate + +3. **Get AI help debugging:** + ```bash + copilot + ``` + Then: `/debug-agentic-workflow` and describe the issue + +## Next Steps + +🎉 **Congratulations!** You've successfully set up GitHub Agentic Workflows. + +**Learn more:** +- 📖 Read `.github/aw/github-agentic-workflows.md` in your repository for comprehensive documentation +- 🔍 Explore the [agentics catalog](https://github.com/githubnext/agentics) for more workflow examples +- 📚 Visit the [official documentation](https://githubnext.github.io/gh-aw/) for guides and references +- 💬 Join the [GitHub Next Discord](https://gh.io/next-discord) #continuous-ai channel for support + +**Customize your workflows:** +- Edit the `.md` files in `.github/workflows/` +- Recompile after changes: `gh aw compile ` +- Test your changes: `gh aw run ` -activate `.github/agents/create-agentic-workflow.agent.md` and follow the guided prompts to create a new workflow. +**Security reminders:** +- ⚠️ Always use `permissions: read-all` by default +- ⚠️ Use `safe-outputs` instead of write permissions when possible +- ⚠️ Review all AI-generated outputs before they're published +- ⚠️ Never commit secrets to your repository From 3b7bc690ff735f11a79f6959649e0aefc55841eb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:08:14 +0000 Subject: [PATCH 3/7] Fix Copilot CLI references and clarify slash command usage Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- install.md | 33 +++++++++++++++++++++------------ 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/install.md b/install.md index cb3cbad5966..e7465dbba7c 100644 --- a/install.md +++ b/install.md @@ -142,7 +142,7 @@ gh secret list You should see `COPILOT_GITHUB_TOKEN` in the list. -**📚 Reference:** [GitHub Copilot CLI documentation](https://github.com/github/copilot-cli?tab=readme-ov-file#authenticate-with-a-personal-access-token-pat) +**📚 Reference:** [GitHub Copilot CLI documentation](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli) ## Step 4: Add Your First Workflow @@ -190,25 +190,32 @@ You should see both the `.md` and `.lock.yml` files. ### Option B: Create a New Workflow with AI Assistance -If you want to create a custom workflow, you can use the GitHub Copilot CLI with the workflow creation agent: +If you want to create a custom workflow, you can use GitHub Copilot Chat (in VS Code, GitHub.com, or Copilot CLI) with the workflow creation agent. -**Prerequisites:** +**Using GitHub Copilot Chat (VS Code or GitHub.com):** + +After running `gh aw init`, the `/create-agentic-workflow` slash command becomes available in GitHub Copilot Chat. Simply type: + +``` +/create-agentic-workflow +``` + +**Using GitHub Copilot CLI (terminal-based):** + +First, install GitHub Copilot CLI if you haven't already: ```bash -# Install GitHub Copilot CLI if you haven't already -npm install -g @github/copilot-cli +# Prerequisites: Node.js v22+ and npm v10+ +npm install -g @github/copilot ``` -**Create a workflow interactively:** +Then launch the interactive CLI and use the agent: ```bash copilot ``` -Then in the Copilot chat: -``` -/create-agentic-workflow -``` +In the Copilot CLI session, you can use the `/create-agentic-workflow` command or simply describe what you want to automate in natural language. -Follow the interactive prompts to design your workflow. The agent will help you: +The agent will help you: - Choose the right trigger (issues, PRs, schedule, etc.) - Configure permissions and tools - Write the workflow instructions @@ -258,10 +265,12 @@ gh aw logs - **Compilation error:** Run `gh aw compile --strict` to validate 3. **Get AI help debugging:** + + Use GitHub Copilot Chat (VS Code, GitHub.com) or Copilot CLI: ```bash copilot ``` - Then: `/debug-agentic-workflow` and describe the issue + Then use the `/debug-agentic-workflow` command and describe the issue. ## Next Steps From 46540e368066164947ea19b35adf06387c2c6f5b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:10:16 +0000 Subject: [PATCH 4/7] Clarify public repositories requirement for PAT setup Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- install.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/install.md b/install.md index e7465dbba7c..de424b2f694 100644 --- a/install.md +++ b/install.md @@ -107,7 +107,10 @@ Agentic workflows use AI agents to execute your instructions. The default engine 2. **Configure the token:** - **Resource owner:** Select your personal user account (not an organization) - - **Repository access:** Select "Public repositories" (required for Copilot Requests permission to appear) + - **Repository access:** Select "Public repositories" (required for Copilot Requests permission to appear in the UI) + + *Note: Once created, the token will work with both public and private repositories where you set it as a secret.* + - **Permissions:** Click "Add permissions" and select **"Copilot Requests"** 3. **Generate and copy the token** (you'll use it in the next step) From 566494ce4a2673342db940e26a93cb2e7b2597ac Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:13:15 +0000 Subject: [PATCH 5/7] Final clarifications for PAT setup instructions Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- install.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/install.md b/install.md index de424b2f694..d8b589f27c9 100644 --- a/install.md +++ b/install.md @@ -103,15 +103,17 @@ Agentic workflows use AI agents to execute your instructions. The default engine **Important:** The token needs the **"Copilot Requests"** permission to communicate with GitHub Copilot's AI agent. -1. **Create a fine-grained token:** Visit +1. **Create a fine-grained personal access token:** Visit + + *Note: You must create a "fine-grained" token (not a "classic" token) as the Copilot Requests permission is only available for fine-grained tokens.* 2. **Configure the token:** - **Resource owner:** Select your personal user account (not an organization) - - **Repository access:** Select "Public repositories" (required for Copilot Requests permission to appear in the UI) + - **Repository access:** Select "Public repositories" - *Note: Once created, the token will work with both public and private repositories where you set it as a secret.* + *Note: This setting is required for the "Copilot Requests" permission option to appear in the permissions list during token creation. Once the token is created with Copilot Requests permission, you can use it as a secret in any repository (public or private) where you have access.* - - **Permissions:** Click "Add permissions" and select **"Copilot Requests"** + - **Permissions:** Scroll down and click "Account permissions", then select **"Copilot Requests"** from the dropdown and set it to "Read-only" 3. **Generate and copy the token** (you'll use it in the next step) From fb1b18d79557ea17538a9eb68d0cc3b392cc2005 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:23:13 +0000 Subject: [PATCH 6/7] Simplify agent activation instructions per feedback Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- install.md | 41 +++++++++++------------------------------ 1 file changed, 11 insertions(+), 30 deletions(-) diff --git a/install.md b/install.md index d8b589f27c9..477e05a2afa 100644 --- a/install.md +++ b/install.md @@ -195,36 +195,17 @@ You should see both the `.md` and `.lock.yml` files. ### Option B: Create a New Workflow with AI Assistance -If you want to create a custom workflow, you can use GitHub Copilot Chat (in VS Code, GitHub.com, or Copilot CLI) with the workflow creation agent. - -**Using GitHub Copilot Chat (VS Code or GitHub.com):** - -After running `gh aw init`, the `/create-agentic-workflow` slash command becomes available in GitHub Copilot Chat. Simply type: +If you want to create a custom workflow, use the workflow creation agent: ``` -/create-agentic-workflow +activate .github/agents/create-agentic-workflow.agent.md ``` -**Using GitHub Copilot CLI (terminal-based):** - -First, install GitHub Copilot CLI if you haven't already: -```bash -# Prerequisites: Node.js v22+ and npm v10+ -npm install -g @github/copilot -``` - -Then launch the interactive CLI and use the agent: -```bash -copilot -``` - -In the Copilot CLI session, you can use the `/create-agentic-workflow` command or simply describe what you want to automate in natural language. - -The agent will help you: -- Choose the right trigger (issues, PRs, schedule, etc.) -- Configure permissions and tools -- Write the workflow instructions -- Compile and test the workflow +This will load the interactive workflow designer agent that will guide you through: +- Choosing the right trigger (issues, PRs, schedule, etc.) +- Configuring permissions and tools +- Writing the workflow instructions +- Compiling and testing the workflow **Alternative:** You can also manually create a workflow file at `.github/workflows/my-workflow.md` and then compile it: ```bash @@ -271,11 +252,11 @@ gh aw logs 3. **Get AI help debugging:** - Use GitHub Copilot Chat (VS Code, GitHub.com) or Copilot CLI: - ```bash - copilot ``` - Then use the `/debug-agentic-workflow` command and describe the issue. + activate .github/agents/debug-agentic-workflow.agent.md + ``` + + Then describe the issue you're experiencing with your workflow. ## Next Steps From 39e42d996cbe58d2e6e26a765609ea74e90b3e7a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 4 Dec 2025 13:30:53 +0000 Subject: [PATCH 7/7] Add interactive session guidelines for AI agent Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- install.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/install.md b/install.md index 477e05a2afa..b3c7a9d788d 100644 --- a/install.md +++ b/install.md @@ -2,6 +2,20 @@ You are an AI assistant helping the user set up **GitHub Agentic Workflows (gh-aw)** in their repository. +## How to Conduct This Interactive Session + +This is an **interactive agentic setup session**. You should be proactive and conversational: + +- **Ask questions** to understand the user's context (e.g., "Which repository are you setting up?", "Do you already have a Copilot subscription?") +- **Give progress updates** after each step (e.g., "Great! I can see gh-aw is installed. Let's move to initializing your repository.") +- **Explain what's happening** before running commands (e.g., "I'm going to check if gh-aw is installed on your system by running `gh aw version`") +- **Explain why** steps are necessary (e.g., "We need to create a Personal Access Token so your workflows can authenticate with GitHub Copilot's AI agent") +- **Narrate tool usage** when you run commands (e.g., "Let me run `gh aw init` to set up your repository structure...") +- **Check for understanding** and offer help (e.g., "Did that work? Let me know if you see any errors.") +- **Adapt to user responses** - if they already have something set up, skip ahead; if they're stuck, provide more detail + +Your goal is to guide the user smoothly through setup, not just execute a script. Be helpful, clear, and responsive to their needs. + ## What is GitHub Agentic Workflows? GitHub Agentic Workflows lets you write AI-powered automation in natural language markdown files that run as GitHub Actions. Instead of complex YAML workflows, you write instructions in plain English, and AI agents (like GitHub Copilot) execute them.