GitHub IssueOps Self-Service Portal
April 17, 2025 ยท View on GitHub
This repository serves as a template to create a self-service portal for managing and sharing IssueOps using GitHub Actions. You can deploy your own version of this portal using GitHub Pages!
IssueOps are a powerful way to automate various tasks using GitHub Issues. This repository contains a set of common IssueOps that can be used by developers in your organization to perform common tasks without needing their corresponding permissions.
The supported IssueOps can be found in the Supported IssueOps section of this README. They are divided into three categories, based on the permissions they require and the scope of the operation:
- Enterprise
- Organization
- Repository
Get Started
- Fork this repository into an organization you manage.
- Enable GitHub Pages in your forked repository.
- Configure GitHub Actions in your forked repository.
- Create a GitHub App and install it on your forked repository.
- If you plan to use the enterprise IssueOps, or want to use a single repository for IssueOps across multiple organizations, create an enterprise token.
- Run the Create IssueOps Labels workflow in your forked repository to create the required labels.
- Run the Continuous Delivery workflow in your forked repository to deploy the portal.
Configure GitHub Actions
The following settings should be configured in your forked repository. For more information, see Managing GitHub Actions settings for a repository.
| Setting | Value |
|---|---|
| Workflow permissions | Read and write permissions |
| Allow GitHub Actions to create and approve pull requests | Enabled |
Create a GitHub App
A GitHub App is used to process any non-enterprise IssueOps, as well as IssueOps targeting the same organization where your forked repository is deployed. When deploying this portal into your own organization, you will need to create a new GitHub App and install it on your forked repository. For more information, see Creating GitHub Apps.
The following settings should be configured in your GitHub App:
| Setting | Value |
|---|---|
| GitHub App name | IssueOps Bot |
| Homepage URL | The URL of your forked repository. |
| Private key | Generate a new private key. |
Configure Permissions
The following permissions encompass all of the IssueOps that can be used by this
portal. However, you can choose to only enable a subset of these permissions. If
you do, make sure to update the issue-ops.json file
to remove any IssueOps that require the disabled permissions.
| Type | Permission | Scope |
|---|---|---|
| Repository | Administration | Read and write |
| Repository | Contents | Read-only |
| Repository | Issues | Read and write |
| Repository | Pull requests | Read and write |
| Organization | Administration | Read and write |
| Organization | Members | Read and write |
| Organization | Announcement banners | Read and write |
| Organization | Projects | Read and write |
| Organization | Variables | Read and write |
Configure Secrets and Variables
Make sure to set the following values as secrets in your forked repository:
| Secret Name | Value |
|---|---|
GH_ENTERPRISE_TOKEN | The personal access token for your enterprise. |
ISSUEOPS_APP_PRIVATE_KEY | The private key of the GitHub App you created. |
Make sure to set the following values as variables in your forked repository:
| Variable Name | Value |
|---|---|
ISSUEOPS_APP_ID | The ID of the GitHub App you created. |
Create an Enterprise Token
If you plan to use the enterprise IssueOps, you will need to create a personal access token (PAT) with the following permissions. This is not required if you are only using the non-enterprise IssueOps.
Note
It is recommended to create a machine user account to use for this token!
| Permission |
|---|
repo |
admin:org |
admin:enterprise |
Enable GitHub Pages
Follow the instructions in publishing with a custom GitHub Actions workflow.
The workflow is already provided:
continuous-delivery.yml.
Supported IssueOps
All of the supported IssueOps are listed in the
issue-ops.json file. They are divided into three
categories, based on the permissions they require and the scope of the
operation:
- Enterprise
- Organization
- Repository
The full list of supported IssueOps can be found in the following table.
| Category | Name | Description |
|---|---|---|
| Organization | Announcement | Create an organization announcement banner. |
| Organization | Project | Create a project for your organization users and repositories. |
| Organization | GitHub Actions Variable | Create an organization variable to use in your GitHub Actions workflows. |
| Organization | Repository Transfer | Transfer a repository. Requires enterprise admin approval. |
| Repository | Create Repository | Create a new repository in your organization. |
| Repository | Rename Repository | Rename a repository in your organization. |
| Repository | Archive Repository | Archive a repository in your organization, converting it to read-only. |
| Repository | Change Visibility | Change the visibility of your repository. |
| Repository | Unarchive Repository | Unarchive a repository. |
Adding New IssueOps
See the CONTRIBUTING.md file for instructions on how to add new IssueOps to this portal.
License
This project is licensed under the terms of the MIT open source license. Please refer to LICENSE for the full terms.