Skip to content

Instantly share code, notes, and snippets.

@jeremyeder

jeremyeder/crd-change-analysis.md

Created January 29, 2026 14:15
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jeremyeder/e10c9df1fd366332d4d1f1ad513090f9 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jeremyeder/e10c9df1fd366332d4d1f1ad513090f9 to your computer and use it in GitHub Desktop.
Download ZIP
Ambient Code Platform - CRD Change Analysis (Jan 2026)
Raw
crd-change-analysis.md

Ambient Code Platform - CRD Change Analysis

Analysis Date: January 29, 2026 Repository: ambient-code/platform CRD Directory: components/manifests/base/crds/

Executive Summary

Change Frequency: ~2-4 changes per quarter (active but manageable) Risk Level: 🟡 MEDIUM - Expect breaking changes until API stabilizes to v1beta1/v1 Recommendation: Review CRD changes in release notes before each upgrade

Change Frequency Analysis

Repository Context

  • Repository Age: ~5.5 months (created August 11, 2025)
  • Current API Version: v1alpha1 (no stability guarantees)
  • CRD Files: 2 active CRDs

Commit History

CRD File Total Commits Recent Activity (Last 3 Months)
agenticsessions-crd.yaml 19 commits Active (12 commits)
projectsettings-crd.yaml 3 commits Low activity

Change Rate by Period

  • Last 30 days (Jan 2026): 2 changes
  • Last 90 days (Nov 2025 - Jan 2026): 4 changes
  • Overall average: ~3.5 changes per month

Recent Changes (Last 6 Commits)

Date Commit CRD Affected Change Size Description
Jan 13, 2026 a6ced3a AgenticSession +12 lines Display git currently checked-out branch in context
Jan 9, 2026 d061526 AgenticSession ±8 lines Per-repo autoPush configuration (replaced global setting)
Dec 4, 2025 40a5f31 AgenticSession ±177 lines Stronger session state (major refactor)
Nov 25, 2025 28479fc ProjectSettings +20 lines GitLab support (added provider enum)
Nov 10, 2025 1540e30 AgenticSession ±18 lines UI revamp backend changes
Nov 6, 2025 bf3c3f1 (restructure) 0 lines E2E tests (directory move)

Notable Pattern

The December 4, 2025 commit (40a5f31) was a major refactor touching 177 lines - this indicates willingness to make significant breaking changes during the alpha phase.

Risk Assessment

🟡 MEDIUM RISK - Active Evolution with Periodic Breaking Changes

HIGH RISK Factors

  • ✅ Active development - CRDs still evolving (not stabilized)
  • ✅ Recent major refactor - Dec 4 change touched 177 lines (session state redesign)
  • ✅ API version still alpha - v1alpha1 indicates no stability guarantees
  • ✅ Breaking changes confirmed - Recent removal of autoPushOnComplete shows willingness to break compatibility

MEDIUM RISK Factors

  • ⚠️ Moderate change frequency - ~1 change every 2 weeks
  • ⚠️ Status schema changes - Status fields actively being refined
  • ⚠️ Deprecated fields present - status.reconciledRepos[].branch marked DEPRECATED

LOW RISK Factors (Mitigating)

  • ✅ Additive changes common - Most changes add fields rather than remove
  • ✅ Backward compatibility efforts - Deprecation warnings instead of hard removals
  • ✅ Test coverage exists - E2E tests added Nov 6 help catch regressions

Change Impact Categories

1. Spec Changes (Affects Users)

Recent Examples:

  • Multi-repo support configuration
  • Per-repository autoPush field
  • Workflow configuration (activeWorkflow)
  • User context (authentication metadata)

Impact: Requires changes to session creation payloads, frontend forms, documentation

2. Status Changes (Affects Operator/Backend)

Recent Examples:

  • Phase enums: Pending → Creating → Running → Stopping → Stopped → Completed → Failed
  • Reconciliation state: reconciledRepos, reconciledWorkflow
  • Current branch tracking: currentActiveBranch, branches[]
  • Conditions array (Kubernetes-style status conditions)

Impact: Requires operator reconciliation logic updates, backend status parsing changes

3. Breaking Changes (Confirmed)

January 9, 2026 - Removed autoPushOnComplete:

# OLD (deprecated)
spec:
  autoPushOnComplete: true

# NEW (per-repository)
spec:
  repos:
    - url: https://github.com/org/repo
      autoPush: true

