Gitlab Time Tracker

• doesn't really 'track' anything, should be called Time Exporter

Quick start

• Download the latest (Windows/Linux) release (x86_64, but emulation on aarch64 also works fine)

  • Alternatively, build from source: cargo build [--release]

• Provide access: set TOKEN and either PROJECT_ID or GROUP_ID via .env, environment, or CLI args

• See help: ./gitlab_timetracker -h (or cargo run -- -h)

  • Subcommand-specific help: ./gitlab_timetracker [command] -h
  • Global options are specified before the subcommand

Using AsciiDoctor output

• Issue groups/categories should be set in categories.json. A sample is provided (categories.json.example). The format is self explanatory. If this file is missing, issues will not be grouped in adoc
  • A category can have a single issue (this practically renames that issue in the output)
  • duplicate categories/issues will throw an error
• AsciiDoc sections will be generated for all people that have booked time in the chosen time period, but a persons role might have to be updated (all are "Entwickler")
• Update 'X'. Sprint in output, obviously

Subcommands

Command	Description	Default/Notes	Options
times	Display a list of time entries	Default (can be omitted)	--show-url: show the issue URL for each entry (default true) --fix-assignees: Add missing assignees where a non-assigned person booked time (Token must have api permissions)
csv	Export time entries as CSV	Same data and filter support as times	-e/--export <file.csv> Optional. If not specified, output will be written to stdout
adoc	Export time entries in AsciiDoctor format	Same data and filter support as times	-e/--export <file.adoc> Optional. If not specified, output will be written to stdout
issue-graph	Generate a PlantUML (graphviz) graph for the issue selection, including child-of/blocks/relates relations and total time booked per node	Respects issues filters (eg. --milestone), but the total time per issue cannot be filtered (≙ is always total time)	-e/--export <file.adoc> Optional. If not specified, output will be written to stdout --exclude [relates, child, blocks]: do not draw these edges in the graph. Does not affect which issue nodes are displayed. Can be passed multiple times
issues	Display a list of issues with or without time entries	Use this to find issues where tracking time was forgotten

Global Options

Flag	Env	Description	Default/Notes
--token <TOKEN>	TOKEN	Access token for the GitLab instance	Required for HTWK GitLab
--instance <URL>	INSTANCE	GitLab Instance URL	https://gitlab.dit.htwk-leipzig.de
-p, --project-id <PROJECT_ID>	PROJECT_ID	Numerical project ID	Either project or group is required
-g, --group-id <GROUP_ID>	GROUP_ID	Numerical group ID	Either project or group is required
-d, --deduplicate	DEDUPLICATE	Sum up multiple entries from one person for the same issue	Only merges entries when the summary (optional description) matches. Affects Times/CSV/Adoc output; no effect on the issue list
-u, --username <USERNAME>	USERNAME	Filter by user	Gitlab ID without '@' like vorname.nachname, not full name
-t, --tags <TAGS>	TAGS	Filter by issue tag	Can be used multiple times for multiple tags
--tags-any	TAGS_ANY	Use OR when multiple tags are passed	Use this if you want to filter for issues that have any of the tags. Default is AND (all tags have to be present)
-m, --milestone <MILESTONE>	MILESTONE	Filter by milestone
-n, --issue <ISSUE>	ISSUE	Filter for a single issue number	If using -g, multiple issues could be returned (since their issue numbers will be the same). You will never use this option
--since <SINCE>	SINCE	Include time entries created since date/time	YYYY-MM-DD or YYYY-MM-DD HH:MM
--until <UNTIL>	UNTIL	Include time entries created until date/time	YYYY-MM-DD or YYYY-MM-DD HH:MM
--issues-since <ISSUES_SINCE>	ISSUES_SINCE	Include issues created since date/time	YYYY-MM-DD or YYYY-MM-DD HH:MM
--issues-until <ISSUES_UNTIL>	ISSUES_UNTIL	Include issues created until date/time	YYYY-MM-DD or YYYY-MM-DD HH:MM

Examples

• Export all time entries to CSV

  ./gitlab_timetracker csv -e data.csv

  Or to stdout:

  ./gitlab_timetracker csv

• Export times since a date in AsciiDoc table format (issue groups/categories supported)

  ./gitlab_timetracker --since 2025-10-12 adoc -e data.adoc

  Note: issue groups/categories should be set in categories.json.

• For a single GitLab user; merging multiple time entries per issue

  ./gitlab_timetracker -u vorname.nachname -d

• Issues with milestone AND tags, then export to CSV

  ./gitlab_timetracker -m milestone -t tag1 -t 'another tag' csv -e data.csv

• Times for issues with ANY of multiple tags

  ./gitlab_timetracker --tags-any -t tag1 -t tag2

• Times for issue #12

  ./gitlab_timetracker -n 12

• Since a specific date/time

  ./gitlab_timetracker --since 2025-05-30\ 11:00

• Show which issues have (or don’t have) time entries, with filters

  ./gitlab_timetracker --issues-since 2025-05-30 -u vorname.nachname issues

Notes

• When passing date/time with spaces, escape or quote (e.g., --since 2025-05-30\ 11:00).
• times --fix-assignees will not work on archived repos. Also, if adding someone as assignee, but that person is no longer a group member, Gitlab won't return an error but will not add the person (therefore, "fixable" issues will remain)