command

IssueOps commands in GitHub Actions!

Like ChatOps but for GitHub Issues and Pull Requests 🤩

This project is based off the github/branch-deploy Action. There are many similarities between the two, but there is a key difference. The github/branch-deploy Action is designed specifically for deployments via IssueOps where this project (command) can be used for any IssueOps command. This Action allows you to tailor your IssueOps command exactly how you want.

This Action does the heavy lifting for you to enabled customized IssueOps commands:

• 🔍 Detects when IssueOps commands are used on a pull request or an issue
• ✏️ Configurable - Choose your command syntax, optional parameters, who can run the commands, what GitHub permissions are required, and much more
• ✔️ Respects your branch protection settings configured for the repo - if commands are run on pull requests
• 🗨️ Reacts to your IssueOps commands
• 🚀 Can be enabled with simple configuration
• 🧶 This Action can be tied into your existing workflows

Turbo Quickstart ⚡

A quick section to get you started with this Action

Usage 📝

Basic usage assuming all defaults:

- name: command
  id: command
  uses: github/command@vX.X.X
  with:
    command: .lint # can be anything you want (example)

Advanced usage with some custom configuration:

- name: command
  id: command
  uses: github/command@vX.X.X
  with:
    command: .restart # can be anything you want (example)
    reaction: "eyes"
    allowed_contexts: "pull_request,issue"
    permissions: "write,admin"
    allowlist: monalisa

For configuration details, see the inputs section below

Example 📚

Check out a super simple workflow example using this Action to quickly get up and running with github/command:

name: "command demo"

# the workflow to execute on is comments that are newly created
on:
  issue_comment:
    types: [created]

# permissions needed for reacting to IssueOps commands on issues and PRs
permissions:
  pull-requests: write
  issues: write
  checks: read
  contents: read # useful if your workflows call actions/checkout@vX.X.X

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      # execute IssueOps command logic, hooray!
      # this will be used to "gate" all future steps below
      - uses: github/command@vX.X.X
        id: command
        with:
          command: ".ping"
          allowed_contexts: issue,pull_request # run on issues AND pull requests

      # run your custom logic for your project here - example seen below

      # conditionally run some logic here
      - name: ping
        if: ${{ steps.command.outputs.continue == 'true' }}
        run: echo "I am going to ping some cool website now!"

Keep reading to learn more about this Action! Even further details about how this Action works can be found below as well

About 💡

Before we get into details, let's first define a few key terms below:

• IssueOps - Its like ChatOps but instead of using a chat bot, commands are invoked by commenting on a pull request (PRs are issues under the hood) - Example: commenting .restart on a pull request
• PR - Short for pull request

IssueOps 🗨️

The best way to define IssueOps is to compare it to something similar, ChatOps. You may be familiar with the concept ChatOps already but in case you aren't here is a quick definition below:

ChatOps is the process of interacting with a chat bot to execute commands directly in a chat platform. For example, with ChatOps you might do something like .ping example.org to check the status of a website

IssueOps adopts the same mindset but through a different medium. Rather than using a chat service to invoke the commands we use comments on a GitHub Issue or Pull Request. GitHub Actions is the runtime which executes our desired logic

How does it work? 📚

This section will go into detail about how this Action works and hopefully inspire you on ways you can leverage it in your own projects

Let's walk through a GitHub Action workflow using this Action line by line:

# The name of the workflow, it can be anything you wish
name: "IssueOps github/command demo"

# The workflow to execute on is comments that are newly created
on:
  issue_comment:
    types: [created]

It is important to note that the workflow we want to run IssueOps on is issue_comment and created. This means we will not run under any other contexts for this workflow. You can edit this as you wish but it does change how this model ultimately works. For example, issue_comment workflows only use files found on main to run. If you do something like on: pull_request you could open yourself up to issues as a user could alter a file in a PR and exfil your secrets for example. Only using issue_comment is the suggested workflow type. It should also be noted that comments on pull requests, and issues will trigger the issue_comment workflow event.

# permissions definitions
permissions:
  pull-requests: write # required for adding reactions to command comments on PRs
  issues: write # required for adding reactions to command comments on issues
  checks: read # required for checking if the CI checks have passed on a pull request (if using this Action in the context of PR comments)

These are the minimum permissions you need to run this Action (this assumes you are running this Action on pull requests and issues)

jobs:
  demo:
    runs-on: ubuntu-latest
    steps:
      # Checkout your projects repository
      - uses: actions/checkout@v4

Sets up your demo job, uses an ubuntu runner, and checks out your repo - Just some standard setup for a general Action. We also add an if: statement here to only run this workflow on pull request comments to make it a little more specific (if necessary)

Note: The Action will check the context for us anyways but this can save us a bit of CI time by using the if: condition

      # Execute IssueOps command logic, hooray!
      - uses: github/command@vX.X.X
        id: command
        with:
          command: ".ping"

Note: It is important to set an id: for this job so we can reference its outputs in subsequent steps

The core of this Action takes place here. This block of code will trigger the github/command action to run. It will do the following:

1. Check the comment which invoked the workflow for the command: phrase (.ping) defined here
2. If the command trigger phrase is found, it will proceed
3. It will start by reacting to your message to let you know it is running
4. The Action will check to ensure the user that invoked the operation has the correct permissions to run the command, collect any parameters used in the command, check CI / reviews (if run on a PR), etc
5. Outputs will be exported by this job for later reference in other jobs as well

      # conditionally run further steps if the command Action was successful
      - name: ping
        if: ${{ steps.command.outputs.continue == 'true' }}
        run: echo "Do your custom logic here to ping your site!"

As seen above, we have a single example step. Perhaps you would actually use a real utility to ping a website, but for this example, we just echo out some text. This step is conditionally gated by the continue variable:

• steps.command.outputs.continue == 'true' - The continue variable is only set to true when a workflow should continue - This is set by logic in the github/command Action

Example: You comment .ping on a pull request. A workflow is kicked off and the github/command Action begins to check the comment body of the message you just typed on the pull request. If you have the correct permissions to execute the IssueOps command, the action outputs the continue variable to true. This will allow the "ping" step seen above to run.

Inputs 📥

| Input | Required? | Default | Description | | ----- | --------- | ------- | ----------- | | command | true | - | The string to look for in comments as an IssueOps trigger/command. Example: ".lint" - You must provide a value for this option | | github_token | true | ${{ github.token }} | The GitHub token used to create an authenticated client - Provided for you by default! | | status | true | ${{ job.status }} | The status of the GitHub Actions - For use in the post run workflow - Provided for you by default! | | reaction | true | eyes | If set, the specified emoji "reaction" is put on the comment to indicate that the trigger was detected. For example, "rocket" or "eyes" | | success_reaction | true | +1 | The reaction to add to the comment that triggered the Action if its execution was successful | | failure_reaction | true | -1 | The reaction to add to the comment that triggered the Action if its execution failed | | allowed_contexts | true | pull_request | A comma separated list of comment