github/command Action

The github/command Action automates the lifecycle of an IssueOps command. When a workflow step using this Action runs, it performs the following:

1. Detection: Scans the comment body for the specified command phrase (e.g., .ping).
2. Reaction: Automatically reacts to the comment to provide immediate feedback that the command is being processed.
3. Authorization: Verifies if the user who commented has the required permissions and is in the allowlist if configured.
4. Validation: Checks CI status and PR reviews (if running in a pull_request context).
5. Output: Sets the continue output variable. If the command is valid and authorized, steps.<id>.outputs.continue is set to 'true'.

When using github/command, the Action provides two primary outputs for flow control:

1. triggered: A string ("true" or "false") indicating if the specific command string was found in the comment.
2. continue: A string ("true" or empty) that acts as the final gate.

Crucial: You should use the continue output to determine if your subsequent workflow steps should run. Even if triggered is true, the workflow might not proceed if permissions, allowlists, or other constraints (like skip_ci or skip_reviews) are not met. Always use a conditional check on ${{ steps.command.outputs.continue == 'true' }} before executing custom logic.

The command Action allows you to pass unstructured parameters to your command by using a separator. By default, the separator is |. Any text following this separator in the command string is captured and saved as a GitHub Actions output named params.

You can use this to pass configuration values (like LOG_LEVEL=debug) or lists of identifiers (like server1 server2) to subsequent workflow steps. It is the responsibility of the user to parse the params string in later steps.

.restart | LOG_LEVEL=debug CPU_CORES=4

To get started with github/command, use it within a GitHub Actions workflow triggered by issue_comment events. This allows you to execute custom logic by commenting on Issues or Pull Requests.

Basic Usage

Use the default configuration to detect a specific command phrase:

- name: command
  id: command
  uses: github/command@vX.X.X
  with:
    command: .lint

Advanced Usage

Customize the command syntax, reaction type, allowed contexts (e.g., pull_request, issue), required permissions, and user allowlists:

- name: command
  id: command
  uses: github/command@vX.X.X
  with:
    command: .restart
    reaction: "eyes"
    allowed_contexts: "pull_request,issue"
    permissions: "write,admin"
    allowlist: monalisa

The text captured after the param_separator is made available via the params output. You can access this in subsequent steps using the standard GitHub Actions syntax: ${{ steps.<step_id>.outputs.params }}.

- name: command
  id: command
  uses: github/command@vX.X.X
  with:
    command: .restart
    param_separator: "|"

- name: example
  if: steps.command.outputs.continue == 'true'
  run: |
    echo "params: ${{ steps.command.outputs.params }}"

The github/command Action allows you to implement IssueOps by triggering workflows based on specific comment strings (e.g., .lint). You can control which users can trigger commands using allowlist and define the required GitHub permissions via permissions.

To allow commands to be invoked from both Pull Requests and Issues, set allowed_contexts to "pull_request,issue". By default, it only allows pull_request.

Security Note: If you use GitHub org teams in your allowlist, you must provide a GitHub Personal Access Token (PAT) with read:org scopes via the allowlist_pat input so the Action can verify team membership.

- uses: github/command@vX.X.X
  id: command
  with:
    command: ".lint"
    allowlist: monalisa,octocat,octo-awesome-org/octo-awesome-team
    allowlist_pat: ${{ secrets.ALLOWLIST_PAT }}

The github/command Action is used to implement IssueOps by reacting to specific commands within issue or pull request comments. To use it, you must provide the following inputs in your workflow file:

Required Inputs

• command: The specific command string to look for in the comment body.
• github_token: A GitHub token with permissions to read comments and add reactions.

Optional Inputs

• param_separator: A string used to separate parameters within the command.
• reaction: The emoji reaction to add to the triggering comment.
• allow_forks: Boolean. Whether to allow commands from fork repositories.
• skip_ci: Boolean. Whether to skip CI checks.
• allow_drafts: Boolean. Whether to allow commands on draft pull requests.
• skip_reviews: Boolean. Whether to skip review checks.
• fork_review_bypass: Boolean. Whether to bypass review requirements for forks.

The following inputs are available for the github/command Action: