Security Best Practices for Running Open‑Code‑Review: A Complete Deployment Guide

Always run the latest release, isolate LLM credentials in environment variables, verify binary signatures, and rely on OCR’s built‑in sanitizeReason redaction to prevent secret leakage in CI pipelines.

Open‑Code‑Review (OCR) by Alibaba is designed with a defense‑in‑depth architecture that isolates secrets, validates code artifacts, and enforces strict redaction. When deploying OCR in production or CI pipelines, following these security best practices for running open-code-review ensures the review process remains isolated from the surrounding environment and prevents accidental credential exposure.

Keep the Binary Updated and Verified

Verify Release Signatures Before Execution

All release binaries are signed with GitHub Artifact Attestations using keyless Sigstore, and Git tags are signed with SSH keys. Before executing OCR in any environment, validate the binary integrity to protect against supply‑chain tampering.

# Verify the binary signature using the GitHub CLI

gh attestation verify /usr/local/bin/ocr --repo alibaba/open-code-review

# Or verify the Git tag signature

git tag -v v1.x.x

According to the SECURITY.md documentation, this verification guarantees that the downloaded executable matches the official release and has not been modified by third parties.

Adhere to the Supported Version Policy

Only the "Latest" released tag receives security patches. Running older versions leaves you exposed to known vulnerabilities that have been fixed in subsequent releases. Upgrade promptly after each new release to ensure you receive critical security updates.

Isolate and Protect LLM Credentials

Secure API Key Storage

LLM providers are external services, and leaking an API key grants attackers free access to the model and potentially downstream services. Store provider API keys in environment variables or a protected .env file, never in source code or command history.

In cmd/opencodereview/shared.go, OCR implements token masking at the UI level (lines 135–142), ensuring that any token entered via the interface is never written to logs or the manifest. However, you must still protect the original secret at the source.

# Load the API key from a protected environment variable

export OCR_OPENAI_API_KEY="${OCR_OPENAI_API_KEY:?Missing API key}"

Runtime Config Separation

OCR deliberately excludes credential information from the RuntimeConfig struct. As implemented in internal/agent/agent.go (lines 44–51), this struct only contains non‑secret fields such as Protocol, EndpointHost, Language, and Timeout.

This design guarantees that the manifest hash cannot be used to reconstruct secrets, even if the session data is compromised.

// Configure the Agent with a safe runtime config
cfg := ocr.Args{
    RepoDir:   "/path/to/repo",
    From:      "main",
    To:        "feature-branch",
    RuntimeConfig: ocr.RuntimeConfig{
        Protocol:     "openai",               // non‑secret
        EndpointHost: "api.openai.com",       // host only, no credentials
        Language:     "en",
        Timeout:      30 * time.Second,
    },
}
agent := ocr.New(cfg)

Enforce Secret Redaction in Outputs

sanitizeReason Implementation

Before persisting any failure or waiver reasons, OCR sanitizes content using the sanitizeReason function in internal/session/manifest.go (lines 47–84). This function removes URL credentials, bearer tokens, and credential‑like key/value pairs from stored data.

This prevents accidental leakage of secrets in the session manifest, log files, or downstream tools, ensuring that even if review data is exported or shared, sensitive credentials remain redacted.

UI-Level Token Masking

As noted in cmd/opencodereview/shared.go, the application masks any token entered via the UI. The stored value is never displayed on screen or written to console output, providing an additional layer of protection against shoulder surfing or accidental copy‑paste errors.

Lock Down CI/CD Integration

Principle of Least Privilege

When running OCR in CI pipelines, use the least‑privileged Git token that only allows read access to the repository. Limit OCR’s Git operations to the current workspace and avoid using the --allow-external flag, which minimizes impact if the CI runner is compromised.

OCR is designed to only read diffs and files; it performs no write‑back operations unless explicitly invoked by a hook, reducing the attack surface in automated environments.

Restrict Output Categories

Limit comment categories to only those you need to prevent leaking unrelated details. Use the --category and --severity flags documented in pages/src/content/docs/en/cli-reference.md to restrict output to security‑relevant findings only.

# Run OCR in workspace mode, limiting output to security findings

ocr review \
  --category security \
  --severity high,critical \
  --output json > review-results.json

This keeps output concise and prevents accidental exposure of low‑severity findings that might contain sensitive context.

Responsible Vulnerability Management

Private Reporting Process

Do not open public issues for security bugs. According to SECURITY.md, use the private vulnerability reporting flow via the GitHub Security Advisories UI. This keeps exploit details out of public view until a fix is released, protecting the community from zero‑day exposure.

Telemetry Configuration

When enabling telemetry, export data only to trusted back‑ends. Configure OTEL_EXPORTER via environment variables to prevent accidental leakage of proprietary code via telemetry payloads. The internal/telemetry package follows OpenTelemetry defaults, but you must explicitly configure the exporter endpoint to ensure data does not leave your trusted network boundary.

Summary

• Verify binaries using gh attestation verify or git tag -v before execution to prevent supply‑chain attacks.
• Store LLM credentials in environment variables only; OCR’s RuntimeConfig excludes secrets from manifests per internal/agent/agent.go.
• Rely on built‑in redaction via sanitizeReason in internal/session/manifest.go to strip credentials from logs and session data.
• Use least‑privilege tokens in CI with read‑only access and avoid the --allow-external flag.
• Filter output using --category security and --severity flags to limit exposure of sensitive findings.
• Report vulnerabilities privately through GitHub Security Advisories, not public issues.

Frequently Asked Questions

How does open-code-review prevent API keys from leaking in logs?

OCR prevents leakage through multiple mechanisms. The sanitizeReason function in internal/session/manifest.go removes URL credentials and bearer tokens before storing failure reasons. Additionally, cmd/opencodereview/shared.go masks tokens entered via the UI, and the RuntimeConfig struct in internal/agent/agent.go explicitly excludes credential fields from session manifests.

What is the safest way to authenticate LLM providers when using OCR?

Store API keys in environment variables or protected .env files, then reference them via shell expansion (e.g., export OCR_OPENAI_API_KEY="${OCR_OPENAI_API_KEY}"). Never pass credentials as command‑line arguments, as these may be logged by CI systems or shell history.

How can I verify that my OCR binary hasn't been tampered with?

Use GitHub’s attestation verification: run gh attestation verify /usr/local/bin/ocr --repo alibaba/open-code-review before execution. Alternatively, verify Git tag signatures using git tag -v. All official releases are signed with keyless Sigstore (Artifact Attestations) and SSH keys per the SECURITY.md documentation.

Does OCR write sensitive data to the review manifest?

No. OCR’s architecture ensures secrets never reach the manifest. The RuntimeConfig struct contains only non‑secret metadata (protocol, host, language), and the sanitizeReason function redacts any credential‑like patterns before persistence. This guarantees that manifest files can be safely shared or archived without exposing sensitive credentials.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}