104 - Epic Templates - Repeatable sets of issues

Objective

Often you need to manage a set of consistently repeating events, where multiple issues are used to track the combined activity of a team. This page describes how to utilize GitLab Issue Import and a few spreadsheet tricks to make it possible to create a repeatable set of issues for future projects.

The Issue Import CSV button is at the top of the GitLab project issue list. This feature can be very useful for repeating projects with similar groups of issues / work.

Please read the “Tips and Tricks” section before you import issues into your projects

Assumptions

1. You’re familiar with the GitLab structure of how projects, groups, epics, milestones, issues, and labels work. If not, please review GitLab 101- No Tissues with Issues

2. You’re comfortable working in a spreadsheet and using formulas to concatenate text into a cell. note: In my examples, I use the & operator, which is the same as the concat function.

3. You have Developer permission level or higher in your project. (required to do issue import)

4. Your issues will be created in the same project. You can still do this for cross-project templates, but you will either need to MOVE issues to the destination project (can be automated) or more manually you would need to upload a separate CSV for each individual project. Check out this automation tutorial for how to automate moving an issue from one project to another.

---

Background

1. Issue Import CSV is really simple. It requires only two columns,

   • title
   • description

   Where the issues are in a coma delimited file. The first row is the header and the subsequent rows include the data.

2. Issue Import CSV is really powerful. It allows you to use the /Quick Actions to do cool things to your new issues like:

• add labels
• set due dates
• add to milestones
• add to epics
• set weights
• set effort estimates
• assign issues to individuals
  

note: See the GitLab documentation for Importing issues from CSV

---

Steps

1. Build Issue spreadsheet

Decide what project structure will be for your set of issues. Specifically,

• what labels will be used for the project,
• what epics and sub-epics will be used to track the work, and
• what milestones will you use for this work effort.

If these structures do not already exist in GitLab, configure them now.

1.1 Spreadsheet setup

1. While you only really need two columns, (Title, and Description), I’ve found it’s easier to have several columns so you can keep details separate and manage issues. Configure a spreadsheet with the following columns

First: - Two columns where the BASIC text of the issue title and description go.

• raw title,
• raw description, These two columns is where you will enter the text for the titles and descriptions of your issues.

Second: Two columns where the actual text for the issue title and description are ‘assembled’

• title,
• description These two columns are actually just formulas that combine different cells to make up the Title and Description for your issues.

Third: One or more additional columns to hold issue specific QUICK ACTIONS. In these columns, you can add content such as; epics, estimates, labels, and more can be stored. In the example spreadsheet these columns each contain specific data for each issue: Team Label, Type, Effort, Size, Epic, Milestone, Iteration

When you’re done it will look like this:

Fourth: If you want to have the same Label or the same Quick Action for ALL the issues. A cell at the top of the spreadsheet is a place for common Quick Actions

1.2 Draft your first Issue

1. In the row below the headings
   1.1 - Raw Title - Write the text for the issue title
   1.2 - Raw Description - Using markdown, write the issue description.

   Note: it’s often much easier to work in the Formula bar in google sheets, which makes it easier to enter multi line text in the cell.

   

2. In the Quick Action columns, add the appropriate quick actions to add labels, set efforts, add to milestones or epics. This is where you can customize each issue to be tracked in GitLab.

Note: If you are using automation, you could use a label to promote the issue to be an epic or a label to automate moving the issue to another project, to make it confidential, or whatever you want to do with quick actions. Read this automation tutorial to learn more about how automation can update issues for you.

See this publicly available example import spreadsheet.

2. Import Your Issues

1. Select the title and description cells (including the column headers) and copy the contents.
2. Go to a new empty spreadsheet and paste as values. This will eliminate the formulas, but will keep the actual values.
3. Save the new spreadsheet as a CSV file. The file should only be the two columns title and description
4. Go to your project issue list and click on the Import CSV button:
5. In the dialogue box, click on the file name button and select the CSV file.
6. Click the Import Issues button and wait for the magic to happen.

IMPORTANT - Tips, Tricks, and Hints - READ THIS FIRST

1. Create a separate project to TEST your import file. There is NO WAY TO DELETE ISSUES in GitLab. You can CLOSE issues, but you cannot delete them. So, if you are importing 20 issues and you make a mistake, depending on where your test project is in your GitLab hierarchy, you will need to:

   • Remove all the labels, milestones, epics, etc (labels and epics roll up to higher level groups)
   • Un-assign any issues that were assigned to individuals
   • Close the issues

2. Use a real issue in your GitLab project to write your Quick Action codes. Then, copy and paste the quick actions to your spreadsheet. That way your quick actions will not have typos or errors.

3. The Issue ORDER will be sequential starting at the first row then working to the last. That means your first row in the your spreadsheet will show up LAST in GitLab (when sorted by the default issue created date). However, if you list your spreadsheet in the reverse order, then your last issues will be loaded first. That means they will be OLDER, and therefore listed last in GitLab issue lists.