# Hummingbird MR Collaboration

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

---

How to open merge requests and help on someone else's MR in the
`redhat/hummingbird/tools` monorepo. Applies to all components (including
`redhat-catalog/`).

## Features

- **Same-repo branches** — contributors work in the shared GitLab project, not
  personal forks for day-to-day changes
- **One MR per change** — seniors push fixes to the author's source branch
  instead of opening a nested MR
- **Automatic CI** — each push to the MR branch re-runs the pipeline, GitLab
  Pages preview, and dashboard status links

## Prerequisites

- GitLab account with **Developer** (or higher) access on
  `redhat/hummingbird/tools`
- Git clone of the monorepo
- Optional: [glab](https://gitlab.com/gitlab-org/cli) CLI authenticated to
  GitLab

## Git remotes

Many developers use two remotes:

| Remote     | Typical URL                                   | Use for                            |
|------------|-----------------------------------------------|------------------------------------|
| `upstream` | `git@gitlab.com:redhat/hummingbird/tools.git` | Fetch MRs, push to shared branches |
| `origin`   | Personal fork (if configured)                 | Optional; not used for team MRs    |

Add `upstream` if missing:

```bash
git remote add upstream git@gitlab.com:redhat/hummingbird/tools.git
git fetch upstream
```

> **Do not open fork MRs** for routine team work. [mr-auto-approver](mr-auto-approver.md)
> unconditionally rejects MRs where `source_project_id != target_project_id`.

## Open an MR (author)

```bash
git clone git@gitlab.com:redhat/hummingbird/tools.git
cd tools
git checkout -b hum-XXXX-short-description
# edit, commit
git push -u upstream hum-XXXX-short-description
```

Open an MR targeting `main` in the GitLab UI.

Branch naming: prefer `hum-XXXX-*` or a descriptive `feat/*`, `fix/*`, or
`experiment/*` prefix (see [Environment Promotion](redhat-catalog-environments.md)
for `experiment/*` deploy behavior).

## Help on someone else's MR (reviewer)

Use the MR **source branch name** from the GitLab MR page (not necessarily your
local checkout name).

### 1. Check out the MR locally

**Option A — fetch by MR number** (works without glab):

```bash
git fetch upstream merge-requests/<IID>/head:mr-<IID>
git checkout mr-<IID>
```

**Option B — checkout the source branch**:

```bash
git fetch upstream <source-branch>
git checkout -B <source-branch> upstream/<source-branch>
```

**Option C — glab**:

```bash
glab mr checkout <IID> --repo redhat/hummingbird/tools
```

### 2. Edit and verify locally

Component-specific checks (example for Red Hat Catalog):

```bash
cd redhat-catalog
npm run ci-checks
npm run start:dev   # optional UI smoke test
```

### 3. Push to the author's branch

If your **local branch name matches** the MR source branch:

```bash
git push upstream <source-branch>
```

If you checked out via `mr-<IID>` (local name differs from remote), push
explicitly:

```bash
git push upstream HEAD:<source-branch>
```

Example: local branch `mr-748`, remote source branch `feat/image-request-form`:

```bash
git push upstream HEAD:feat/image-request-form
```

Optional — rename locally so future pushes are simpler:

```bash
git branch -m mr-<IID> <source-branch>
git push -u upstream <source-branch>
```

The existing MR updates; CI re-runs; no second MR is needed.

## What runs on each MR push

For `redhat-catalog/**` changes, see
[Red Hat Catalog Environment Promotion — Pipeline Flow](redhat-catalog-environments.md#pipeline-flow).
Summary:

| Stage   | Result                                                                 |
|---------|------------------------------------------------------------------------|
| Test    | Build, lint, type-check, unit tests, audit, SAST                       |
| Visual  | Mock visual diff (MR head vs merge-base)                               |
| Preview | GitLab Pages at `/mr-{IID}`                                            |
| Status  | Internal MR note with Hummingbird dashboard link                       |
| Agent   | Code review on open/update; `/hummingbird analyze-failures` on CI fail |

After merge to `main`, staging deploys automatically; production requires manual
gate and UAT sign-off.

## Troubleshooting

### `error: src refspec <branch> does not match any`

Git has no **local** branch with that name. You are probably on `mr-<IID>` while
pushing `git push upstream feat/...`.

**Fix:** push the current branch to the remote source branch:

```bash
git push upstream HEAD:<source-branch>
```

### Push rejected / permission denied

- Confirm **Developer+** access on `redhat/hummingbird/tools`
- Confirm you are pushing to `upstream`, not a personal fork
- Check whether the MR author enabled "Prevent pushing to source branch" (uncommon)

### `fatal: couldn't find remote ref merge-requests/.../head`

Fetch from `upstream`, not `origin`:

```bash
git fetch upstream merge-requests/<IID>/head:mr-<IID>
```

## Team tips

| Tip                                          | Why                                  |
|----------------------------------------------|--------------------------------------|
| Assign yourself when taking over pushes      | Clear ownership on the MR            |
| Use MR Pages preview                         | Review UI without local dev          |
| Use dashboard link in MR internal note       | Per-commit Konflux/build status      |
| Use GitLab suggestions                       | Small fixes without a local checkout |
| Use `experiment/<name>` for long exploration | Live host before opening an MR       |

## Related documentation

- [Red Hat Catalog Environment Promotion](redhat-catalog-environments.md)
- [MR Auto-Approver](mr-auto-approver.md) — fork rejection and approval rules
- [Hummingbird Dashboard — Merge Requests](hummingbird-dashboard.md#merge-requests)
- [Hummingbird Agent](hummingbird-agent.md) — `/hummingbird` MR commands