Repository files navigation

IssueOps commands in GitHub Actions!

Like ChatOps but for GitHub Issues and Pull Requests 🤩

This project is based off thegithub/branch-deploy Action. There aremany similarities between the two, but there is a key difference. Thegithub/branch-deploy Action is designed specifically for deployments via IssueOps where this project (command) can be used forany 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

A quick section to get you started with this Action

Basic usage assuming all defaults:

-name:commandid:commanduses:github/command@vX.X.Xwith:command:.lint# can be anything you want (example)

Advanced usage with some custom configuration:

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

For configuration details, see theinputs section below

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

name:"command demo"# the workflow to execute on is comments that are newly createdon:issue_comment:types:[created]# permissions needed for reacting to IssueOps commands on issues and PRspermissions:pull-requests:writeissues:writechecks:readcontents:read# useful if your workflows call actions/checkout@vX.X.Xjobs:demo:runs-on:ubuntu-lateststeps:# execute IssueOps command logic, hooray!# this will be used to "gate" all future steps below      -uses:github/command@vX.X.Xid:commandwith: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:pingif:${{ 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

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

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

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 wishname:"IssueOps github/command demo"# The workflow to execute on is comments that are newly createdon:issue_comment:types:[created]

It is important to note that the workflow we want to run IssueOps on isissue_comment andcreated. 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 workflowsonly use files found onmain to run. If you do something likeon: 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 usingissue_comment is the suggested workflow type. It should also be noted that comments on pull requests,and issues will trigger theissue_comment workflow event.

# permissions definitionspermissions:pull-requests:write# required for adding reactions to command comments on PRsissues:write# required for adding reactions to command comments on issueschecks: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-lateststeps:# Checkout your projects repository      -uses:actions/checkout@v4

Sets up yourdemo job, uses an ubuntu runner, and checks out your repo - Just some standard setup for a general Action. We also add anif: 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 theif: condition

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

Note: It is important to set anid: 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 thegithub/command action to run. It will do the following:

1. Check the comment which invoked the workflow for thecommand: 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:pingif:${{ 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 thecontinue variable:

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

Example: You comment.ping on a pull request. A workflow is kicked off and thegithub/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 thecontinue variable totrue. This will allow the "ping" step seen above to run.

This Action supports a configurable input calledallowlist which can be used to specify a list of individual GitHub users or teams that should have permission to use this Action. By default, this input option's value is set to"false" which means that anyone how has the properpermissions (see theinputs section above) "permissions", will be able to invoke IssueOps commands. You can actually use both theallowlist andpermissions input together to help control who can invoke IssueOps commands. For example, you could use these two options together to only allow people in the GitHuboctoawesome team withadmin permissions to run your commands.

Theallowlist input option takes a comma separated list of GitHub handles or GitHub org teams. For example, if you give the optionallowlist: monalisa, themonalisa user will be the only user allowed to invoke IssueOps commands (assuming they also have the correctpermissions)

Here is a simple example using only handles below (the monalisa and octocat users will be allowlisted):

-uses:github/command@vX.X.Xid:commandwith:allowlist:monalisa,octocat

Here is an example using a mix of GitHub handles and a GitHub org team below:

-uses:github/command@vX.X.Xid:commandwith:allowlist:monalisa,octocat,octo-awesome-org/octo-awesome-teamallowlist_pat:${{ secrets.ALLOWLIST_PAT }}

In this case, all users (and future users) in theocto-awesome-org/octo-awesome-team team will be treated as admins in addition to the monalisa and octocat users

It should be noted if you choose to use GitHub org teams for allowlist definitions, youwill need aGitHub Personal Access Token with theread:org scope. This is because the Action will need to make API calls on behalf of an authenticated user in the org to retrieve team memberships. If you choose to only use GitHub handles for admin definitions, then theallowlist_pat input is not required

Note: You can read more about theallowlist option under theinputs section in this readme

Check out some of the links below to see how others are using this Action in their projects:

• coming soon!

In order to ensure your usage of this action is stable, it is highly recommended that you use either pin your action to a SHA or use a specific release tag

You can easily select the exact version you want on the GitHub Actions marketplace seen in the screenshot below:

You can also pin to an exact commit SHA as well using a third party tool such asmheap/pin-github-action

GitHub Actions security hardening and stability docs available here:docs

This section will cover a few suggestions that will help you when using this Action

1. Suggest Updating Pull Request Branches - A great setting to enable for pull request hygiene. This option can be found in your repository's/settings page

   

2. Enable Branch Protection Settings - It is always a good idea to enable branch protection settings for your repo, especially when using this Action

The security aspects of this Action have already been well documented in thebranch-deploy repo. Please see the followingdocs to learn more.

All contributions are welcome from all!

Check out thecontributing guide to learn more