feat(multivariate): report variant key on identities flag responses

[gagantrivedi]

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature. (deferred — docs will land once SDKs surface variant.)
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

Contributes to

Adds a variant field to each flag returned by /api/v1/identities/, so SDKs and experimentation can tell which multivariate variant an identity was exposed to:

{ "feature": {...}, "enabled": true, "feature_state_value": "blue", "variant": "control" }

The value is:

• the matched multivariate option's key, or
• "control" when the identity falls through to the base (control) value, or
• null for non-multivariate features.

Implementation notes:

• Scoped to the identities endpoint via a dedicated SDKIdentityFeatureStateSerializer subclass (features/serializers.py), wired into IdentifyWithTraitsSerializer.flags and the single-feature GET. /api/v1/flags/ shares the parent serializer and is left untouched — it has no identity to evaluate against (verified by a scoping test).
• The variant is read from the multivariate option already selected during evaluation (FeatureState.get_multivariate_feature_state_value); "control" uses a new CONTROL constant in features/constants.py.
• Remote (core) evaluation only; the flag engine / environment document and SDKs are out of scope for this slice.

How did you test this code?

Automated tests, written TDD-first (Given/When/Then):

• Integration (tests/integration/environments/identities/): parametrised over an identity hashing into variant 1, variant 2, and the control fall-through → asserts the correct variant key (and "control"); a standard feature reports variant: null; and /api/v1/flags/ responses contain no variant field (scoping proof).
• Unit (tests/unit/features/test_unit_features_serializers.py): get_variant returns null when no identity is in serializer context.

Verification run locally:

• Identities + feature serializer suites: 110 passed.
• ruff check, ruff format --check, and mypy (strict, incl. tests): clean.

Follow-ups (not in this PR)

• **OpenAPI spec (sdk/openapi.yaml)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
docs	Ignored	Preview	Jun 8, 2026 7:55am
flagsmith-frontend-preview	Ignored	Preview	Jun 8, 2026 7:55am
flagsmith-frontend-staging	Ignored	Preview	Jun 8, 2026 7:55am

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.53%. Comparing base (9e11027) to head (7653499).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #7723    +/-   ##
========================================
  Coverage   98.52%   98.53%            
========================================
  Files        1445     1446     +1     
  Lines       55083    55371   +288     
========================================
+ Hits        54273    54561   +288     
  Misses        810      810            

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gagantrivedi]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces the SDKIdentityFeatureStateSerializer to include a variant field in feature states evaluated for specific identities, falling back to a control variant if needed. It also adds corresponding integration and unit tests. The review feedback suggests using .get("identity") instead of direct dictionary access on self.context to avoid potential KeyError exceptions when the serializer is instantiated without an identity context, such as during OpenAPI schema generation.

[github-actions]

Docker builds report

Image	Build Status	Security report
ghcr.io/flagsmith/flagsmith-e2e:pr-7723	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-api-test:pr-7723	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-frontend:pr-7723	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-api:pr-7723	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith:pr-7723	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-private-cloud:pr-7723	Finished ✅	Results ✅

[github-actions]

Playwright Test Results (oss - depot-ubuntu-latest-16)

 1 passed

Details

 1 test across 1 suite
 40.9 seconds
 7653499
 🔄 Run: #17316 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

 2 passed

Details

 2 tests across 2 suites
 33.4 seconds
 7653499
 🔄 Run: #17316 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 44.5 seconds
 7653499
 🔄 Run: #17316 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 56.8 seconds
 7653499
 🔄 Run: #17316 (attempt 1)

[github-actions]

Visual Regression

19 screenshots compared. See report for details.
View full report

[Zaimwa9]

👍