Gitlab

You can import tasks from your Gitlab instance using the gitlab service name.

Example Service

Here’s an example of a Gitlab target:

ini

[my_issue_tracker]
service = gitlab
gitlab.login = ralphbean
gitlab.token = OMG_LULZ
gitlab.host = gitlab.com

toml

[my_issue_tracker]
service = "gitlab"
login = "ralphbean"
token = "OMG_LULZ"
host = "gitlab.com"

The above example is the minimum required to import issues from Gitlab. You can also feel free to use any of the configuration options described in Common Service Configuration Options or described in Service Features below.

The token is your private API token.

Service Features

Include and Exclude Certain Repositories

If you happen to be working with a large number of projects, you may want to pull issues from only a subset of your repositories. To do that, you can use the include_repos option.

For example, if you would like to only pull-in issues from your own project_foo and team bar’s project_fox repositories, you could add this line to your service configuration (replacing me by your own login):

ini

gitlab.include_repos = me/project_foo, bar/project_fox

toml

include_repos = ["me/project_foo", "bar/project_fox"]

Alternatively, if you have a particularly noisy repository, you can instead choose to import all issues excepting it using the exclude_repos configuration option.

In this example, noisy/repository is the repository you would not like issues created for:

ini

gitlab.exclude_repos = noisy/repository

toml

exclude_repos = ["noisy/repository"]

Hint

If you omit the repository’s namespace, bugwarrior will automatically add your login as namespace. E.g. the following are equivalent:

ini

gitlab.login = foo
gitlab.include_repos = bar

toml

login = "foo"
include_repos = ["bar"]

and:

ini

gitlab.login = foo
gitlab.include_repos = foo/bar

toml

login = "foo"
include_repos = ["foo/bar"]

Alternatively, you can use project IDs instead of names by prefixing the project id with id::

ini

gitlab.include_repos = id:1234,id:3141

toml

include_repos = ["id:1234", "id:3141"]

Filtering Repositories with Regular Expressions

If you don’t want to list every single repository you want to include or exclude, you can additionally use the options include_regex and exclude_regex and specify a regular expression (suitable for Python’s re module). No default namespace is applied here, the regular expressions are matched to the full repository name with its namespace.

The regular expressions can be used in addition to the lists explained above. So if a repository is not included in include_repos, it can still be included by include_regex, and vice versa; and likewise for exclude_repos and exclude_regex.

Note

If a repository matches both the inclusion and the exclusion options, the exclusion takes precedence.

For example, you want to include only the repositories foo/node and bar/node as well as all repositories in the namespace foo starting with ep_, but not foo/ep_example:

ini

gitlab.include_repos = foo/node, bar/node
gitlab.include_regex = foo/ep_.*
gitlab.exclude_repos = foo/ep_example

toml

include_repos = ["foo/node", "bar/node"]
include_regex = "foo/ep_.*"
exclude_repos = ["foo/ep_example"]

Filtering Membership

If you want to filter repositories that you have a membership:

ini

gitlab.membership = True

toml

membership = true

Filtering Owned

If you want to filter repositories that you own:

ini

gitlab.owned = True

toml

owned = true

Import Labels as Tags

The gitlab issue tracker allows you to attach labels to issues; to use those labels as tags, you can use the import_labels_as_tags option:

ini

gitlab.import_labels_as_tags = True

toml

import_labels_as_tags = true

Also, if you would like to control how these labels are created, you can specify a template used for converting the gitlab label into a Taskwarrior tag.

For example, to prefix all incoming labels with the string ‘gitlab’ (perhaps to differentiate them from any existing tags you might have), you could add the following configuration option:

ini

gitlab.label_template = gitlab_{{label}}

toml

label_template = "gitlab_{{label}}"

In addition to the context variable {{label}}, you also have access to all fields on the Taskwarrior task if needed:

Note

See Field Templates for more details regarding how templates are processed.

Include Issues

Issues are included by default, if not configured otherwise. To disable querying of issues, set:

ini

gitlab.include_issues = False

toml

include_issues = false

Include Merge Requests

