Have you ever built an issue template, or asked people to fill out a GitHub issue with specific information, only to realise they haven't put in any details? Well, gone are those days with the new GitHub Issues.
Now you can create GitHub Issue templates that function as Google-like forms. You can request specific information, add check boxes, and make certain fields required so you get all the details you need.
This is super handy for bug reports, feature requests, and more. Let's take a look at these forms and how to build one.
GitHub Issue forms look and function similar to a standard HTML form, but in an issue. This is a short form I built for users to request demos from me while I'm on a live stream.
You can see I ask the user to select the "type" of demo they'd like to see. This is a drop down that allows me to write the types of demos I can users to choose from. The "More information" section is a text box where users can add more details. You'll see the red asterisk * next to "type" and "More information". This means these fields are required. The user will not be able to submit the issue without filling these out.
Then there's an optional small text box to add user details. Hopefully that makes a little bit of sense. I'm going to create a new GitHub Issue Form and step through how to do this.
If you haven't used Issue templates before, you'll need to create a location for them. All GitHub Issue templates, including GitHub Issue Form templates, live under the
ISSUE_TEMPLATE folder under the
.github folder in your repo. Navigate to the "code" tab under your repo and see if you have the folder
If you don't have this folder, create it. You can do this by clicking "Add file" "Create new file".
Once the screen loads, click where it says "Name your file...":
Type ".github / ISSUE_TEMPLATE /" from your keyboard. You'll notice two new 'folders' has been created and can add a new file:
Name your file. Since this is a GitHub Issue Form, we want to name it something that ends in
*.yml because GitHub Issue Forms are run on yaml files:
You might also notice a blue box appear:
This link will take you to GitHub Docs. It has a a great explanation on how to work with Issue templates. Save this link for later and come back to it if you ever get stuck with issue templates.
You can add a commit message if you like.
Now we have a blank yaml file. Since you have a blank file, you might have a red error box saying there's a problem with the template. Don't worry, because now we're going to build it out.
Click the pencil on the right to "Edit this file".
We need to initialise this template as an issue form. We'll need to add the name of the template. This is also the description that will appear when someone wants to fill out the form. We also need a title which will show when someone opens a blank issue from this template.
Do this by adding the following code:
name: NAME_OF_TEMPLATE description: DESCRIPTION title:
You can also add
labels. These might already have setup in your repo. Add
assignees if you want to assign someone to the form.
My form is going to be for requesting specific tips on a stream, or tips to write in a DEV post. Here's what my issue form currently looks like:
Once you have this part complete you can add all the information to build out the form. Fun fact: the above two steps are the same if you were building a standard issue template.
Now we can add all the fancy features that make this a GitHub Issue Form.
body: with the same indentation as
name: Tip Request description: Request a GitHub Tip from MishManners title: "[Tip]: I want " labels: [Tip, enhancement] assignees: - mishmanners body:
Next, add the various elements you'll want for your Issue form. The types of things you can have in an Issue form include:
markdown: a place where you can write a message or leave information for the person filling out the form. Text such as "thanks for taking the time to fill out this form" is helpful. You need to have more than markdown to make this file an issue form. So you can also add:
input: a small area for users to write text. Useful for short answers
textarea: a field where users can write text. Useful for longer answers
checkboxes: for users to mark off
dropbown: for users to select specific answers
Under each element, you'll need to add some things:
id:name of the element (this is more for your reference and won't show up on the form itself)
attributes, you'll need to add the following:
label: heading for this part of the form
description: short description that will appear under the heading
- Depending on what you chose above for the element, you'll have more options. If this is a
textareayou'll need to add
renderto tell it what kind of textarea it is. If you added
checkboxesyou'll need to provide the
options, and if you used
inputyou can add a
validations: finally, you'll need to add whether this section of the form is
required. This is a boolean, so you'll need to provide either
If you've sorted out what kind of things you want for your form, and added the correct code, your template should look something like this:
name: Tip Request description: Request a GitHub Tip from MishManners title: "[Tip]: I want " labels: [Tip, enhancement] assignees: - mishmanners body: - type: markdown attributes: value: | Thanks for asking Mish for a Tip. Tune into a Live stream or read Mish's articles on DEV for great GitHub tips. - type: input id: Name attributes: label: Name of GitHub Tip description: What is the name of this GitHub Tip? placeholder: ex. GitHub Issue Forms validations: required: true - type: textarea id: info attributes: label: More information description: Add more information on the tip you would like to see. render: shell validations: required: true - type: dropdown id: Level attributes: label: What kind of level is this tip? description: What level of developer do you tthink this tip is aimed at? options: - Beginner - Intermediate - Advanced validations: required: true - type: checkboxes id: location attributes: label: Where do you want this GitHub Tip? description: Where would you like to see this GitHub Tip? You can select more than one. options: - label: Twitch required: false - label: DEV post required: false - label: YouTube video (longer) required: false - label: Twitter video (shorter) required: false
Click "Start commit":
Add a commit message if you like and click "Commit changes". If the code above is working (feel free to copy and paste mine to compare) there shouldn't be any errors when you committed the code. Read more about the types of syntax required for GitHub Issue Forms over on the GitHub Docs. If you have an error 🔴, skip step 4, and jump down to the "HELP 🔴" step.
Your form should now be complete! Now to test it:
- Go to the repository where you made the template
- Click the "Issues" tab
- Click "New Issue"
- Select the issue template you just created.
Mine is called "Tip Request" since this was the I have under
name: in my template file.
Click "Get Started" and your issue form should be displayed.
This is what mine looks like:
You can see all the elements in the form that were added into the file. You can see the red asterisk * next to
Check out this form and match it up to the code aboveabove.
One thing I love about GitHub Issue Forms is that if you get stuck building your template, GitHub is pretty good at helping you. For example, if you commit your code and you forgot to add a certain element, GitHub will give you an error, such as this:
This error means that the forth element in my form (
body) is missing one of its
options. If we go back and compare the code, I can see that the forth element is the
checkboxes at the end of the form and they don't have any options:
All I need to do is add the options like this:
If all this sounds really scary, or you're not sure where to start, or how to fix errors, GitHub can help. When you're creating your template, on the right hand side, you'll see some options to help you:
This handy configuration helper provides information on what needs to be included in the yaml file. There are code snippets to copy and paste and lots of information. It makes building these issue forms much easier and has helpful explanations about all the fields.
As of right now (August 2021), GitHub Issue forms are still in beta.
If you're reading this and issue templates are still in beta, then you might notice a
Beta tag when you were creating the yaml file. Feedback is always super welcome and I promise the GitHub team reads every single piece of feedback and all suggestions.
If you'd like to give feedback on GitHub Issue forms, or any other feature, visit our Discussions Feedback.
How will you be using GitHub issues?