Issues and PRs

The structure of issues and pull requests

• Alpha

This page provides an overview of the different components that make up issues and PRs, and includes information about how each component can be used throughout an IssueOps workflow.

Issues

Issue permissions

Any user with read access to a repository can open an issue.

Issue structure

Component	Description
Title	Title of an issue
Body	Main content of an issue entered by a user
Assignees	Users responsible for resolving an issue
Labels	Short tags that can be applied to issues
Milestones	Groups for issues and PRs
Relations	Other issues and PRs that are related to this issue
Development	Branches or PRs linked to the issue
Projects	Projects that are tracking the issue
Participants	Users who have interacted with the issue
Timeline	Events that have occurred on the issue
Comments	Comments and replies that have been added to the issue
Reactions	Emoji reactions added to the issue and its comments

Issue templates vs. issue forms

Currently, GitHub supports both issue templates and issue forms. When creating IssueOps workflows, the initial issue body is where you will get a lot of the information you need to process the issue. Depending on your use-case, issue templates may not result in the desired format, since they allow users to overwrite or replace the entire contents of the issue body during creation. Issue forms require specific input formats and result in a more consistent output.

Title

The title of an issue is a short, concise description of the reason the issue has been opened, such as a particular bug or piece of feedback. Typically, the title is the first thing a user will enter when they open an issue (or they may update it based on the initial title provided by the issue form).

When creating an issue forms, the title can be used as a way to identify the type of issue. For example, you can use a title like [Request] Team Membership: TEAM_NAME to indicate that the issue is a request to be added to a team. However, since this field can be modified by users, it should not be used as a way to validate the issue.

title: '[Request] Team Membership: TEAM_NAME'

Body

The body of an issue is where your workflow will get most of the information it needs to process the issue. When creating an issue form, you can use the body to provide instructions to the user, and to collect information from them. For example, you can use a markdown field to provide instructions, and then use an input field to collect the name of the team they would like to join.

For information about the different types of fields that can be used, see Syntax for issue forms.

Assignees

Assignees are users who are responsible for resolving an issue. If your workflow involves a review process, you can use assignees to indicate who is responsible for reviewing the issue. You can also use assignees to indicate who is responsible for processing the issue when manual tasks are involved.

assignees:
  - octocat
  - mona

Labels

Labels are a great way to control the flow of an issue through the state(s) you've defined. Any time a issue is commented on or updated, you can use labels to tell where in the flow it is currently, and where it needs to go next.

labels:
  - issueops:team-membership-request

Milestones

If you have certain timelines or deadlines associated with your workflow, you can use milestones to track them. Milestones are groups of issues and pull requests that are tracked together. They can be used to track:

• Due date
• Completion percentage
• Open and closed issues and pull requests

An issue cannot be added automatically to a milestone using issue forms, but you can use GitHub Actions to add it to a milestone after it has been created. See IssueOps Actions in the reference for more information.

Relations

When creating or commenting on issues, you can reference related issues by using the # symbol followed by the issue number. For example, if you want to reference issue 1 in another issue in the same repository, you would type #1.

Relations may be useful when your workflow involves multiple issues. For example, if you have a workflow that involves interaction with another team, you can use relations to track the status of the other team's issue.

Development

The development section of an issue is where you can track the branches and pull requests that are associated with the issue. This can be useful if your workflow involves creating branches or pull requests for the user. For example, if you would like to create an IssueOps workflow for users to create new repositories and you use an infrastructure as code service such as Terraform, you may want to create a PR on the user's behalf that includes the new repository definition. That way, developers don't have to learn Terraform to get new infrastructure, and operations teams can ensure all infrastructure is created following their requirements.

Projects

GitHub Projects are dual-purpose when it comes to IssueOps. They can be used to both track and change the state of an issue. This is especially the case when your workflow involves manual steps that must be performed by a human.

As a non-technical example, suppose you're planning Thanksgiving dinner with your extended family. Everyone in the family is supposed to suggest three dishes, prepare them, and bring them on Thanksgiving day.

