diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 83bc9402db4..6cffc5cfdd6 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -2,6 +2,7 @@ import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; import starlightLlmsTxt from 'starlight-llms-txt'; +import starlightLinksValidator from 'starlight-links-validator'; // https://astro.build/config export default defineConfig({ @@ -11,6 +12,10 @@ export default defineConfig({ title: 'GitHub Agentic Workflows', social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/githubnext/gh-aw' }], plugins: [ + starlightLinksValidator({ + errorOnRelativeLinks: false, + errorOnLocalLinks: false, + }), starlightLlmsTxt({ description: 'GitHub Agentic Workflows (gh-aw) is a Go-based GitHub CLI extension that enables writing agentic workflows in natural language using markdown files, and running them as GitHub Actions workflows.', optionalLinks: [ diff --git a/docs/package-lock.json b/docs/package-lock.json index cb04e835871..28eb4ac8f61 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -11,6 +11,7 @@ "@astrojs/starlight": "^0.35.2", "astro": "^5.6.1", "sharp": "^0.34.2", + "starlight-links-validator": "^0.17.2", "starlight-llms-txt": "^0.6.0" } }, @@ -1737,6 +1738,12 @@ "undici-types": "~7.10.0" } }, + "node_modules/@types/picomatch": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/@types/picomatch/-/picomatch-3.0.2.tgz", + "integrity": "sha512-n0i8TD3UDB7paoMMxA3Y65vUncFJXjcUf7lQY7YyKGl6031FNjfsLs6pdLFCy2GNFxItPJG8GvvpbZc2skH7WA==", + "license": "MIT" + }, "node_modules/@types/sax": { "version": "1.2.7", "resolved": "https://registry.npmjs.org/@types/sax/-/sax-1.2.7.tgz", @@ -3388,6 +3395,18 @@ "url": "https://github.com/sponsors/brc-dd" } }, + "node_modules/is-absolute-url": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/is-absolute-url/-/is-absolute-url-4.0.1.tgz", + "integrity": "sha512-/51/TKE88Lmm7Gc4/8btclNXWS+g50wXhYJq8HWIBAGUBnoAdRu1aXeh364t/O7wXDAcTJDP8PNuNKWUDWie+A==", + "license": "MIT", + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/is-alphabetical": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", @@ -5702,6 +5721,30 @@ "url": "https://github.com/sponsors/wooorm" } }, + "node_modules/starlight-links-validator": { + "version": "0.17.2", + "resolved": "https://registry.npmjs.org/starlight-links-validator/-/starlight-links-validator-0.17.2.tgz", + "integrity": "sha512-d2SRWu04HPiUzrzntuv/uzuXnIu4reJwzX1c+7uvcnqOCuzgpv+tmlUC+dp3VYpmfxQy8RX+xcWtfcEkx905VA==", + "license": "MIT", + "dependencies": { + "@types/picomatch": "^3.0.1", + "github-slugger": "^2.0.0", + "hast-util-from-html": "^2.0.3", + "hast-util-has-property": "^3.0.0", + "is-absolute-url": "^4.0.1", + "kleur": "^4.1.5", + "mdast-util-mdx-jsx": "^3.1.3", + "mdast-util-to-string": "^4.0.0", + "picomatch": "^4.0.2", + "unist-util-visit": "^5.0.0" + }, + "engines": { + "node": ">=18.17.1" + }, + "peerDependencies": { + "@astrojs/starlight": ">=0.32.0" + } + }, "node_modules/starlight-llms-txt": { "version": "0.6.0", "resolved": "https://registry.npmjs.org/starlight-llms-txt/-/starlight-llms-txt-0.6.0.tgz", diff --git a/docs/package.json b/docs/package.json index 60fdc58b9dd..f374e4d13db 100644 --- a/docs/package.json +++ b/docs/package.json @@ -7,12 +7,14 @@ "start": "astro dev", "build": "astro build", "preview": "astro preview", - "astro": "astro" + "astro": "astro", + "validate-links": "astro build" }, "dependencies": { "@astrojs/starlight": "^0.35.2", "astro": "^5.6.1", "sharp": "^0.34.2", + "starlight-links-validator": "^0.17.2", "starlight-llms-txt": "^0.6.0" } } diff --git a/docs/src/content/docs/reference/alias-triggers.md b/docs/src/content/docs/reference/alias-triggers.md new file mode 100644 index 00000000000..c8852ef6b38 --- /dev/null +++ b/docs/src/content/docs/reference/alias-triggers.md @@ -0,0 +1,110 @@ +--- +title: Alias Triggers +description: Learn about special @mention triggers and context text functionality for agentic workflows, enabling interactive automation through command-style triggers. +--- + +Alias triggers provide a way to create interactive agentic workflows that respond to special @mention-style commands in GitHub issues and comments. + +## What are Alias Triggers? + +Alias triggers allow you to create workflows that activate when someone mentions a specific command in an issue or comment using the `/command-name` format. This enables interactive, on-demand automation that team members can invoke as needed. + +## Command Syntax + +Alias triggers use the `command:` event type in your workflow frontmatter: + +```yaml +on: + command: + name: my-command # Optional: defaults to filename without .md extension +``` + +When configured, users can trigger the workflow by mentioning `/my-command` in: +- Issue descriptions and comments +- Pull request descriptions and comments +- Review comments + +## Basic Example + +```markdown +--- +on: + command: + name: summarize-issue +permissions: + issues: write +tools: + github: + allowed: [add_issue_comment] +--- + +# Issue Summarizer + +When someone mentions /summarize-issue in an issue or comment, +analyze and provide a helpful summary. + +The current context text is: "${{ needs.task.outputs.text }}" +``` + +## Context Text Access + +All alias-triggered workflows have access to contextual information through `${{ needs.task.outputs.text }}`: + +- **Issues**: `title + "\n\n" + body` +- **Pull Requests**: `title + "\n\n" + body` +- **Issue Comments**: `comment.body` +- **PR Review Comments**: `comment.body` +- **PR Reviews**: `review.body` + +This allows your agentic workflow to understand what it's responding to. + +## Visual Feedback + +You can provide immediate visual feedback when commands are triggered: + +```yaml +on: + command: + name: my-bot +reaction: "eyes" +``` + +This will: +1. Add the specified emoji reaction (👀) to the triggering comment +2. Automatically edit the comment to include a link to the workflow run + +## Security Considerations + +- Only team members with appropriate repository permissions can trigger command workflows +- The workflow compiler automatically adds permission checks +- Commands respect the same security model as other GitHub Actions + +## Common Use Cases + +- **Code Review Assistance**: `/review-pr` to get AI-powered code analysis +- **Issue Triage**: `/triage` to automatically categorize and label issues +- **Documentation Updates**: `/update-docs` to refresh documentation +- **Release Preparation**: `/prepare-release` to automate release checklists +- **Bug Analysis**: `/analyze-bug` to investigate reported issues + +## Combining with Other Triggers + +You can combine command triggers with other events: + +```yaml +on: + command: + name: my-bot + schedule: + - cron: "0 9 * * 1" # Also run weekly + workflow_dispatch: # Allow manual triggering +``` + +**Note**: You cannot combine `command` with `issues`, `issue_comment`, or `pull_request` as they would conflict. + +## Related Documentation + +- **[Command Triggers](command-triggers.md)** - Detailed technical implementation +- **[Frontmatter Options](frontmatter.md)** - Complete configuration reference +- **[Visual Feedback](frontmatter.md#visual-feedback-reaction)** - Available reaction options +- **[Security Notes](security-notes.md)** - Security best practices \ No newline at end of file diff --git a/pkg/workflow/js/push_to_pr_branch.cjs b/pkg/workflow/js/push_to_pr_branch.cjs index 5bdf0805bae..e6aed1cc9c4 100644 --- a/pkg/workflow/js/push_to_pr_branch.cjs +++ b/pkg/workflow/js/push_to_pr_branch.cjs @@ -151,9 +151,9 @@ async function main() { // Compute the target branch name based on target configuration let pullNumber; if (target === "triggering") { - // Use the number of the triggering pull request - pullNumber = context.payload?.pull_request?.number || context.payload?.issue?.number; + pullNumber = + context.payload?.pull_request?.number || context.payload?.issue?.number; // Check if we're in a pull request context when required if (!pullNumber) {