How to Use Slash Commands to Trigger Workflows from Issue Comments in GitHub Agentic Workflows

You can trigger GitHub Actions workflows by typing /command-name in issue comments by defining a slash_command trigger in your workflow's front matter, which the gh-aw compiler expands into a complete GitHub Actions configuration at build time.

GitHub Agentic Workflows (gh-aw) enables repository automation through natural chat-like interactions. By implementing slash commands to trigger workflows from issue comments, teams can execute complex CI/CD pipelines, run diagnostics, or generate reports directly from pull request discussions without leaving the GitHub interface.

How Slash Command Triggers Work

The compilation process transforms a simple /command-name comment into a fully functional GitHub Actions workflow through four distinct phases:

1. Parsing the Shorthand

When the compiler encounters an ultra-short form like on: /my-bot, the function parseSlashCommandShorthand in pkg/workflow/slash_command_parser.go extracts the command name and flags it as a slash command trigger. This parser ensures the command appears as the first word of the comment to prevent accidental triggers.

2. Expanding the Configuration

The schedule_preprocessing.go file transforms the shorthand into a complete event map:

{ "slash_command": "my-bot", "workflow_dispatch": nil }

This expansion allows the workflow to respond to both slash commands and manual triggers simultaneously.

3. Extracting Command Configuration

During compilation, extractCommandConfig in pkg/workflow/frontmatter_extraction_yaml.go processes the front matter to:

• Set up the activation job
• Expose the matched command as needs.activation.outputs.slash_command
• Emit deprecation warnings if the older command: field is used instead of slash_command:

4. Generating GitHub Actions YAML

The final output includes an automatic "eyes" (👀) reaction added to the triggering comment, plus environment variables that expose the command name and sanitized context text for downstream steps.

Writing a Slash Command Workflow

Minimal Object Format

Define the trigger using the structured object syntax:

---
on:
  slash_command:
    name: my-bot               # command name; defaults to the file name if omitted

---

# Your steps go here

The compiler automatically expands this configuration to include workflow_dispatch support.

Shorthand String Format

For concise definitions, use the string shorthand:

---
on:
  slash_command: "my-bot"      # ultra-short form

---

Ultra-Short Form

The most compact syntax places the command directly in the on: field:

---
on: /my-bot                    # parsed by parseSlashCommandShorthand

---

This ultra-short form is transformed by schedule_preprocessing.go into the full object configuration.

Full Example with Custom Reaction

---
on:
  slash_command:
    name: summarize-issue
    reaction: rocket            # overrides the default "eyes" emoji

  workflow_dispatch: {}
permissions:
  issues: write
---

# Summarize the issue when /summarize-issue is typed

- name: Generate summary
  run: |
    echo "Summarizing ${{ needs.activation.outputs.text }}"

This example demonstrates overriding the default reaction and accessing the sanitized comment text through the activation job outputs.

Triggering Workflows from Issue Comments

Posting Commands

Users trigger workflows by posting comments that start with the defined command:

/summarize-issue

The command must appear as the first word of the comment or issue body. This positional requirement prevents accidental triggers when commands appear in the middle of sentences or code blocks.

Accessing Command Data Within Workflows

Once triggered, the workflow exposes two critical outputs through the activation job:

• ${{ needs.activation.outputs.slash_command }} — Contains the exact command name used (e.g., summarize-issue)
• ${{ needs.activation.outputs.text }} — Contains sanitized context combining the issue title and body or the comment body

These outputs enable a single workflow file to handle multiple command aliases by switching on the slash_command value.

Key Configuration Details

Aspect	Implementation Detail
Command Position	Must be the first word of the comment or body, enforced by the parser in slash_command_parser.go
Field Deprecation	The older command: field is accepted but emits a warning via frontmatter_extraction_yaml.go
Trigger Combination	slash_command can coexist with workflow_dispatch, schedule, or label-only events
Default Reaction	Automatically adds an "eyes" (👀) reaction to the triggering comment unless overridden
Output Variables	needs.activation.outputs.slash_command exposes the matched command; needs.activation.outputs.text provides sanitized content

Summary

• Slash commands in gh-aw allow triggering GitHub Actions by typing /command-name in issue comments, with the trigger defined in workflow front matter using the slash_command: field.
• The compiler processes commands through slash_command_parser.go and schedule_preprocessing.go, expanding shorthand syntax into complete GitHub Actions configurations that include automatic comment reactions.
• Commands must appear as the first word of a comment, and the matched command name is available to workflow steps via needs.activation.outputs.slash_command.

Frequently Asked Questions

What is the difference between slash_command: and the older command: field?

The slash_command: field is the current standard for defining issue comment triggers in gh-aw, while command: is deprecated but still functional for backward compatibility. When using the older field, the compiler emits a deprecation warning through frontmatter_extraction_yaml.go. Both fields ultimately configure the same underlying trigger mechanism, but new workflows should exclusively use slash_command: to avoid future breaking changes.

Can I use multiple slash commands in a single workflow file?

Yes, a single workflow can respond to multiple command names by utilizing the needs.activation.outputs.slash_command output variable. After defining multiple potential commands in your repository configuration, your workflow steps can switch on this output value to execute different logic paths. The activation job automatically captures which specific command triggered the workflow, making it available to subsequent jobs through the GitHub Actions needs context.

Why does my slash command only work when it's the first word of the comment?

This positional requirement is a safety feature implemented in parseSlashCommandShorthand within pkg/workflow/slash_command_parser.go. By restricting commands to the first word, the system prevents accidental triggers when users mention commands in the middle of sentences, code blocks, or quoted text. This design ensures that workflows only execute when users intentionally invoke them at the beginning of a comment, reducing false positives and unintended workflow runs.

How do I customize the reaction emoji added to triggering comments?

Override the default "eyes" (👀) reaction by specifying the reaction: key in your slash_command configuration. In the front matter, set reaction: rocket (or any valid GitHub reaction emoji name) alongside your command name. If you omit this field, the compiler automatically generates the default eyes reaction through the workflow generation logic, providing visual feedback to users that their command has been acknowledged and processed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}