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"?

[probitcarwyn]

Thinking about it a bit more, issue types could have been implemented as namespaced labels where types are a namespace (optional at the discretion of the organisation). You often see namespaces emulated via naming conventions like type:bug or type-bug. Existing labels would then just be in the default namespace, and something tidy could be done to make a given namespace repo or org scoped.

There's another parallel to labels too, project fields, that also annotate issues with metadata, but only if the issues are in a project. The main gotcha with these if that if you remove an issue from a project, this metadata is lost. It's causing quite some confusion for us now having these somewhat disjoint metadata sources, each with their own semantics. Arguably project fields are the richest, but lacking a multi-valued option which labels have.

A similar dichotomy exists between milestones, and project based date fields with sub-issues, again with different semantics.

It would be interesting to see the thinking behind the data model and semantics of these features, especially how the semantics relate to each other. Was this considered? I do wonder if a more formal theoretical basis for these features would be beneficial?

Thinking ahead to issue workflows (which has vanished from the roadmap) i do wonder if all this makes that task much more complex than it needs to be. The lack of workflows (which are really allowed metadata state transitions) is the biggest bugbear we have with GH issues at the moment. Workflows and especially enforced workflows being a big requirement for larger organisations that have certifications to consider. For example, there's no way to block issues progressing through a project board without some pre-condition being met. Actions would be great for this, but all you can do to enforce is write a convoluted action using the APIs to move things back after they move when they shouldn't. Bots are a sticking plaster over this stuff.

[oliviertassinari]

The thread in the initial issue (during the opt-in phase) https://github.com/orgs/community/discussions/139933#discussioncomment-10885036 touches the same problem. "Issue types" in its current shape seems harmful (less is more).

Org level labels (that appear in all repos) combined with namespaced/nested labels

This would be great. In our case, we have have 3 kind of issue labels: a. Product scope labels (e.g. billing, onboarding) b. Prioritization type labels (e.g. regression, bug, new features, priority: high) c. Skill / kind of work labels (e.g. design, Safari). The notion of issues type feels absurd in our context (too opinionated to help).

Off-topic: Going to amazing for us would be to be able to subscribe to notifications that are only about new issues with specific labels so product owners can be aware of new (a.) Product scope labels.

[vyudh]

How does the introduction of "issue types" enhance issue categorization and management?

[alystair]

https://github.com/orgs/community/discussions/16682 scoped labels solve this entirely without added noise. It's the only reason my org sticks to Gitlab at this point.

[simon-abbott]

I agree 100% with using scoped labels + organization labels. Would be a much more flexible solution. Our org has lots of labels already that are in the <category>:<entry> format, and we've been annoyed for years at the lack of ability to sync common tags between all our repos. This solution for types is a step in the right direction at least, but the two solutions described above would have solved all our labeling issues at once. As it stands we still can't sync the rest of our labels across our repos without external tools.

[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.

[rileybroughten]

Thank you for this feedback! We are aware of this and have plans to bring issue types to this page as well. We will keep you posted on when you can expect this as we know it is an important piece of information to see as you work with milestones!

[andrybedo]

Is there an expected timeline for when this feature will be implemented?

[rileybroughten]

We do not have a concrete timeline quite yet as we make plans to migrate the milestones, labels, and /issues dashboard pages, but as soon as we have more details we'll be sure to share them with you all!

[jrfnl]

Can an option to disable this be added please ?

As @hyangah @andrewbanchich @@probitcarwyn and @jahirfiquitiva pointed out above, this has a HUGE duplication with labels - and in most repos/organisations, this is already handled via labels.

As a developer, I don't like having to maintain duplicate code in multiple places.
As a maintainer, I don't like having to maintain duplicate classifications for issues in different taxonomies.

The field is just noise I can do without.

Actually, on that note: why does the "Projects" field still show up when the "Projects" feature has been disabled for a repo ? Again: noise I can do without.

[rileybroughten]

Appreciate all of the feedback on this! We will keep you posted for any updates.

[LeaVerou]

@rileybroughten Labels are a workaround. Making it an explicit field is the right way to go, what you're observing here is just the usual migration pains + change aversion.

[probitcarwyn]

I disagree @LeaVerou , if you think about the actual data model underneath this, and especially how you might want certain labels to only apply to certain types, then scoping/nesting is what you end up in that case too. Once you get to there you're back to questionable value of a disjoint metadata field, especially when you think ahead to how you might implement workflows (state machines across label states). Having been on the private preview for a few months now with Issue Types, when to use which (label vs type) and the lack of types on PRs has been a consistent topic of confusion.

[iphydf]

I like having enforcement of a singular "label". I don't want people to label things as feature and bug. Having a field for singular classification is nice on top of the labels to further describe the issue.

[Topher-the-Geek]

We too need an option to disable this field. We deleted the bug, feature and task labels, and we don't want this field. The previous labels and this field provide no value to our workflows for managing issue, but they do create cognitive load for our users filing issues.

[dingo-d]

Can you add the ability to select the issue type in the issue templates? Because currently we are limited to labels, and then manually selecting the type, which is less than ideal 🤷🏼‍♂️

[rileybroughten]

You can also specify the issue type in issue templates - when making edits to your issue templates, you'll find the documentation on the right side and can use the type field to specify

[dingo-d]

So it's available in the yml files as well? Because the documentation doesn't have this field mentioned.

Maybe it should be added with the asterisk that it's an organization issue only thing.

[rileybroughten]

Good suggestion! We're working on getting the public documentation updated to include this field.

[beingminimal]

@rileybroughten projects are not supported in md files issue templates, as they are supported in yml file of issue templates, any ETA?

[rileybroughten]

We don't have an ETA at the moment, I've raised this again with the team and will keep you posted with any updates 👍

[webknjaz]

Feedback: the type field is not documented in the Issue Forms doc. It took some time for me to google this specific discussion to confirm that it's supposed to work.

Action item: Document this outside this discussion @ https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms.

[rileybroughten]

Thank you for this feedback, we'll work on getting the documentation updated!

When making edits to your issue forms, you'll see a note on the right hand side for configuration options.

[webknjaz]

Feedback: Issue Types don't seem to be available in regular GitHub accounts, only in the orgs (some orgs?)

Suggestion: Make them available to mere mortals. This may be useful to mass-maintainers who organize their repos under personal accounts rather than creating orgs.

Workaround: One would be tempted to create an org just to gain access to such features. It's not a bad thing, it's actually a good way to organize big amounts of projects and get a number of other features that are rather limiting in user accounts. I'm pretty sure people do this for other features already.

[rileybroughten]

Thank you for the feedback and for the suggested workaround, while we don't have plans to expand this to user accounts, we'll keep you posted on any updates.

[Nicolas-Innocent]

feedback: when using a board display in projects, it would be nice to have a view of this in the toasts. Since space is very limited there, might I suggest a colored bar (option ?)

something like this ?

[rileybroughten]

Thanks for this feedback! You can also choose to show or hide the Type field on items in your board view.

[Nicolas-Innocent]

oh, I realize that, but it displays it mixed in with the labels which kind of defeat the purpose of having them separate (and honestly render them useless if I understand the design purpose of quickly being able to identify a toast type).
The other option might be to display the type tag between the repo and assignee .

[IntegratedQuantum]

I noticed that you can only select between a small number of colors.

I think these colors are too saturated and make the issues tab rather noisy and cluttered (at least in dark mode). Choosing gray for everything fixes it for now, but in the future I would like the option to pick less saturated colors. There should be a color wheel or just a field for the hexcode like for label colors.

[rileybroughten]

Thank you for this suggestion, we have it noted 👍

[jon-nfc]

+1 for a colour wheel or field for html hex code

[beingminimal]

+1

[alystair]

We're getting issue types before scoped labels? It's been years 😔
https://github.com/orgs/community/discussions/16682

[LukasKalbertodt]

It would be nice to make issue types a repository-level setting. Otherwise, when moving a project to a different org, I imagine weird things will happen. Having that contained in the repository seems more useful to me.

[simon-abbott]

Our org already has issue types in the form of labels, but I can't find any way to bulk-convert from one to the other. Are there any plans to add functionality like the "Convert to discussions" button for switching over to the new format?

Alternately I would love to see support instead for scoped labels with organization-level management (like the way workflow secrets work). That would allow us to keep all our existing tags, just move them up to the org level.

[rileybroughten]

As far as bulk converting there are a few options:

• 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, and note REST API support is coming soon!)

[LeaVerou]

@rileybroughten this is what we did too, but it would be nice to have a way to override the pagination so that folks don't need to do it once per page (and large repos can have A LOT of pages!). Especially since it takes some time to apply bulk actions, and one cannot trigger another bulk action while one is already running.

[lemonpole]

Is it possible to create an issue via the REST API with an issue type?

I could not find this mentioned in the REST API docs and in this post, only GraphQL was used as an example.

• https://docs.github.com/en/rest/issues/issues#create-an-issue

[RahulGautamSingh]

Rest API responses do not have the issueType info so I doubt this can be done currently. Bit weird to only access/modify this info via the GraphQL API.

[simon-abbott]

Yet another point in favor of just doing this change via scoped labels instead, all the existing APIs will just work with no modifications needed.

[rileybroughten]

We're working on REST API support and will provide an update when that is complete on our end. Appreciate your patience on this!

[alystair]

I have a mostly working GitLab to GitHub importer and having scoped labels would bring so many folks over that were holding out including myself.

[Seldaek]

I wonder why is it not possible to assign types to pull requests? I often create pull requests out of the blue without having an issue first, and now while migrating to issue types I found that I end up with a need to keep Feature/Bug labels just to be able to assign them to PRs.

P.S: Overall I'm quite liking this for organizations with lots of small repos where doing the work of setting up labels on every repo was too much of a hassle. Thanks 👍🏻

[rileybroughten]

Thank you for this feedback! They are scoped to only being present on issues to help you categorize and classify your work, break it down if needed using sub-issues, and report on it so you can understand the breakdown and progress of work across repositories. Then creating or linking a pull request helps you track the code changes and fixes to resolve and close out the bug, task, etc.

[SteveG-tkorp]

Hello,
I agree with @Seldaek, it would be great if the types of issues could be communicated to the PRs, as this would allow the changelog to be generated with PRs sorted by type directly.

Thanks !

[montyclt]

What about enabling organizations to define multiple dropdown fields, each with their own options? For example:

• Type

• • Bug
• • Feature
• • Documentation
• • Meta-issue

• Difficulty

• • Good first issue
• • Standard

• Critical

• • Critical
• • No critical

I usually use Notion due this capacity. A screenshot for reference:

[probitcarwyn]

This has been called scoped labels or nested labels in other comments on this thread. I do think this is what Types should be and it should be unified with labels. See also:

• https://github.com/orgs/community/discussions/16682

[LeaVerou]

Great feature! I agree it would be nice for the list to be customizable.

One bug we noticed: it seems that if an issue is set to an issue type of "Bug" it doesn't show up in the Bugs section, as that is keyed on "bug" labels only. Ideally, it would be an OR.

[rileybroughten]

I agree it would be nice for the list to be customizable.

Could you elaborate how you would like this be done?

One bug we noticed: it seems that if an issue is set to an issue type of "Bug" it doesn't show up in the Bugs section, as that is keyed on "bug" labels only. Ideally, it would be an OR.

What is the Bugs section in this case? If you could provide more details or screenshots on this setup that would be great!

[iphydf]

This doesn't seem to work in issue templates, unlike what the initial post says:

[rileybroughten]

I tried to replicate this using a form with a .yaml file extension with the same input and wasn't able to see the same error. Could you provide a link to this issue form so we can investigate?