You can open issues for each dish that needs to be prepared using an issue form, and automatically assign them to your meal project.

projects:
  - octo-repo/1

Within your project, you can specify columns for the state of each dish (e.g. New, Ingredients purchased, Ready to cook, and Cooked).

Participants

Participants are users who have interacted with an issue. This includes the user who opened the issue as well as users who have commented on or been assigned to the issue. You can use participants to track who has interacted with an issue, and to communicate with them if needed.

Timeline

The timeline is a list of all of the events that have occurred on an issue, starting from when it was first opened. Each timeline event includes a timestamp, the origin of the event, and other useful information.

The timeline is especially useful to verify information about an issue. For example, if you have a workflow that requires validation of the issue body, you can (and should!) use labels to mark the issue as validated. However, what happens if a malicious user adds the label manually? You can use the timeline to compare when the issue body was last updated to when the validated label was added. If the label was added before the issue body was updated, you can determine that the label was added manually and re-run your validation logic.

Comments

Other than the issue body, comments are how a user will drive your IssueOps flow. You should define keywords that your workflow looks for to trigger certain actions. Suppose you have a workflow where a user can create a new repository. After the issue has been validated, the user can comment on the issue with a keyword such as “.submit” to trigger the creation of their repo.

You can also use them to communicate information back to the user. For example, if the issue body contains invalid or incorrect information, you can reply to the issue stating what needs to be corrected. For example, in the screenshot, you can see that a comment was added to the issue because the request was missing information.

Reactions

Though they don't convey as much information as a comment, adding reactions to issues and comments are a nice way to let the user know that their input has been received and is being processed. If needed, you can follow up with a comment when processing is complete.

Example issue form

Issue form template

name: Team Membership Request
description: Submit a request to be added to a GitHub Team
title: '[Request] Team Membership: TEAM_NAME'
labels:
  - issueops:team-membership-request
assignees:
  - octocat
  - mona
projects:
  - octo-repo/1

body:
  - type: markdown
    attributes:
      value:
        Welcome to GitHub! Please fill out the information below to request to
        be added to a GitHub Team. Once submitted, your request will be reviewed
        by the admin team. Once approved, you will be added automatically!
  - type: input
    id: name
    attributes:
      label: Team name
      description: The name of the team you would like to join.
      placeholder: octoteam
    validations:
      required: true

Rendered output

Pull requests

Pull requests add extra features and metadata on top of issues. Many GitHub APIs support interacting with both at the same time! These additional features, along with examples of how to use them in IssueOps workflows, are listed in the following sections.

PR permissions

In order to create a pull request, the required permissions will differ based on the location of the branch you wish to merge.

Location	Permissions
Same repository (branch)	Write access
Different repository (fork)	Read access

Reviews and approvals

Unlike issues, PRs support reviews and approvals out of the box. When changes are ready to be merged, you can assign individuals or teams as reviewers. Branch protection can also be used to enforce required reviewers and other checks before a PR can be merged.

When your IssueOps workflow includes changes to the contents of a repository, using PRs instead of issues is a great option to enforce specific approval settings without having to include additional workflows for tracking approvals as comments.

Status checks

Status checks run any time a PR is created or updated. These can range from code quality checks to security scans and more. You can use status checks to ensure that the changes in a PR meet your organization's standards before they are merged.

In an IssueOps workflow, there are two ways you can use status checks: to validate the contents of the PR, and to validate the contents of the issue.

Validation is a critical aspect to consider when designing your workflow. If your workflow is best suited for PRs, status checks can be used to run your validation workflow any time the PR is updated. Combined with branch protection rules specifying required status checks, you can ensure that validation rules pass before a PR can change states.

Deployments and Environments

When a GitHub Actions workflow runs that specifies an environment, a deployment is created. Deployments track the successful/failed status of a workflow run, and link it to the targeted environment.

A great example of an IssueOps workflow that uses PRs, deployments, and environments is the branch deploy model. A detailed explanation can be found in the reference.