# Dashboard MR Linker

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

---

An AWS Lambda function that posts internal notes on newly opened GitLab merge
requests linking to the Hummingbird dashboard status page. This provides an easy
way for developers to check Konflux build status directly from their MRs.

## Features

- **Internal Notes**: Posts an internal note with dashboard link when MRs are
  opened (visible to project members only)
- **Configurable Projects**: Only monitors specified projects via space-delimited
  list
- **SNS Integration**: Subscribes to GitLab events via SNS with filter policy

## Architecture

The Lambda subscribes to the existing SNS topic (from gitlab-event-forwarder)
with a filter for `merge_request` events:

```text
GitLab Webhook → gitlab-event-forwarder → SNS Topic → dashboard-mr-linker → GitLab API
```

When a new MR is opened on a configured repository, the Lambda posts an internal
note:

```markdown
:robot: **Hummingbird Status**

View Konflux build status for this MR: [org/group/repo!123](https://dashboard.example.com/mr/org/group/repo/123)
```

## Prerequisites

- AWS CLI configured with appropriate credentials (IAM permissions for Lambda,
  SNS, CloudFormation, CloudWatch Logs)
- Podman or Docker (for containerized SAM build/deploy)
- Python 3.11 or later (for development)
- GitLab API token with `api` scope (Reporter role or higher on monitored projects)

## Deployment

Build and deploy using containerized AWS SAM CLI:

```bash
cd dashboard-mr-linker
make build     # Build Lambda package
make deploy    # First deployment (interactive/guided)
make redeploy  # Subsequent deployments (non-interactive)
```

### Parameters

| Parameter          | Description                                  | Default              |
| ------------------ | -------------------------------------------- | -------------------- |
| `ResourcePrefix`   | Prefix for resources                         | `myapp-prod`         |
| `SnsTopicArn`      | SNS topic ARN                                | (required)           |
| `GitLabToken`      | GitLab API token (`api` scope, Reporter+)    | (required)           |
| `GitLabUrl`        | GitLab instance URL                          | `https://gitlab.com` |
| `DashboardBaseUrl` | Base URL of the dashboard                    | (required)           |
| `GitLabProjects`   | Space-delimited list of GitLab project paths | (required)           |
| `SentryDsn`        | Optional Sentry DSN                          | ``                   |

**Resource naming:** Lambda follows `{ResourcePrefix}-lambda-linker` pattern.

**Prerequisites:** Requires an existing SNS topic. Deploy
[hummingbird-events-topic][het-docs] first to create the topic, then use its
ARN for the `SnsTopicArn` parameter.

[het-docs]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/documentation/hummingbird-events-topic.md

## Usage

Configure the `GITLAB_PROJECTS` parameter with space-delimited project paths:

```text
org/group/containers org/group/rpms org/other/project
```

Only MRs opened on these projects will receive dashboard link notes.

## Development

See the main [README][readme] for development workflows.

```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
```

## Configuration

Lambda function receives configuration via environment variables (automatically
set by CloudFormation):

| Variable             | Description                                  |
| -------------------- | -------------------------------------------- |
| `GITLAB_TOKEN`       | GitLab API token (`api` scope, Reporter+)    |
| `GITLAB_URL`         | GitLab instance URL                          |
| `DASHBOARD_BASE_URL` | Base URL of the dashboard                    |
| `GITLAB_PROJECTS`    | Space-delimited list of GitLab project paths |
| `SENTRY_DSN`         | Optional Sentry DSN                          |
| `AWS_REGION`         | AWS region (auto-set)                        |

## Security & Limitations

**Security:**

- GitLab API token should have minimal required scopes (`api`)
- Token stored as CloudFormation parameter with `NoEcho: true`
- SNS subscription uses filter policy to only receive relevant events
- Notes are posted as internal (visible to project members only)
- CloudWatch logs capture all note posts (7-day retention)
- Sentry integration for error tracking

**Limitations:**

- Lambda timeout: 30 seconds
- Lambda memory: 256 MB
- Only processes `action: open` events (not updates or other actions)
- Skips MRs with the `managed-by::workqueue` label (created by
  [workqueue-service](workqueue-service.md)). The workqueue-service
  manages its own dashboard integration for these MRs, so the Lambda
  backs off to avoid duplicate notes

## Integration

The workqueue-service creates the dashboard note itself for MRs it
manages. The `managed-by::workqueue` scoped label, applied by the
`create_mr` executor, causes this Lambda to skip those MRs. The
workqueue-service's `ensure_dashboard_note` executor then posts the
note and stores the `dashboard_link` dimension with the note ID.

For non-managed MRs (those not created by the workqueue-service), the
Lambda remains the sole creator of the dashboard note.

Both systems use the same marker in the note body:
`:robot: **Hummingbird Status**`. The Lambda's `COMMENT_MARKER` and
the workqueue-service's `DASHBOARD_LINK_MARKER` constant must stay in
sync — changing one without the other will break identification and
may cause issues with future reconciliation or status rendering.

## License

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

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