Issue Types Public Preview

[github-staff]

Feedback wanted

Thank you for participating in the issue types public preview. Please leave your feedback below on what is working well, any bugs you encounter, and what else you’d like to see!

To provide your feedback on other experiences released at the same time, please visit:

• Evolving GitHub Issues - Public Preview #148713
• Sub-issues Public Preview #148714
• Advanced Search for Issues Public Preview #148716

Issue types

Issues types allow you to classify and manage your issues with a shared and consistent language across all repositories in the organization, such as bugs or tasks.

Customizing default issue types

An organization administrator can customize the issue types that makes sense for the organization from the organization settings "Planning" page in the “Issue types” section, with bug, task, and feature provided by default to get you started. These are available for all repositories in the organization.

Organization settings page

Adding a type to an issue

When you create a new issue, you can change the issue type using the Type section on the right. You can also change the issue type from this location once an issue has been created.

Screen.Recording.2024-09-30.at.1.45.49.PM.mov

When creating a sub-issue from an issue, you'll find this at the bottom next to the other issue metadata.

Additionally, you can specify the type qualifier in issue forms in your repositories, so that each issue created from each template automatically has the type set.

Issue form with `type` field

If you’d like to add or change the issue type for existing issues, you can update it from the repository page by selecting one or multiple issues using the checkbox to the left of each issue, or from a project using the Type field by copying and pasting or dragging cells.

Creating custom views in your project

In a project, you can use the new Type field to customize your views by filtering, sorting, slicing, or grouping, so you can visualize and understand the breakdown of your issues.

You can even use the Type field in the auto-add to project workflow, so you can automatically add these to your project.

Auto-add to project workflow

Automating issue types

There are now typed and untyped webhook payload objects for the issues webhook event that trigger a GitHub action.

For the GraphQL API, there is an IssueType object to manage issue types at the organization level to create, update, and delete them. You can also create a new issue with an issue type, update the issue type, and query a repository by issue type.

Click to view GraphQL details

Note that these requests will need to include the GraphQL-Features header with a value of issue_types.

Objects and Fields

Query Issue.IssueType
Returns issue type based on issue ID

  node(id:ID) {
    ... on Issue {
      issueType {
        id
        name
      }
    }
  }
}

Query IssueType
Returns fields for issue type i.e. private, enabled etc.

  node(id:ID) {
    ... on IssueType {
      id
      name
      isEnabled
      isPrivate
    }
  }
}

Query IssueType.issues connection (w/ repository argument)
Returns total count of issues (with associated fields i.e. title, state etc) with an issue type based on specified repo.

  organization(login: LOGIN) {
   issueTypes(first: 10) {
      nodes {
        id
        name
        # Fetch the first 10 issues with this issue type
        # From the given repository
        # With an open state
        issues(first: 10, repositoryId: REPO_ID, states: OPEN) {
          nodes {
            id
            number
            title
          }
          totalCount
        }
      }
    }
  }
}

Query issueTypes using global search filter API
Org wide searches for issue type.

  search(type: ISSUE, first: 100, query: "type:Bug org:production") {
    issueCount
    nodes {
      ... on Issue {
        title
        repository {
          nameWithOwner
        }
      }
    }
  }
}

Mutations

Create Issue Type

mutation {
  createIssueType(input:{
    ownerId: "ID"
    name: "NAME"
    isEnabled:true
    isPrivate: true
  }) {
    issueType {
      id
    }
  }
}

Update Issue Type

mutation {
  updateIssueType(input:{
    issueTypeId: "ID"
    name: "NEW NAME"
  }) {
    issueType {
      id
    }
  }
}

Delete Issue Type

mutation {
  deleteIssueType(input:{
    issueTypeId: "ID"
  }) {
    deletedIssueTypeId
  }
}

Create Issue -> w/ Issue Type

mutation {
  createIssue(input: {
    repositoryId: "ID"
    title:"test-api-2"
    issueTypeId: "ID"
  }) {
    issue {
      id
      url
    }
  }
}

Update Issue -> w/ Issue Type

mutation {
  updateIssue(input: {
    id: "ID"
    issueTypeId: "ID"
  }) {
    issue {
      id
      url
    }
  }
}

Update Issue Issue Type

mutation {
  updateIssueIssueType(input: {
    issueId: "ID"
    issueTypeId: "ID"
  }) {
    issue {
      id
      url
    }
  }
}

Next steps

We are continuing to improve the Issues experience, and so we’d love to hear your feedback as you try out the new experience and start using issue types.

[hyangah]

Congrats for the feature release.
What are the key differences between the traditional label and this new issue type,
and when do you recommend users favor "issue types" instead of "labels"?

[rileybroughten]

Issue types are managed at the organization level to provide a global classification of an issue, such as a bug, task, or feature request, while labels are managed at the repository level. This ensures that issues are classified consistently across all repositories without the varying syntax and management of labels, so you can easily search for and understand the breakdown of work across an entire organization.

Using issue types alongside sub-issues also allows you to consistently break down your work and view the progress either from the issue or in a project, using the Parent issue, Sub-issues progress, and Type fields to build custom views by slicing, sorting, grouping, and filtering. We're looking into how we can further strengthen the relationship and integration between issue types and sub-issues.

[andrewbanchich]

this seems like a confusing new terminology / concept addition. why not just have "org-level labels"? labels are the standard for classifying issues. i'm not clear on why we need a new concept to be able to do the features listed here, like sorting or filtering.

this seems like it will add a lot of unnecessary duplication, work, and confusion.

[probitcarwyn]

They do indeed feel disjointed. Org level labels (that appear in all repos) combined with namespaced/nested labels would have arguably been more integrated, possibly with an easier migration path to promote certain labels from repos to org level (e.g. bug, enhancement and the other GH default labels).

A good example of this is that you can't have PR types, only labels. So if you have an issue of type "Bug" and you want your PR to carry that metadata too, you're still going to need a "Bug" label.

Types are also single valued which means you have to think carefully to avoid Pigeonhole problem when deciding what types you want.

Being able to at least relate sets of labels (preferably allowing overlapping sets) to types would have been useful too.

[jahirfiquitiva]

I agree this could've been "solved" by implementing organization-wide labels, instead of creating a new field that is also limited to issues only (not available for PRs) as mentioned by @probitcarwyn.

[jpobst]

It would be nice if the issue types were visible on the list of issues in a milestone (ex: https://github.com/dotnet/android/milestone/38).

When looking to prioritize work assigned to a milestone, probably the most important information is whether it is a bug or feature.