Merge requests are included by default. You can exclude them by disabling this feature:

ini

gitlab.include_merge_requests = False

toml

include_merge_requests = false

Include Todo Items

By default todo items are not included. You may include them by adding the following configuration option:

ini

gitlab.include_todos = True

toml

include_todos = true

If todo items are included, by default, todo items for all projects are included. To apply the same repository filters to todos as to issues and merge requests, you may set:

ini

gitlab.include_all_todos = False

toml

include_all_todos = false

Include Only One Author

If you would like to only pull issues and MRs that you’ve authored, you may set:

ini

gitlab.only_if_author = myusername

toml

only_if_author = "myusername"

Priority by type

If you would like that your issues have a different default priority than your MRs or todo items, you can configure individual priorities for each:

ini

gitlab.default_issue_priority = M
gitlab.default_todo_priority = M
gitlab.default_mr_priority = H

toml

default_issue_priority = "M"
default_todo_priority = "M"
default_mr_priority = "H"

Custom query strings

The Gitlab REST API allows many more configuration options than the ones provided by the options explained above. If you want to further customize calls, you can set for example:

ini

gitlab.issue_query = issues?search=foo&in=title
gitlab.merge_request_query = merge_requests?state=opened&scope=all&reviewer_username=myusername
gitlab.todo_query = todos?state=pending&action=directly_addressed

toml

issue_query = "issues?search=foo&in=title"
merge_request_query = "merge_requests?state=opened&scope=all&reviewer_username=myusername"
todo_query = "todos?state=pending&action=directly_addressed"

These can be combined with the other configuration options above, but queries are only evaluated if the respective category (issue, merge_request, todo) is enabled.

Note: Depending in the scope you are interested in, this query-based approach can be much faster than using the “default queries”. For example, imagine that you want to query all issues assigned to your user.

This can be achieved by leaving the include_repos configuration value empty and setting only_if_assigned to True. This will result in querying all repos your user has access to, which might take a very long time.

Alternatively, you could set issue_query = issues?assignee_username=myusername&state=opened&scope=all, which will fetch the assigned issues first and then only fetch the projects for which issues have been found.

Use HTTP

If your Gitlab instance is only available over HTTP, set:

ini

gitlab.use_https = False

toml

use_https = false

Do Not Verify SSL Certificate

If you want to ignore verifying the SSL certificate, set:

ini

gitlab.verify_ssl = False

toml

verify_ssl = false

Including Project Owner in Project Name

By default the taskwarrior project name will not include the owner. To do so set:

ini

gitlab.project_owner_prefix = True

toml

project_owner_prefix = true

Synchronizing Issue Content

This service synchronizes most Gitlab fields to UDAs, as described below.

To limit the amount of content synchronized into TaskWarrior (which can help to avoid issues with synchronization), use

• body_length=0 to disable synchronizing the Gitlab Description UDA (or set it to a small value to limit size).

Provided UDA Fields

Field Name	Description	Type
gitlabassignee	Gitlab Assignee	Text (string)
gitlabauthor	Gitlab Author	Text (string)
gitlabcreatedon	Gitlab Created	Date & Time (date)
gitlabdescription	Gitlab Description	Text (string)
gitlabdownvotes	Gitlab Downvotes	Number (numeric)
gitlabduedate	Gitlab Due Date	Date & Time (date)
gitlabmilestone	Gitlab Milestone	Text (string)
gitlabnamespace	Gitlab Namespace	Text (string)
gitlabnumber	Gitlab Issue/MR #	Text (string)
gitlabrepo	Gitlab Repo Slug	Text (string)
gitlabstate	Gitlab Issue/MR State	Text (string)
gitlabtitle	Gitlab Title	Text (string)
gitlabtype	Gitlab Type	Text (string)
gitlabupdatedat	Gitlab Updated	Date & Time (date)
gitlabupvotes	Gitlab Upvotes	Number (numeric)
gitlaburl	Gitlab URL	Text (string)
gitlabweight	Gitlab Weight	Number (numeric)
gitlabwip	Gitlab MR Work-In-Progress Flag	Number (numeric)