How to create GitLab issues using the Python GitLab API

GitLab is one of the most widely used project management tools in software development and data science. It’s similar to Jira and similar systems in that it provides a useful Kanban board, so you can create tickets, called issues, and track their progress.

I’ve used various systems like this over the years, but find GitLab to be one of the best. I use it to keep track of my own projects, and also to manage the work of my team. Recently, I needed to come up with a way to automatically generate issues in GitLab, so I could create a backlog of work for my team based on issues that had been detected on our ecommerce sites that needed to be fixed by specific individuals.

The GitLab API lets you create issues, and it’s pretty straightforward to use, but there’s lots of code required, and I needed something neater, so I created a little wrapper in Python to make it quicker and easier to generate GitLab issues from my Python automations. Here’s how to use it.

Install the package

My GitLab Issue Creator package can be installed from my Git repository using a Pip install command. It’s not in PyPi, so you’ll need to use the Git repository URL to install it.

pip3 install git+https://github.com/practical-data-science/gitlab-issue-creator.git

Obtain a GitLab access token

Next, you’ll need to login to your GitLab account and create an access token. You can do this by going to your GitLab account settings, and then selecting “Personal Access Tokens” from your profile page. Now import the gitlab_issue_creator module as gic and use the authenticate() function to authenticate with GitLab, and pass it your GitLab access token.

import gitlab_issue_creator as gic

gl = gic.authenticate('YOUR-PERSONAL-ACCESS-TOKEN')

Create a GitLab issue in Python

Now you’re authenticated, you can create a GitLab issue using the create_issue() function. You’ll need to pass it the GitLab project ID, the title of the issue, and the description of the issue. You’ll probably also want to assign it to a specific assignee, and you may want to add it to a project milestone or give it a specific label.

Annoyingly, GitLab doesn’t let you refer to the project_id, assignee_id, or milestone_id using the name (which would be very convenient). Instead, you need to obtain their IDs from the GitLab API. I’ve created some helpers to allow you to access these.

issue = gic.create_issue(gl,
                         project_id=987654321,
                         title='Housekeeping / Fix URLs returning 404s',
                         description='Please fix the below URLs returning 404s:', 
                         assignee_id=54321,
                         milestone_id=123456,
                         labels=['Content'])

How to find your GitLab project_id

To create a GitLab issue you’ll need to define the project_id. You can get this using the get_owned_projects() function. It returns a list of projects that you own so you can find the project within which you want to assign your issues.

owned_projects = gic.get_owned_projects(gl)

How to find your GitLab assignee_id

Similarly, and annoyingly, you can’t assign an issue using a username and you instead need to provide the assignee_id. You can get this using the get_user_by_username() function. It returns the ID of the user with the specified username.

user = gic.get_user_by_username(gl, 'your-username-here')

How to find your GitLab milestone_id

The get_project_milestones() function returns a list of milestones for a project. You’ll find the names and IDs of milestones in here.

milestones = gic.get_project_milestones(gl, 123456789)

Add an attachment to a GitLab issue

One of the things I wanted to do using my Python automation was generate a list of site issues to fix (such as 404s, pages that don’t contain a high ranking keyword, or pages that have duplicate content), and then attach a CSV file to the GitLab issue. This isn’t so easy to do.

I created a function called upload_file_to_issue_note() to handle this. As the name suggests, you first create your issue and then upload the file to the issue note. It takes the GitLab project ID, the issue object, and the path to the file you want to upload and the name you want to give it.

gic.upload_file_to_issue_note(gl,
                              project_id=987654321,
                              issue=issue,
                              filepath='404s.csv',
                              filename='/data/404s.csv')

Once this is all set up, you’ll be able to run Python automations that generate useful work for your team, assign them to specific individuals, and check that they’re being completed. It’s really useful and saves a lot of time.

Matt Clarke, Tuesday, September 27, 2022