Safe Push Guide for AI Agents

This guide covers the Safe Push process for pushing changes to the IntelliJ repository.

Overview

Safe Push is a system that ensures code changes pass all required tests before being merged to protected branches (like master). It's powered by Patronus.

Safe Push CLI

The safePush.cmd script in the repository root provides command-line access to Safe Push without needing the IDE.

Basic Usage

# Push current HEAD to master (most common)
./safePush.cmd HEAD:master

# Push specific commit to master
./safePush.cmd <commit-hash>:master

# Push from feature branch to master
./safePush.cmd HEAD:master  # while on feature branch

# Dry run (test without pushing)
./safePush.cmd -dry-run HEAD:master

Options

-autosquash    Automatically squash fixup! commits (default true)
-dry-run       Run tests without push
-emergency     Skip tests and push directly (USE ONLY IN EMERGENCIES)
-verbose       Verbose output
-help          Print help

What Happens During Safe Push

1. Your changes are pushed to a temporary branch
2. Patronus triggers required CI checks (tests, compilation)
3. Tests may retry up to 4 times for flaky failures
4. If all checks pass, changes are merged to the target branch
5. You receive Slack/Space/Email notification of results

Typical Duration

• Successful Safe Push: ~3-5 hours (95th percentile ~4.7 hours)
• Failed Safe Push: ~4-5 hours

Monitoring Progress

After starting a Safe Push you'll receive a Patronus URL like:

https://patronus.labs.jb.gg/robot/<uuid>

Always print this URL back to the user — it is their primary handle for the run (link to share, cancel button, restore-branch button). The <uuid> segment is the robot id.

You can also track the Safe Push directly: check current status, enumerate failing checks, drill into a specific attempt, or babysit a long-running robot until it finishes. All of that is in the [[patronus]] skill — pick it up when the user asks for status or when offering to follow up. It's reasonable to proactively suggest tracking or babysitting once the Safe Push is in flight; the user can say no. The [[patronus]] skill also documents the hand-off to [[teamcity-cli]] when an individual TC build needs deeper inspection.

Cancel and restore-branch actions stay in the browser.

Emergency Push

Use ./safePush.cmd -emergency ONLY for:

• Fixing broken compilation
• Reverting commits that break installers
• Fixing .patronus/config.yaml misconfigurations

DO NOT use Emergency Push for:

• Javadoc typo fixes
• When Safe Push fails due to "unrelated" tests (they're likely related)
• Skipping tests because you're in a hurry
• Pushing large changes that conflict with concurrent pushes

Bazel Tests and Environment Variables

When writing tests that spawn external processes (like bazel.cmd), ensure required environment variables are passed:

// In BUILD.bazel for java_test targets:
env_inherit = [
    "LOCALAPPDATA",      // Windows
    "PROCESSOR_ARCHITECTURE",  // Windows
    "USERPROFILE",       // Windows
    "HOME",              // Unix/macOS - required for bazel cache directory
],

The Bazel sandbox does NOT inherit environment variables by default. Use env_inherit to explicitly pass variables from the host environment to tests.

Troubleshooting

Safe Push stuck or slow

• Check #ij-builds Slack channel for infrastructure issues
• Safe Push duration varies based on infrastructure load

Tests failing that seem unrelated

• Patronus retries tests up to 4 times
• If tests fail all 4 attempts and pass in master, your changes likely caused the failure
• Report suspected infrastructure issues to #ij-qa-watch

Need to debug a failed Safe Push

1. Go to your Safe Push on Patronus
2. Click "commits" to see changes
3. Click "Restore Branch" to recover your changes locally

References

• Safe Push Documentation
• Patronus Manual
• Slack: #patronus-support, #ij-builds, #ij-qa-watch