Status deprecation - reconciledRepos[].branch:

# DEPRECATED
status:
  reconciledRepos:
    - branch: "main"  # Don't use

# USE INSTEAD
status:
  reconciledRepos:
    - currentActiveBranch: "main"
      branches: ["main", "feature-xyz"]

Current CRD Schema Overview

AgenticSession (v1alpha1)

Spec Fields (19 commits, active development):

  • repos[] - Multi-repository configuration
  • interactive - Chat mode vs batch mode
  • initialPrompt - First SDK invocation prompt
  • displayName - Human-readable session name
  • userContext - Authenticated caller identity
  • llmSettings - Model, temperature, maxTokens
  • timeout - Session timeout in seconds
  • activeWorkflow - Dynamic workflow switching

Status Fields:

  • observedGeneration - Reconciliation tracking
  • phase - Session lifecycle state (7 enum values)
  • startTime, completionTime - Timestamps
  • reconciledRepos[] - Per-repo reconciliation state
  • reconciledWorkflow - Active workflow state
  • sdkSessionId - Resume support
  • sdkRestartCount - Restart tracking
  • conditions[] - Kubernetes-style conditions

ProjectSettings (v1alpha1)

Spec Fields (3 commits, stable):

  • groupAccess[] - RBAC group bindings
  • runnerSecretsName - Runner configuration secret
  • repositories[] - Git repository configuration

Status Fields:

  • groupBindingsCreated - RoleBinding count

Recommendations

For Deployment Planning

  1. Expect monthly schema changes until v1beta1 or v1 release
  2. Test CRD upgrades in dev before applying to production clusters
  3. Monitor deprecation warnings - Current: reconciledRepos[].branch
  4. Plan migration windows when upgrading (not zero-downtime compatible)
  5. Subscribe to repository notifications for CRD-related commits

For Development

  1. Don't rely on alpha API stability - Use feature flags for experimental fields
  2. Version your clients - Pin to specific CRD versions in CI/CD pipelines
  3. Watch for status schema changes - Backend/operator need coordinated updates
  4. Use OpenAPI validation - CRDs include openAPIV3Schema for client generation
  5. Test against latest CRDs - Pull latest manifests before development

Risk Mitigation Strategies

Before Upgrading

  • ✅ Review commit history: gh api repos/ambient-code/platform/commits?path=components/manifests/base/crds
  • ✅ Check diff: Compare current vs new CRD schema
  • ✅ Backup existing CRs: kubectl get agenticsessions -A -o yaml > backup.yaml
  • ✅ Test in dev namespace first

During Upgrade

  • ✅ Apply CRDs first: kubectl apply -f crds/
  • ✅ Verify CRD version: kubectl get crd agenticsessions.vteam.ambient-code -o yaml
  • ✅ Check for validation errors: Watch CRD events
  • ✅ Update operator/backend: Deploy new versions that understand schema changes

After Upgrade

  • ✅ Validate existing resources: kubectl get agenticsessions -A
  • ✅ Check for warnings: Look for deprecated field usage in logs
  • ✅ Run E2E tests: make test-e2e to verify functionality
  • ✅ Monitor operator logs: Watch for reconciliation errors

Change Timeline (Visual)

Aug 2025    Sep 2025    Oct 2025    Nov 2025    Dec 2025    Jan 2026
    |           |           |           |           |           |
    └─ Repo     └─ 3        └─ 4        └─ 2        └─ MAJOR    └─ 2
       Created     changes     changes     changes     REFACTOR     changes
                                                      (177 lines)

Change Intensity: ████░░░░░░░ (Active → Stabilizing)

Conclusion

The Ambient Code Platform CRDs are actively evolving with an average of 2-4 changes per quarter. The December 2025 major refactor (177 lines) and January 2026 breaking change (removal of autoPushOnComplete) demonstrate that the API is still in active development.

Key Takeaway: While changes are manageable in frequency, they can be significant in scope. Treat these as alpha-quality APIs and plan for schema evolution until the project graduates to v1beta1 or v1.

Next Milestone to Watch: Promotion from v1alpha1 → v1beta1 (signals API stabilization)

Generated: 2026-01-29 Methodology: GitHub API commit analysis + local git history Commands Used:

gh api repos/ambient-code/platform/commits?path=components/manifests/base/crds
git log --oneline --follow components/manifests/base/crds/*.yaml
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment