gitlab-activity-report 0.1.1

Collect GitLab group activity and render static JSON/HTML reports

gitlab-activity-report

Collects GitLab activity for a parent group (and descendants), outputs a JSON report with both by_user and by_project, and writes a fully static HTML viewer.

Install

pip install .

This installs the console executable:

gitlab-activity-report --help

You can also run from source checkout:

./gitlab-activity-report --help

Usage

gitlab-activity-report \
  --group 60207604 \
  --start 2026-W05 \
  --end 2026-W06 \
  --output-json report.json \
  --output-html report.html

Authentication

A GitLab access token is required. Provide it either by environment variable or CLI option.

Environment variable:

export GITLAB_ACCESS_TOKEN="glpat-..."
gitlab-activity-report --group 60207604 --start 2026-W05 --end 2026-W06

CLI option:

gitlab-activity-report --access-token "glpat-..." --group 60207604 --start 2026-W05 --end 2026-W06

Token requirements:

• Role: Reporter
• Scope: read_api

User Mapping File

gitlab-activity-report expects a user mapping file at username_author.json by default (or provide a path with --usermap).

Start from the included example file:

cp username_author.json.example username_author.json

This mapping is used to map git commit author name/email values to GitLab usernames.

Output shape

report.json contains:

• meta: report metadata (generated_at, group_id, date range)
• by_user: activity grouped by user, then project
• by_project: project-centric activity keyed by namespace path/id

Each project entry includes group context:

• group.full_path
• group.path_from_start (subgroup tree path relative to selected start group)
• path_with_namespace relative to the selected base group path

Each activity includes:

• actor
• activity_heading ({actor}: {activity_type} - {body or title})
• activity_type
• title
• timestamps (created_at, updated_at)
• optional detail payloads from GitLab APIs

report.html is standalone and static (no external scripts/styles/requests).

License

MIT. See LICENSE.

Releasing

Release process and CI publishing details are documented in RELEASING.md.