Perforce
Learn more about Sentry's Perforce integration and how it can track and resolve bugs faster by using data from your Perforce changelists.
Sentry's Perforce integration connects your P4 Server to Sentry, enabling stack trace linking, commit tracking, and suspect commit detection for teams using Perforce P4 (formerly Helix Core) for version control.
The Perforce integration supports the following features:
Before installing, make sure you have:
- Sentry permissions: Organization owner, manager, or admin role.
- Perforce server access: A Perforce user account with read access to the depots you want to connect. We recommend creating a dedicated service account (e.g.,
sentry-bot). - SSL fingerprint (if using SSL): Obtain it by running
p4 -p ssl:<host>:<port> trust -yon a machine with access to your Perforce server. - Network connectivity: The Sentry application must be able to reach your Perforce server over the network on the configured port. Make sure the IP addresses Sentry uses to make outbound requests are allowed by your firewall or network configuration.
Note
We recommend creating a dedicated service account on your Perforce server for this integration rather than using a personal user account. This ensures access isn't disrupted when team members leave and keeps changelist attribution consistent.
In sentry.io, navigate to Settings > Integrations > Perforce and click "Add Installation".
Fill out the configuration form with your Perforce server details:
Sentry will verify the connection to your Perforce server. If the connection is successful, the integration will be installed and enabled for all projects in your organization.
Sentry supports two authentication methods:
- Password: Sentry sends your password to the Perforce server's
p4 logincommand to obtain a session ticket. This is the simplest setup. - P4 Ticket: Use a pre-generated ticket from
p4 login -p. This avoids sending the password and is useful when your Perforce server uses external authentication (LDAP, etc.).
After installing, you'll need to configure features like commit tracking and stack trace linking for your projects.
Commit tracking allows Sentry to associate Perforce changelists with your releases. This enables suspect commit detection and helps your team pinpoint which changelist introduced an issue.
For more details, see the full documentation on commit tracking and releases.
Once commit tracking is configured, the author of the suspect changelist will be listed as a suggested assignee for the issue. Click on their icon to assign the issue.
When an error occurs, Sentry automatically queries your Perforce server to find the most recent changelist that modified the file where the error originated. This changelist is shown as a suspect commit on the issue details page, along with:
- Changelist number (displayed as the commit ID)
- Author name and email (from the Perforce user record)
- Changelist description (commit message)
- Timestamp
Stack trace linking takes you from a file in your Sentry stack trace to that same file in your source code. If you have commit tracking set up, Sentry links to the exact revision of the file. Otherwise, it links to the current state.
If you have a P4 Code Review (Swarm) URL configured, links will open in the Swarm web viewer. Otherwise, Sentry uses p4:// protocol URLs.
To set up stack trace linking, add a code mapping for each Sentry project and Perforce depot you want to link. For Perforce, Branch is the stream name. It's optional, because streams are part of the depot path.
Perforce Example
If the stack trace shows src/main.cpp and the depot path is //depot/project/src/main.cpp, set Stack trace prefix to src/ and Repository prefix to project/src/. Sentry then replaces src/ with project/src/ when it looks up files in your depot.
If your events don't carry inline source context (for example, native crashes or releases built without source maps), you can have Sentry fetch the surrounding lines from your Perforce depot on demand and render them in the issue stack trace. See SCM Source Context for setup and access details.
You can update your Perforce server credentials and settings at any time by navigating to Settings > Integrations > Perforce > Configurations and clicking the gear icon next to your instance. Changes take effect immediately.
Each Sentry organization gets its own private Perforce integration instance. Credentials are isolated per organization, even if multiple organizations connect to the same Perforce server.
Sentry connects to your Perforce server using the P4Python library and executes standard P4 commands (p4 depots, p4 files, p4 changes, p4 user) to retrieve data.
When you add a repository, Sentry queries your Perforce server for all accessible depots using p4 depots. You can then select which depots to associate with your Sentry projects.
For suspect commit detection, Sentry uses p4 changes -m 1 -l <file> to find the most recent changelist that modified each file in a stack trace. This is a lightweight query that doesn't require fetching full file history.
The following features are not supported by the Perforce integration:
- Pull request comments: Perforce does not have native pull requests.
- Issue management: Creating or linking Perforce issues from Sentry is not supported.
- Resolve via commit: Automatic issue resolution via commit messages is not supported.
- CODEOWNERS: Importing CODEOWNERS files from Perforce is not supported.
- Line-level blame: Suspect commits are detected at the file level, not per line.
If you see "Failed to connect to Perforce server", verify:
- Your P4PORT address is correct and reachable from Sentry's network.
- The IP addresses Sentry uses to make outbound requests are allowed by your firewall or network configuration.
- If using SSL, ensure the SSL fingerprint is correct. Re-obtain it with:
p4 -p ssl:<host>:<port> trust -y - Your firewall allows inbound connections on the Perforce port (typically 1666).
If you see "Authentication failed":
- Password auth: Verify the username and password are correct.
- Ticket auth: Tickets expire. Generate a new one with
p4 login -pand update the integration configuration.
If a depot doesn't appear when adding a repository, verify that the service account has read access to that depot on the Perforce server.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").