diff --git a/docs/src/content/docs/examples/scheduled.md b/docs/src/content/docs/examples/scheduled.md index 0566f8bfe4..0dd7a5804b 100644 --- a/docs/src/content/docs/examples/scheduled.md +++ b/docs/src/content/docs/examples/scheduled.md @@ -17,6 +17,7 @@ Scheduled workflows run automatically at specified times using cron expressions. ## Patterns in This Section - **[DailyOps](/gh-aw/examples/scheduled/dailyops/)** - Make incremental improvements through small daily changes +- **[Daily Team Status](/gh-aw/examples/scheduled/daily-team-status/)** - Automated daily status reports and team updates - **[Research & Planning](/gh-aw/examples/scheduled/research-planning/)** - Automated research, status reports, and planning ## Example Schedule Triggers diff --git a/docs/src/content/docs/examples/scheduled/daily-team-status.md b/docs/src/content/docs/examples/scheduled/daily-team-status.md new file mode 100644 index 0000000000..ad0927bfe2 --- /dev/null +++ b/docs/src/content/docs/examples/scheduled/daily-team-status.md @@ -0,0 +1,141 @@ +--- +title: Daily Team Status Report +description: Automated daily status reports that gather repository activity and post upbeat team updates as discussions +--- + +This workflow automatically creates daily team status reports every weekday morning, gathering recent repository activity and posting engaging updates to help teams stay connected and informed. + +## Use Case + +- **Automated team updates**: Keep everyone informed without manual status meetings +- **Activity summaries**: Track issues, PRs, discussions, and code changes +- **Team morale**: Positive, encouraging updates that boost productivity +- **Community engagement**: Highlight contributions and suggest improvements + +## Workflow Example + +```aw wrap +--- +timeout-minutes: 10 +strict: true +on: + schedule: + - cron: "0 9 * * 1-5" # 9 AM on weekdays + workflow_dispatch: +permissions: + contents: read + issues: read + pull-requests: read +network: defaults +tools: + github: +safe-outputs: + create-discussion: + expires: 3d + category: announcements + title-prefix: "[team-status] " + close-older-discussions: true +--- + +# Daily Team Status + +Create an upbeat daily status report for the team as a GitHub discussion. + +## What to include + +- Recent repository activity (issues, PRs, discussions, releases, code changes) +- Team productivity suggestions and improvement ideas +- Community engagement highlights +- Project investment and feature recommendations + +## Style + +- Be positive, encouraging, and helpful 🌟 +- Use emojis moderately for engagement +- Keep it concise - adjust length based on actual activity + +## Process + +1. Gather recent activity from the repository +2. Create a new GitHub discussion with your findings and insights +``` + +## Configuration Details + +### Scheduling + +```yaml +on: + schedule: + - cron: "0 9 * * 1-5" # Runs at 9 AM, Monday-Friday + workflow_dispatch: # Also allows manual triggering +``` + +The workflow runs automatically on weekdays at 9 AM UTC. The `workflow_dispatch` trigger allows you to run it manually for testing or on-demand updates. + +### Permissions + +```yaml +permissions: + contents: read + issues: read + pull-requests: read +``` + +Read-only permissions allow the AI to gather repository data without making changes. The `create-discussion` safe-output handles creating the discussion post with appropriate permissions. + +### Tools Configuration + +```yaml +network: defaults +tools: + github: +``` + +Enables GitHub API access through the GitHub MCP server, allowing the AI to query issues, pull requests, discussions, and other repository data. + +### Safe Outputs + +```yaml +safe-outputs: + create-discussion: + expires: 3d # Auto-close after 3 days + category: announcements # Post to announcements category + title-prefix: "[team-status] " # Consistent title formatting + close-older-discussions: true # Clean up old reports +``` + +The `create-discussion` safe-output creates GitHub discussions with: +- **Auto-expiration**: Reports are automatically closed after 3 days +- **Categorization**: Posts appear in the "Announcements" category +- **Title prefix**: Makes reports easy to identify +- **Cleanup**: Automatically closes older status reports to reduce clutter + +## Adding This Workflow + +Install from the agentics collection: + +```bash +gh aw add githubnext/agentics/daily-team-status --create-pull-request +``` + +Or create it manually in `.github/workflows/daily-team-status.md`. + +## Customization Ideas + +1. **Change schedule**: Adjust the cron expression to run at different times +2. **Focus areas**: Modify the prompt to emphasize specific metrics or topics +3. **Style preferences**: Adjust tone, emoji usage, or report format +4. **Different outputs**: Use `create-issue` or `add-comment` instead of discussions +5. **Additional data**: Include security alerts, dependencies, or code quality metrics + +## Prerequisites + +- **GitHub Discussions** must be enabled in your repository +- **Copilot token** configured as `COPILOT_GITHUB_TOKEN` secret +- **Announcements category** exists in Discussions (or modify category in config) + +## Related Examples + +- [DailyOps](/gh-aw/examples/scheduled/dailyops/) - Continuous improvement through small daily changes +- [Research Planning](/gh-aw/examples/scheduled/research-planning/) - Weekly planning workflows diff --git a/docs/src/content/docs/setup/quick-start.md b/docs/src/content/docs/setup/quick-start.md index 0dfa2d7676..43ef396dcb 100644 --- a/docs/src/content/docs/setup/quick-start.md +++ b/docs/src/content/docs/setup/quick-start.md @@ -33,9 +33,9 @@ This guide walks you through setup step-by-step, so you don't need everything up - *Why:* You need permission to add workflows, enable Actions, and configure secrets - **GitHub Actions** enabled - *Why:* Agentic workflows compile to GitHub Actions YAML files that run on GitHub's infrastructure -- **Discussions** enabled (optional for custom workflows) - - *Why:* The example workflow in this guide creates a daily status report as a discussion post - - *Note:* You can disable this requirement by customizing the workflow to use different outputs +- **Discussions** enabled + - *Why:* The Hello World example creates a discussion post to show a visible result + - *How to enable:* Go to your repository Settings → General → Features → Check "Discussions" ::: @@ -112,15 +112,52 @@ Install the [GitHub CLI](https://cli.github.com/), then install the GitHub Agent gh extension install githubnext/gh-aw ``` -### Step 2 — Add a sample workflow +### Step 2 — Create your first workflow -Add a sample from the [agentics](https://github.com/githubnext/agentics) collection. From your repository root run: +Let's create a simple "Hello World" workflow that introduces you to agentic workflows without overwhelming complexity. + +Create a new file `.github/workflows/hello-world.md` in your repository with this content: + +```aw wrap +--- +# Trigger: Run manually from GitHub Actions UI +on: + workflow_dispatch: + +# Permissions: Read repository information +permissions: + contents: read + +# AI Engine: Use GitHub Copilot +engine: copilot + +# Safe Output: Allow creating discussions +safe-outputs: + create-discussion: {} +--- + +# My First Agentic Workflow + +Create a discussion in the "General" category that says "Hello from my first agentic workflow!" + +Include today's date and a fun fact about GitHub Copilot. +``` + +Now compile the workflow to generate the GitHub Actions YAML file: ```bash wrap -gh aw add githubnext/agentics/daily-team-status --create-pull-request +gh aw compile .github/workflows/hello-world.md ``` -This creates a pull request that adds `.github/workflows/daily-team-status.md` and the [compiled](/gh-aw/reference/glossary/#compilation) `.lock.yml` (the generated GitHub Actions workflow file). Review and merge the PR into your repo. +This creates `.github/workflows/hello-world.lock.yml` (the [compiled](/gh-aw/reference/glossary/#compilation) GitHub Actions workflow file). + +Commit both files to your repository: + +```bash wrap +git add .github/workflows/hello-world.md .github/workflows/hello-world.lock.yml +git commit -m "Add my first agentic workflow" +git push +``` ### Step 3 — Add an AI secret @@ -193,12 +230,12 @@ Repository secrets are encrypted and never exposed in workflow logs. Only workfl For more information, see the [GitHub Copilot CLI documentation](https://github.com/github/copilot-cli?tab=readme-ov-file#authenticate-with-a-personal-access-token-pat). -### Step 4 — Trigger a workflow run +### Step 4 — Trigger your workflow -Trigger the workflow immediately in GitHub Actions: +Trigger your workflow manually in GitHub Actions: ```bash wrap -gh aw run daily-team-status +gh aw run hello-world ``` After a few moments, check the status: @@ -207,52 +244,79 @@ After a few moments, check the status: gh aw status ``` -Once complete, a new discussion post will be created in your repository with a daily news! The report will be automatically generated by the AI based on recent activity in your repository. +Once complete, a new discussion post will be created in your repository with a friendly "Hello World" message and today's date! The AI will also include an interesting fact about GitHub Copilot. ## Understanding Your First Workflow -Let's look at what you just added. The daily team status workflow automatically creates a status report every weekday and posts it as a discussion in your repository, and looks like this: +Let's look at what you just created. The workflow has two parts: **configuration** (frontmatter) and **instructions** (markdown body). + +### Configuration (Frontmatter) + +The section between `---` markers configures when and how the workflow runs: ```aw wrap --- +# Trigger: Run manually from GitHub Actions UI on: - schedule: - - cron: "0 9 * * 1-5" workflow_dispatch: + +# Permissions: Read repository information permissions: contents: read - issues: read - pull-requests: read -network: defaults -tools: - github: + +# AI Engine: Use GitHub Copilot +engine: copilot + +# Safe Output: Allow creating discussions safe-outputs: - create-discussion: + create-discussion: {} --- +``` + +**Breaking it down:** -# Daily Team Status +- **`on: workflow_dispatch`** - This workflow runs only when you manually trigger it from the GitHub Actions UI or CLI. No automatic scheduling. -Create an upbeat daily status report for the team as a GitHub discussion. -- Recent repository activity (issues, PRs, discussions, releases, code changes) -- Team productivity suggestions and improvement ideas -- Community engagement highlights -- Project investment and feature recommendations +- **`permissions: contents: read`** - The AI can read your repository content but cannot make any changes directly. This is a key security feature. -... +- **`engine: copilot`** - Uses GitHub Copilot as the AI [agent](/gh-aw/reference/glossary/#agent) that executes your instructions. -1. Gather recent activity from the repository -2. Create a new GitHub discussion with your findings and insights +- **`safe-outputs: create-discussion: {}`** - Pre-approves the AI to request creating a discussion. The actual creation happens in a separate, permission-controlled job for security. The `{}` means use default settings. + +:::tip[What is frontmatter?] +[Frontmatter](/gh-aw/reference/glossary/#frontmatter) is the configuration section at the top of markdown files, written in [YAML](/gh-aw/reference/glossary/#yaml) format. It's enclosed by `---` markers and controls how the workflow behaves. + +Think of it like the settings panel for your workflow - you're not writing instructions yet, just configuring the environment. +::: + +### Instructions (Markdown Body) + +The section below the frontmatter contains your natural language instructions: + +```markdown +# My First Agentic Workflow + +Create a discussion in the "General" category that says "Hello from my first agentic workflow!" + +Include today's date and a fun fact about GitHub Copilot. ``` -This workflow triggers every weekday at 9 AM via cron schedule, has [permissions](/gh-aw/reference/glossary/#permissions) to read repository content and create GitHub discussions, and runs AI instructions in natural language to generate status reports. +This is plain English telling the AI what to do. The AI reads these instructions, executes them within the configured environment, and uses the `create-discussion` safe-output to post the result. + +**Why this works:** -**Understanding the structure:** +1. The AI reads your repository and the instructions +2. It generates content based on your requirements (greeting, date, fun fact) +3. It requests to create a discussion using the safe-output +4. A separate GitHub Actions job creates the discussion with proper permissions -- **[Frontmatter](/gh-aw/reference/glossary/#frontmatter)** (between `---` markers): The configuration section with [YAML](/gh-aw/reference/glossary/#yaml) settings that control when the workflow runs (`on:`), what permissions it has (`permissions:`), what tools it can use (`tools:`), and what outputs it can create (`safe-outputs:`). +### Want to Try Something More Complex? -- **Markdown body** (below frontmatter): Natural language instructions that tell the AI [agent](/gh-aw/reference/glossary/#agent) what tasks to perform. Written in plain English, not code. +Once you're comfortable with this basic workflow, explore more advanced examples: -- **[Safe outputs](/gh-aw/reference/glossary/#safe-outputs)**: Pre-approved actions (like creating discussions, issues, or comments) that the AI can request without needing write permissions during execution. The workflow processes these requests in separate, permission-controlled jobs for security. +- **[Daily Team Status](/gh-aw/examples/scheduled/daily-team-status/)** - Automated status reports with cron scheduling, GitHub API integration, and richer safe-output configuration +- **[Manual Research Workflows](/gh-aw/examples/manual/)** - On-demand workflows with custom inputs +- **[Comment-Triggered Workflows](/gh-aw/examples/comment-triggered/)** - Workflows that respond to issue and PR comments ## Customize Your Workflow @@ -273,7 +337,7 @@ Then, run the following to create and edit your workflow: copilot > /agent > select create-agentic-workflow -> edit @.github/workflows/daily-team-status.md +> edit @.github/workflows/hello-world.md ``` ## What's next? diff --git a/docs/tests/quick-start-hello-world.spec.ts b/docs/tests/quick-start-hello-world.spec.ts new file mode 100644 index 0000000000..4f891454bf --- /dev/null +++ b/docs/tests/quick-start-hello-world.spec.ts @@ -0,0 +1,68 @@ +import { test, expect } from '@playwright/test'; + +test.describe('Quick Start Hello World Example', () => { + test.beforeEach(async ({ page }) => { + await page.goto('/gh-aw/setup/quick-start/'); + await page.waitForLoadState('networkidle'); + }); + + test('should display Hello World workflow example in Step 2', async ({ page }) => { + // Verify the page contains the Hello World workflow title + const helloWorldText = page.locator('text=My First Agentic Workflow').first(); + await expect(helloWorldText).toBeVisible(); + + // Verify it's a simple workflow_dispatch trigger (not cron) + const workflowDispatch = page.locator('text=workflow_dispatch').first(); + await expect(workflowDispatch).toBeVisible(); + + // Verify the first workflow example mentions Hello World + const helloText = page.locator('text=Hello from my first agentic workflow').first(); + await expect(helloText).toBeVisible(); + }); + + test('should have minimal configuration in Hello World example', async ({ page }) => { + // Verify the example uses simple create-discussion safe-output + const createDiscussion = page.locator('text=create-discussion').first(); + await expect(createDiscussion).toBeVisible(); + + // Verify it has read-only permissions + const readPermissions = page.locator('text=contents: read').first(); + await expect(readPermissions).toBeVisible(); + }); + + test('should have inline comments explaining configuration', async ({ page }) => { + // Verify the example includes explanatory comments + await expect(page.locator('text=Trigger: Run manually from GitHub Actions UI').first()).toBeVisible(); + await expect(page.locator('text=Permissions: Read repository information').first()).toBeVisible(); + await expect(page.locator('text=AI Engine: Use GitHub Copilot').first()).toBeVisible(); + await expect(page.locator('text=Safe Output: Allow creating discussions').first()).toBeVisible(); + }); + + test('should reference daily-team-status as a more complex example', async ({ page }) => { + // Verify the daily-team-status is referenced as an advanced example + const advancedLink = page.locator('a:has-text("Daily Team Status")'); + await expect(advancedLink).toBeVisible(); + + // Verify it links to the examples section + const href = await advancedLink.getAttribute('href'); + expect(href).toContain('/examples/scheduled/daily-team-status'); + }); + + test('should have Step 4 reference hello-world workflow', async ({ page }) => { + // Verify Step 4 uses the hello-world workflow name + const step4Section = page.locator('h3:has-text("Step 4")'); + await expect(step4Section).toBeVisible(); + + // Verify the run command uses hello-world + await expect(page.locator('text=gh aw run hello-world')).toBeVisible(); + }); + + test('should explain workflow structure with configuration and instructions sections', async ({ page }) => { + // Verify the Understanding section explains frontmatter and markdown body + await expect(page.locator('h3:has-text("Configuration (Frontmatter)")')).toBeVisible(); + await expect(page.locator('h3:has-text("Instructions (Markdown Body)")')).toBeVisible(); + + // Verify it explains what frontmatter is + await expect(page.locator('text=What is frontmatter?')).toBeVisible(); + }); +});