# Perforce Helix Core (Beta)

> Review shelved Perforce Helix Core changes in Helix Swarm with MergeHarbor (Beta), mapping depot paths and streams to repositories for codebase context.

MergeHarbor reviews **Perforce Helix Core** changes through **Helix Swarm**. It reads the shelved files of a Swarm review, posts a summary and inline comments on the review, and reports its result on a Swarm test. This integration is in **Beta**.

## Requirements

- Helix Swarm with REST API v9 or later. Votes, test results and the review file list need API v10 or later. MergeHarbor detects the newest version your Swarm supports (up to v11) when you connect.
- A Helix user for MergeHarbor with read access to the depot paths you map, and permission to comment and vote in Swarm.
- A long-lived ticket for that user (`p4 login -a -p`) or its password.

## Connect

1. In the console, open **Integrations → Code hosts** and choose **Perforce Helix Core (Swarm)**.
2. Enter the Swarm URL, the Helix user, and the ticket or password. The ticket is encrypted at rest and never shown again.
3. Add the depot paths or streams to review, such as `//depot/main/...` or `//streams/main`. Each one becomes a repository in MergeHarbor.
4. After connecting, the console shows the webhook URL and a POST body with a secret. Keep the secret private.
5. Choose the repositories to review in **Repositories**, as with any other code host.

You can change the mappings and options later with **Configure** on the connection.

### Mapping options

| Field                             | Purpose                                                                                                                                      |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Path                              | Depot path or stream root. Reviews of shelved files under it belong to this repository.                                                      |
| Name                              | Name shown in MergeHarbor (default: the path without `//`).                                                                                  |
| Git Fusion repository, Git branch | The Git Fusion or Helix4Git repository and branch that mirror the path (see below).                                                          |
| Swarm project, Swarm branch       | Route Swarm deliveries for that project and branch to this repository. Without them, MergeHarbor uses the depot paths of the review's files. |

## Notify MergeHarbor from Swarm

Swarm calls MergeHarbor through a test. In Swarm, add a test (**Workflow → Tests**, or the project's automated tests on older Swarm versions) that runs when a review is updated:

- **URL**: `https://<your MergeHarbor host>/webhooks/perforce?c=<connection id>` (shown in the console).
- **Method**: POST, body as JSON:

```json
{
  "review": "{review}",
  "version": "{version}",
  "change": "{change}",
  "status": "{status}",
  "project": "{project}",
  "branch": "{branch}",
  "testRunId": "{testRunId}",
  "token": "<webhook secret>"
}
```

You can send the secret in an `X-MergeHarbor-Token` header instead of the `token` field. MergeHarbor rejects deliveries without the right secret.

Name the test `mergeharbor` (or the name you set under **Swarm test name**) so MergeHarbor can mark its run as passed or failed. A test that runs on submit, with `{change}` and no review, refreshes the index of a Git Fusion repository.

## How reviews work

A Swarm review is a shelved changelist. For each review version MergeHarbor reads the shelved files and the revisions they were opened at, and builds the change as two git commits on its own server. The diff it reviews is exactly the shelf's change, even if the branch moved on since.

Shelved files are read through Swarm's file downloads. If your Swarm does not allow downloads with the MergeHarbor user's credentials, set **P4PORT** (and, for `ssl:` servers, the server fingerprint) so MergeHarbor reads them with the `p4` client. The `p4` client must be installed on your MergeHarbor workers; MergeHarbor never trusts an unknown SSL fingerprint.

Limits per review: up to 1,000 files, 4 MB per file and 64 MB in total. Files over these limits are left out of the review.

## Codebase context

- **With Git Fusion or Helix4Git**: set the Git Fusion URL and, per mapping, the git repository and branch. MergeHarbor mirrors and indexes the repository, so reviews use your whole codebase: search, symbols, callers and history.
- **Without Git Fusion**: reviews work, but MergeHarbor sees only the files the change touches. The repository shows as empty in the index. There is no direct `p4` to git sync.

## What is posted

- One summary comment on the review, and inline comments on the right-hand side of changed lines.
- The result on the MergeHarbor test run (Swarm API v10 and later).
- With **auto-approve**, an up vote on reviews that pass. With **Vote down reviews that fail the gate**, a down vote that is cleared when a later review passes.
- Likes on MergeHarbor's comments count as positive feedback. Swarm has no dislike, so use the console to rate comments.

## Not supported yet

- Replies to `@mergeharbor` mentions (Swarm does not send comment events to tests).
- Updating the review description, merging or closing reviews from the console, and fix pull requests.
- Incremental reviews: each new version is reviewed in full.