[iphydf]

It was because I wanted to test on my personal repo before merging it into the org's repo. Turns out, it's not available on personal repos, so I couldn't test and had to push it blindly. It does work now, on the org's repo.

[cagney]

ah, tripped up by same problem

[Phil-DS]

I like these. Of the basic 3, only Task was one that we didn't already have a label for. Nice to keep these apart.

[jannis-baum]

Why is this only available for organizations? Would be great to be able to use it on personal repos as well.

[octatone]

Appreciate the feedback! I’ve passed this along to the team, and we’ll see what we can do.

[jackbentley]

Feedback: Adding/removing/changing an issue type doesn't show as a timeline item in the issue. When adding/removing labels it's shown in the timeline.

[rileybroughten]

Showing timeline events when modifying the issue type is in progress, I'll provide an update on this post when it's available!

[scottdorman]

Why is this limited to just organizations? Defining it at an organizational level makes the issue types consistent and available across all repositories in the organization, but not everyone works only in organization repositories. I'm sure I'm not the only one with personal public (and private) repositories that would benefit from having issue types.

We should be able to define it at the organization and repository levels. If the repository is part of an organization, you have two choices: you can't redefine issue types and must use the organization ones, or you can. If the repository is personal, you can define it at the repository level.

[jmklix]

It's mentioned that:

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

But it doesn't appear to trigger a webhook event when the type is changed. It does include the "type" when an issue is created or closed, but there doesn't seem to be a way to capture when the type is changed. Both the webhooks docs and graphql docs don't include any mention of the new types.

Basically I have two asks:

• please make type changes trigger a webhook event
• please update the documentation to include info on issue type

[rileybroughten]

Currently, the issue type is available in the action event payload for the following issue-related events: opened, closed, reopened as github.event.issue.type and for issue type related events (typed, untyped) as github.event.type when an issue type is added, edited or removed from an issue.

We're working to include the issue type in all payloads and getting public documentation published, appreciate your patience on this!

[GuySartorelli]

It would be nice to be able to disable the "type" feature completely, so it doesn't display at all on issues. We use labels for this and aren't likely to migrate to use types in the near future. We've disabled all of the default types, but having an empty dropdown there is a bit silly.

[gstokkink]

@rileybroughten I've been trying to use the listed GraphQL mutations to add an issue type to queries using a Github Action but I keep running into the following error: - Field 'updateIssueIssueType' doesn't exist on type 'Mutation'. I have included the issue_types feature header. This can be reproduced in GraphQL explorer.

In case it matters, I use https://github.com/octokit/graphql-action and my action looks as follows:

---
name: Set correct type for issues

on:
  issues:
    types:
      - labeled

jobs:
  label_issues:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: "add issue type Bug if issue contains label bug"
        if: contains(github.event.issue.labels.*.name, 'bug')
        uses: octokit/graphql-action@v2.x
        with:
          query: |
            mutation addIssueType($issueid:ID!,$issuetypeid:String!) {
              updateIssueIssueType(input: {
                issueId: $issueid 
                issueTypeId: $issuetypeid
              }) {
                issue {
                  id
                }
              }
            }
          variables: |
            issueid: ${{ github.event.issue.id }}
            issuetypeid: "<redacted>"
          mediaType: |
            previews:
            - issue_types

What am I doing wrong?

[rileybroughten]

This is a bug with the GraphQL Explorer where it does not send request headers. This has been raised with the team to work on a fix, but in the meantime you can use any alternative such as Insomnia or Curl.

[turadg]

Will transitions of this field be viewable? If someone reclassifies an issue it's helpful to see that it happened, and ideally who did it so you know who to talk if you disagree. We'd been using labels to classify "bug" before and label changes show up in the issue history, so in switching to Issue Type we would lose that functionality.

[rileybroughten]

We're still working on showing the activity in the issue timeline when issue types are added or changed (see comment). I'll provide an update when that is available 👍

[turadg]

Thanks. I looked for an existing comment but missed that one.