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:

• Sub-issues Public Preview #139932
• Advanced Search for Issues Public Preview #139934
• Issues: Index, Create and Show Page Updates Public Preview #139935
• Increased Project Item Limits Public Preview #139936

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 for the organization from the organization settings "Planning" page in the “Issue types” section, with bug, task, and feature provided by default. 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.

[RanVaknin]

What is the main benefit of using types over using labels of the same name? Ie; use a bug label rather than a type.

[DNin01]

For one, you can sort and group by issue types in Projects.

And other than that, it's just more upfront than labels.

[probitcarwyn]

I notice that the default labels for repos now overlap with the default issue types. This likely needs some clarification in the docs and possibly the option to mass migrate from labels to types?

[rileybroughten]

Issue types are managed at the organization level for a global classification of an issue, while labels are managed at the repository level. This ensures that issues are classified consistently across repositories without the varying syntax and management of labels, so you can search for and understand the breakdown of work across all repositories in an organization. This also makes it easier to understand this in a project, where issues can be added across repositories and organizations.

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.

[rileybroughten]

I notice that the default labels for repos now overlap with the default issue types. This likely needs some clarification in the docs and possibly the option to mass migrate from labels to types?

Thank you for this feedback! We'll be evaluating the default labels provided.

As far as bulk migrating, the best ways to do this are to

• Utilize the bulk editing capabilities in a project using copy/paste or dragging table cells (see documentation)
• Use the filter bar and quick filter dropdowns to make bulk edits to existing issues.
  
• Use the API to do this programmatically (see "Automating issue types" section above)

[fpigeonjr]

Would tech-debt be considered an enhancement or should it be its own label?

[rileybroughten]

You can customize the set of issue types available for the organization (up to 10) as well as the description to help guide what they should be used for, so you can modify, add, or delete issue types as needed for your organization.

[bastimeyer]

There's a bug when trying to filter issue types which contain whitespace when using the dropdown in the issue list header. It doesn't wrap the issue type name in quotes, so the filter query becomes this for example:
is:issue is:open type:plugin issue
instead of
is:issue is:open type:"plugin issue"

The same doesn't happen when clicking the type button directly on an item in the issue list. Here, it properly sets the quotes.

[rileybroughten]

We're aware of this bug and will provide an update when a fix is available! Thank you for reporting 👍

[bastimeyer]

Btw, is it intentional that when changing issue types that there's no item added to the issue history, like when changing labels?

[rileybroughten]

We have it on our backlog to support events in the issue timeline so you can see changes over time, we'll provide an update once this is supported in the future 👍

[bastimeyer]

Another bit of feedback:

In our repos, we've been labeling issues and their respective PRs with the same labels (for example "plugin issue", "bug", etc.). Since PRs (currently) don't have the type attribute, changing our issue labels with dedicated type attributes would mean that we "disconnect" the issues and their respective PRs (apart from the closing/resolving/fixing links), and we would not be able to fully remove the old type-labels.

So the question is, would it make sense adding types to PRs as well?

[rileybroughten]

We don't have plans to add types to pull requests. Do you have other automations or workflows that are relying on the issues and their linked pull requests to have the same set of labels?

[bastimeyer]

No, we don't have any label-automations.

However, by moving all our labeled issues to specific issue types and removing the respective old labels from the issues, issues and PRs can't be categorized in the same groups anymore, unless we keep the duplicate labels on the issues. This is pretty bad for us organizing/moderating stuff, and for users browsing/finding stuff.

The new issue types allow for better semantic categorization. Labels which were previously also used for categorizing stuff can now purly be used for adding additional annotations, which is great. But if PRs lack this feature, then nothing is really gained from this, because both systems are very much intertwined.

Why should issues be put into the "bug" category via the issue type attribute, while PRs resolving those kinds of issues can not, and instead still need to be labeled "bug", making both categorization systems incompatible with each other?

[scordio]

On a related use case, we were looking at automation for generating release notes, where issue and PR references would be grouped under a markdown section based on a label.

For example:

• New Features section for all issues and PRs having the new-feature label
• Bug Fixes section for all issues and PRs having the bug label
  and so on.

Generally, an issue holds the label relevant to the release notes. Sometimes, a PR has no corresponding issue and gets the label directly.

When moving to issue types, such PRs without issues won't be included in the release notes, and the project would need to create artificial issues to keep the release note generation consistent.

[ruuda]

Small detail: on the issues page, if you filter by type, it populates the search box with

is:issue state:open type:Bug 

The casing is inconsistent between these filters, Bug is capitalized while issue and open are not.

[lukewar]

Thanks for the feedback. This is similar how labels filtering works today. I am curios would you expect labels also to be lowercased when applying the filter?

[TWiStErRob]

You can rename your Types at the org level to be lowercase.

[wojtekmaj]

There should be an option to easily migrate labels to types.

[rileybroughten]

See this comment above for some tips on how you can make bulk updates from using labels to issue types

[wojtekmaj]

There should be a way to filter Issues by a LACK of type, so that PMs could backfill information on already created tickets.

[tay1orjones]

I think you can do this by stacking multiple individual negated task filters.

