feat: add secret_key config, deprecate personal_api_key

[turnipdabeets]

Problem

The credential used for local feature flag evaluation and remote config accepts either a Personal API Key (phx_...) or a Project Secret API Key (phs_...). Today the only option name is :personal_api_key, which is confusing — users with a Project Secret API Key reasonably assume the option won't accept it.

Change

• Add a new canonical :secret_key option to PostHog::Client.new (and the Rails config.secret_key= setter). It accepts either a Personal API Key (phx_...) or a Project Secret API Key (phs_...).
• Keep :personal_api_key working as a deprecated alias. When only the alias is used, a deprecation warning points users at :secret_key.
• When both are supplied, :secret_key wins.
• Internally the resolved value is stored as @secret_key, with @personal_api_key kept as a mirror so existing reads (the flags poller auth headers) keep working unchanged.
• Updated YARD @option docs, the flag-definition-cache doc example, and the Rails/generator config examples to demonstrate the canonical option.

Non-breaking — existing :personal_api_key callers keep working.

Specs added in spec/posthog/client_spec.rb prove: :secret_key sets the credential, :personal_api_key still works and warns, and :secret_key wins when both are provided. Full suite (580 examples) passes; RuboCop clean.

Context

• Coordinated rename across the backend SDKs (mirrors posthog-python PR #727 — this is the same change ported to Ruby).
• Rename item tracked in @posthog/convex: make feature flag refresh opt-in instead of running on every install posthog-js#4046 and discussed in Slack.

[github-actions]

posthog-ruby Compliance Report

Date: 2026-07-02 16:15:05 UTC
Duration: 98419ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	111ms
Format Validation.Event Has Uuid	✅	106ms
Format Validation.Event Has Lib Properties	✅	110ms
Format Validation.Distinct Id Is String	✅	108ms
Format Validation.Token Is Present	✅	107ms
Format Validation.Custom Properties Preserved	✅	107ms
Format Validation.Event Has Timestamp	✅	107ms
Retry Behavior.Retries On 503	✅	5314ms
Retry Behavior.Does Not Retry On 400	✅	2109ms
Retry Behavior.Does Not Retry On 401	✅	2109ms
Retry Behavior.Respects Retry After Header	✅	8117ms
Retry Behavior.Implements Backoff	✅	15723ms
Retry Behavior.Retries On 500	✅	5212ms
Retry Behavior.Retries On 502	✅	5212ms
Retry Behavior.Retries On 504	✅	5212ms
Retry Behavior.Max Retries Respected	✅	15523ms
Deduplication.Generates Unique Uuids	✅	111ms
Deduplication.Preserves Uuid On Retry	✅	5212ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10317ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5215ms
Deduplication.No Duplicate Events In Batch	✅	112ms
Deduplication.Different Events Have Different Uuids	✅	108ms
Compression.Sends Gzip When Enabled	✅	106ms
Batch Format.Uses Proper Batch Structure	✅	108ms
Batch Format.Flush With No Events Sends Nothing	✅	5ms
Batch Format.Multiple Events Batched Together	✅	111ms
Error Handling.Does Not Retry On 403	✅	2109ms
Error Handling.Does Not Retry On 413	✅	2109ms
Error Handling.Retries On 408	✅	5212ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	109ms
Request Payload.Flags Request Uses V2 Query Param	✅	110ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	110ms
Request Payload.Flags Request Omits Authorization Header	✅	107ms
Request Payload.Token In Flags Body Matches Init	✅	108ms
Request Payload.Groups Round Trip	✅	108ms
Request Payload.Groups Default To Empty Object	✅	107ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	108ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	108ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	108ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	107ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	113ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	106ms
Retry Behavior.Retries Flags On 502	✅	260ms
Retry Behavior.Retries Flags On 504	✅	211ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	109ms

[greptile-apps]

Comments Outside Diff (1)

1. lib/posthog/feature_flags.rb, line 32-54 (link)

   FeatureFlagsPoller param naming not updated

   The initialize parameter is still called personal_api_key (line 44) and the YARD @param doc on line 33 still reads "Personal API key used to fetch local evaluation definitions." The inline comment on line 77 was updated to mention secret_key, but the parameter name and doc were not, creating a split description inside the same method. Since this is an @api private class the public contract is unaffected, but it's now internally inconsistent: the log says "No secret_key provided" while the parameter that drives that check is still named personal_api_key.

_{Reviews (1): Last reviewed commit: "feat: add secret_key config, deprecate p..." | Re-trigger Greptile}

[greptile-apps]

_{Reviews (2): Last reviewed commit: "Regenerate API snapshot, rename poller s..." | Re-trigger Greptile}