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

> Learn to trigger GitHub Actions workflows from issue comments using slash commands. Define triggers in front matter to automate tasks effortlessly.

- Repository: [GitHub/gh-aw](https://github.com/github/gh-aw)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/schedule_preprocessing.go) file transforms the shorthand into a complete event map:

```yaml
{ "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`](https://github.com/github/gh-aw/blob/main/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:

```yaml
---
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:

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

---

```

### Ultra-Short Form

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

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

---

```

This ultra-short form is transformed by [`schedule_preprocessing.go`](https://github.com/github/gh-aw/blob/main/schedule_preprocessing.go) into the full object configuration.

### Full Example with Custom Reaction

```yaml
---
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`](https://github.com/github/gh-aw/blob/main/slash_command_parser.go) |
| **Field Deprecation** | The older `command:` field is accepted but emits a warning via [`frontmatter_extraction_yaml.go`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/slash_command_parser.go) and [`schedule_preprocessing.go`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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`](https://github.com/github/gh-aw/blob/main/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.