Repository setup

This page outlines recommended configuration settings for IssueOps repositories. For instructions on how to create a repository, see the GitHub documentation.

Visibility

IssueOps works best when your repository is accessible to users who need to submit requests. Depending on if the repository is owned by an organization or a user account, you can set the visibility to one of the following:

Alternatively, if you only want to allow specific users to submit requests, you can set the visibility to private and add those users as collaborators.

Permissions

Users only need read access to open issues! Unless there is a specific reason to do otherwise, you should only ever need to grant read access.

The primary reason to grant write access is if your IssueOps flow uses pull requests instead of issues, but only if you want users to create pull requests from branches in the same repository. As an alternative, you can allow forking of your repository and users can create pull requests from their forked repository instead.

Branch protection

Branch protection rules are a good idea regardless of what your repository is being used for! You should always protect your default branch (usually main) and any other branches that you want to prevent accidental changes to.

For an IssueOps repository, you should create a branch protection rule for main that enables the following:

• Require a pull request before merging
• Require status checks to pass before merging (add any continuous integration or testing workflows that you use)
• Require branches to be up to date before merging
• Require review from Code Owners (if your repository has a CODEOWNERS file)

GitHub Actions

Fork pull request workflows

If your IssueOps workflow uses pull requests instead of issues, you must be careful about the configuration of GitHub Actions and what permissions are allowed for fork pull requests. The following settings can be enabled for fork pull requests, with a description of the risks involved.

As you can guess, the safest option is to not allow fork pull requests to run workflows at all. However, this may not be practical for your workflow. Here are some recommended settings:

One alternative to consider is to "wrap" the creation of the PR into part of your IssueOps flow. If the content of the PR will follow a known format, you can use a GitHub Action to create the PR on behalf of the user. This will allow you to remove the need to allow any GitHub Actions access to fork pull requests.

Workflow permissions

In the repository settings, it is best to keep the base workflow permissions limited to Read repository contents and packages permissions. Within each IssueOps workflow, you can increase the permissions as needed for specific jobs.

Environments

If your IssueOps workflow involves deployments or interaction with environments, you should consider adding enviroment-specific rules to restrict deployments to only the main branch. A common exception to this rule is if you are running IssueOps workflows from pull requests, as these will be run from branches other than main.

This is also a good opportunity to further restrict access to secrets and variables by defining them at the environment level!

Other considerations

A few common questions and answers about repository setup. Most of the time, the answer is "it depends!", but these are some things to consider.

Multiple IssueOps workflows in one repository

There are some tradeoffs to consider when using one or multiple repositories to host different IssueOps workflows. For example, suppose you have the following workflows:

• Team membership requests
• New repository creation requests

If you use a single repository, one challenge you may run into is ensuring that jobs for the team membership requests don't affect new repository requests. This is where labels are particularly helpful! You can use labels to scope jobs to specific requests.

name: Issue Opened/Edited

on:
  issues:
    types:
      - opened
      - edited

jobs:
  new-repository-request:
    name: New Repository Request
    runs-on: ubuntu-latest

    # Only run for issues with the `issueops:new-repository` label.
    if: contains(github.event.issue.labels.*.name, 'issueops:new-repository')

  team-membership-request:
    name: Team Membership Request
    runs-on: ubuntu-latest

    # Only run for issues with the `issueops:team-add` label.
    if: contains(github.event.issue.labels.*.name, 'issueops:team-add')