# Hummingbird MR Human Tracker

LLMS index: [llms.txt](https://hummingbird-project.io/llms.txt) | Full content: [llms-full.txt](https://hummingbird-project.io/llms-full.txt)

---

A CLI tool that detects human intervention on automation-opened GitLab merge
requests (Renovate, Dependabot, etc.) and links them to a per-sprint Jira epic
for tracking.

## Features

- **Bot MR Detection**: Identifies MRs authored by bot accounts across
  multiple GitLab projects using configurable username patterns
- **Human Activity Detection**: Finds MRs where humans have commented or
  pushed commits (via GitLab system notes)
- **Per-Sprint Jira Epic**: Automatically finds or creates an epic per sprint
  to track automation fix work (e.g. "Automation MR fixes for sprint Hum S16")
- **Remote Link Tracking**: Adds affected MR URLs as remote links on the Jira
  epic, with deduplication to avoid duplicates on repeated runs
- **Merged/Closed MR Scanning**: `--since` flag catches MRs that were
  merged or closed before the next scheduled run
- **Dry Run**: Preview what would be linked without making any changes

## Prerequisites

- Python 3.11 or later
- GitLab API token with read access to target projects (including MR notes)
- Jira API token with permission to create epics and remote links in the HUM
  project

## Installation

```bash
pip install -e hummingbird-mr-human-tracker
```

## Usage

```bash
mr-human-tracker --jira-user user@redhat.com --dry-run -v
```

### Common invocations

```bash
# Preview what would be linked (no changes made)
mr-human-tracker --jira-user user@redhat.com --dry-run -v

# Run for real, including MRs merged in the last 2 days
mr-human-tracker --jira-user user@redhat.com --since 2d

# Scan only specific projects
mr-human-tracker --jira-user user@redhat.com --projects redhat/hummingbird/tools

# Verbose output for debugging
mr-human-tracker --jira-user user@redhat.com --since 1w -v
```

### Output

On completion, the tool prints a summary of linked MRs:

```text
INFO hummingbird_mr_human_tracker.tracker: Active sprint: Hum S16 [June 11 - June 25] (id=68851)
INFO hummingbird_mr_human_tracker.tracker: Using epic HUM-2602
INFO hummingbird_mr_human_tracker.tracker: Linked 2 MR(s) to HUM-2602:
INFO hummingbird_mr_human_tracker.tracker:   https://gitlab.com/redhat/hummingbird/rpms/-/merge_requests/2395
INFO hummingbird_mr_human_tracker.tracker:   https://gitlab.com/redhat/hummingbird/containers/-/merge_requests/8476
```

## Configuration

All configuration is via CLI arguments and environment variables.

### CLI arguments

| Argument          | Description                                        | Default                    |
|-------------------|----------------------------------------------------|----------------------------|
| `--gitlab-url`    | GitLab instance URL                                | `GITLAB_URL` env           |
| `--gitlab-token`  | GitLab private token                               | `GITLAB_TOKEN` env         |
| `--jira-url`      | Jira base URL                                      | `JIRA_URL` env             |
| `--jira-token`    | Jira API token                                     | `JIRA_TOKEN` env           |
| `--jira-user`     | Jira email for Basic auth (omit for Bearer)        | None                       |
| `--projects`      | GitLab project paths to scan                       | tools, rpms, containers    |
| `--board-id`      | Jira board ID for sprint lookup                    | `1489`                     |
| `--sprint-prefix` | Sprint name prefix to match                        | `Hum S`                    |
| `--since`         | Also scan merged/closed MRs updated within window  | None (open MRs only)       |
| `--dry-run`       | Report without making changes                      | False                      |
| `-v, --verbose`   | Enable debug logging                               | False                      |

### Environment variables

| Variable       | Description                    |
|----------------|--------------------------------|
| `GITLAB_URL`   | GitLab instance URL            |
| `GITLAB_TOKEN` | GitLab private token           |
| `JIRA_URL`     | Jira base URL                  |
| `JIRA_TOKEN`   | Jira API token                 |

### Duration format for `--since`

The `--since` flag accepts a number followed by a unit:

| Unit | Meaning |
|------|---------|
| `h`  | Hours   |
| `d`  | Days    |
| `w`  | Weeks   |

Examples: `12h`, `2d`, `1w`

## How it works

1. **Fetch active sprint** from the Jira Agile API (board 1489, prefix
   "Hum S")
2. **Find or create** a Jira epic named "Automation MR fixes for sprint
   {sprint_name}" in the HUM project, assigned to the active sprint
3. **Scan GitLab projects** for open MRs authored by bot accounts; if
   `--since` is set, also scan recently merged/closed MRs
4. **Detect human activity** on each bot MR by checking:
   - Non-bot, non-system comments
   - System notes indicating a human pushed commits ("added N commit")
   - Reopen events by non-bot users
5. **Add remote links** on the Jira epic for each human-touched MR (skipping
   URLs already linked)

### Bot detection

A username is considered a bot if it matches any of:

- Contains `bot_` or `bot-` (e.g. `renovate_bot`)
- Ends with `_bot` (e.g. `some_bot`)
- Ends with `[bot]` (e.g. `renovate[bot]`, `dependabot[bot]`)
- Starts with `project_<digits>_bot` or `group_<digits>_bot` (GitLab service
  accounts)

## Development

```bash
make setup     # Install dependencies
make check     # Lint code (ruff)
make fmt       # Format code
make test      # Run unit tests
make coverage  # Run tests with coverage
```

## License

This project is licensed under the GNU General Public License v3.0 or later -
see the [LICENSE][license] file for details.

[license]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/LICENSE