is:issue state:open -type:bug -type:task -type:enhancement ...

I agree a no:type would be much better.

[rileybroughten]

Thank you for this feedback, we have it noted!

[wojtekmaj]

Table header should be sticky to allow easily assigning labels/types/… without scrolling up after selecting an issue further down the list.

[rileybroughten]

Could you provide an example or screen recording of what you are observing?

[wojtekmaj]

I'll try!

So when managing properties of an item higher up in the table, all the controls are within my reach:

But if I want to manage an item further down the list, I'm selecting it…

…and scrolling up to see the options to assign labels and issue types.

Oh wait, what was the issue I selected? Let me scroll back down again. Oh, it was this one. Let's scroll up again and add that label.

[njzjz]

The issue template can add labels automatically. Will it support the issue types?

[bastimeyer]

It's in the OP. Click "Issue form with type field" and see the screenshot.

[njzjz]

Oh, I see. Thanks!

[scordio]

Would you consider displaying the issue type also for pinned issues?

See for example https://github.com/assertj/assertj/issues, where assertj/assertj#3489 is pinned and has issue type New Feature.

[RussKie]

How do I bulk assign a type?

https://github.com/gitextensions/gitextensions/issues?q=sort%3Aupdated-desc+is%3Aopen+label%3A%22type%3A+bug+%3Abug%3A%22

[therealedsheenan]

Im curious about this too. What I usually do as a workaround(My team is using projects btw) is that we copy past values from the columns on the table view. Something like below:

We copy one item and then highlight the columns below and paste it(I assume it would be the same with Type column too.

I don't have any idea how to do bulk from the issues page.

[scordio]

I stumbled across the same and realized there were pull requests between the results, which cannot receive issue types.

Adding is:issue to your search query should bring checkboxes on the left side to allow bulk changes.

[RussKie]

Thank you @scordio, that worked!

[TWiStErRob]

See also https://github.com/orgs/community/discussions/139933#discussioncomment-10824698

[beingminimal]

@rileybroughten can you please share when issue types will be supported in gh cli? shouls i create issue in gh cli repo?
Awaiting your response. Thanks

[lukewar]

This is something that we plan to work on. Do you have any specific action you would like to see as part of it?

[beingminimal]

Basic operations with types would be fine like assign, get, remove & change type of issue, as of now this would be fine. Thanks
Here is the issue i have created.

[scordio]

Currently, issue types cannot be seen on GitHub Mobile. Is a beta rollout also planned there?

[lukewar]

We are working on adding GitHub Mobile support as well.

[acidoxee]

Release changelogs (with a release.yml file) are currently based on labels to form groups (such as new features, bugs, chores...) via changelog: { categories: [{ labels: [ ... ] }] }. Will there be a new kind of matching possible based on issue types rather than labels?

[jeherve]

Would it be possible to automatically assign an issue type such as "Task" to issues created by converting project cards into issues? It would be a welcome addition that would save some time with issue triage.

[jeherve]

Is it possible to specify an issue type as a query parameter when creating a new issue, e.g. https://github.com/myorg/myrepo/issues/new?template=bug-report.yml&labels=Bug&type=Bug?

[lukewar]

@jeherve it is currently supported egz. https://github.com/myorg/myrepo/issues/new?type=Bug. Could it be that you have a different type specified in the template that overriders the query parameter?

[jeherve]

It works indeed, I had mistyped! Thank you!

[wkmor1]

So I understand that the advantage of types over labels is that we can create types at the org level instead of creating labels for each of our repos. Is there are way to filter all the issues across our org by type like we can by label.? At the moment it seems like a type:{type} filter can only be used from in a repo or a project and not at github.com/issues in combination with org:{org}.

[jeherve]

Are there any plans to make it possible to assign an issue type via Octokit?

[dansheerhealth]

As a interim we're using GraphQL for API query/mutate with issue types.

[tnordquist-bis]

Permissions

In order to get the issue-types (name and id), one needs organization:admin (read?) permissions.

This is not working using App Installation Tokens, only using PATs.

Also organization:admin permissions appears to be a bit too elevated, since you can technically extract the same info when selecting an issue-type while creating an issue in the frontend.

A GitHub App wanting to create issues with issue-types would require organization:admin privileges, just to get the issue-type ids (if app permissions would be working).

[shaun-nx]

Hi there.

I'm looking for help with adding a new Type to our project.
By default, it looks like "Bug", "Enhancement" and "Task" are the default Types

I added an epic.yaml file to .github/ISSUE_TEMPLATE of the project and then merged that into the default main branch.

The good thing is that, when creating a new issue, the Epic showed up in the list of issues to create!

However, I noticed the Epic still isn't in the list of of issue Types in the dropdown

Is there something else that we need to do to add a new type?

For context, this is the epic.yaml file that we made to test with:

name: Epic
description: Create an Epic
labels: ["ready for refinement"]
type: 'Epic'
body:
  - type: textarea
    id: Overview
    attributes:
      label: Overview
      description: High-level overview of the work to be done
      placeholder: |
        As a "Blank", I want to "Blank", so that "Blank"