Latchpoint for Perforce

Setup guide

Perforce Helix Core changelists, shown on the Jira issues they belong to.

A developer submits a changelist with a Jira issue key in the description. Moments later that issue's development panel shows the changelist — author, description, file count. No one has to link anything by hand.

Your depot credentials never leave your network. Latchpoint does not connect to your Perforce server. Your server posts outbound to Jira over HTTPS, authenticated with a secret only you hold. Works with on-premises, cloud and hybrid deployments.

Setup

Install Latchpoint for Perforce from the Atlassian Marketplace.
In Jira, go to Settings → Apps → Marketplace apps, then choose Latchpoint for Perforce under Apps in the left sidebar. Copy your endpoint URL and secret.
Put the trigger script on your Perforce server (below).
Set the environment variables for the account running p4d.
Register the trigger with p4 triggers.

Environment variables

LATCHPOINT_URL=<endpoint URL from the Jira admin page>
LATCHPOINT_SECRET=<secret from the Jira admin page>
LATCHPOINT_DEPOT=depot                          # optional, label shown in Jira
LATCHPOINT_SWARM_URL=https://swarm.example.com  # optional, see below

With LATCHPOINT_SWARM_URL set, each changelist shown in Jira links straight to its Swarm page. Without it, changelists link to this documentation instead — everything else works the same.

Linux and macOS servers

Save as /p4/latchpoint-trigger.sh, then chmod +x. Run p4 triggers and add:

latchpoint change-commit //... "/p4/latchpoint-trigger.sh %change% %user%"

Download latchpoint-trigger.sh

Windows servers

Save as C:\p4\latchpoint-trigger.ps1. Run p4 triggers and add:

latchpoint change-commit //... "powershell -NoProfile -ExecutionPolicy Bypass -File C:\p4\latchpoint-trigger.ps1 %change% %user%"

Download latchpoint-trigger.ps1

Use that line exactly as written. Windows Server defaults to the RemoteSigned execution policy, which refuses to run any script downloaded from the internet. Without -ExecutionPolicy Bypass, PowerShell exits before the script starts and Perforce treats that as a failed trigger. If you would rather not pass Bypass, review the script and run Unblock-File C:\p4\latchpoint-trigger.ps1 once instead.

How issues are matched

Any Jira issue key in the changelist description is matched, for example GAME-412 fix collision on ramp geometry. Multiple keys in one description all receive the changelist. Changelists without a key are ignored — the script exits before making any network call.

The whole description is read, not just its first line. Perforce's usual shape is a summary, a blank line, then detail, and a key anywhere in it counts — including in the body.

Importing your existing history

The trigger only ever sees new changelists. Until someone submits, the development panel stays empty. If you would rather see your existing history straight away, run the backfill script once — it walks the changelists you already have and publishes the ones that mention a Jira issue.

latchpoint-backfill.sh latchpoint-backfill.ps1

It uses the same two environment variables as the trigger. Look before you leap:

# Linux / macOS
./latchpoint-backfill.sh --max 2000 --dry-run   # prints what it would send
./latchpoint-backfill.sh --max 2000             # sends it

# Windows
.\latchpoint-backfill.ps1 -Max 2000 -DryRun
.\latchpoint-backfill.ps1 -Max 2000

Option	Meaning
`--max N` · `-Max`	Consider the N most recent changelists. Default 1000.
`--since N` · `-Since`	Only changelists newer than N. Use to resume, or to import a slice.
`--path SPEC` · `-Path`	Depot path to walk. Narrow it to one stream or project. Default `//...`
`--batch N` · `-BatchSize`	Changelists per request. Default 200, which is the maximum.
`--delay N` · `-Delay`	Seconds between batches. Default 10. Leave this alone — see below.
`--dry-run` · `-DryRun`	Print what would be sent and send nothing.

Safe to re-run. Development information is keyed by changelist number, so a second run updates the same entries rather than creating duplicates. If a batch fails, re-run the whole thing.

Why the delay between batches matters. Jira's development-information API is asynchronous, and it accepts an update before storing it. Sending several batches to the same depot within a second or so loses the earlier ones — every request still reports success, and the commits are simply absent afterwards. We found this by reading the stored data back rather than trusting the response, and the default spacing exists to prevent it. Setting the delay to zero on a large import will silently lose changelists.

Large histories take a while: the script reads each changelist individually, so a few thousand is minutes rather than seconds. It prints progress as it goes, and it is not running on your submit path, so nothing is at risk while it works.

Safety

Concern	Behaviour
Latchpoint unreachable	The trigger logs a line and exits 0. Submits are never blocked.
Depot credentials	Never transmitted. The script reads changelist metadata locally via `p4 -ztag describe -s`.
File contents and paths	Never transmitted. Only changelist number, description, author, timestamp and file count.
Secret compromised	Rotate it on the Jira admin page and update the server variable.
Outbound access	HTTPS to `*.atlassian.app` on 443. No inbound access to your network.

Troubleshooting

Nothing appears in Jira. Check the description contains an issue key that exists in that Jira site. Test the trigger by hand — /p4/latchpoint-trigger.sh 12345 alice — it prints what it did.

"Invalid or missing X-Latchpoint-Secret". LATCHPOINT_SECRET doesn't match the admin page. Note that the p4d service account has its own environment.

"Not configured". Open the admin page in Jira once to generate the secret.

Can't find the admin page. It is under Settings → Apps → Marketplace apps, listed beneath Apps in the left sidebar. It is not under "Manage apps", which handles installation rather than configuration.

Windows: "cannot be loaded because running scripts is disabled" or "is not digitally signed". The p4 triggers line is missing -ExecutionPolicy Bypass. See the Windows section above.