Skip to content

πŸ™Œ OpenHands: AI-Driven Development

feat(backend): add API endpoints to claim and disconnect git organizations (#13683)

Hiep Le5d593ca6e4cd
diff --git a/enterprise/migrations/versions/105_create_org_git_claim_table.py b/enterprise/migrations/versions/105_create_org_git_claim_table.py
new file mode 100644
index 0000000000..3836255383
--- /dev/null
+++ b/enterprise/migrations/versions/105_create_org_git_claim_table.py
@@ -0,0 +1,37 @@
+"""Create org_git_claim table for tracking Git organization claims.
+
+Revision ID: 105
+Revises: 104
+Create Date: 2026-04-01
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = '105'
+down_revision: Union[str, None] = '104'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+ op.create_table(
+ 'org_git_claim',
+ sa.Column('id', sa.UUID(), nullable=False),
+ sa.Column('org_id', sa.UUID(), nullable=False),
+ sa.Column('provider', sa.String(), nullable=False),
+ sa.Column('git_organization', sa.String(), nullable=False),
+ sa.Column('claimed_by', sa.UUID(), nullable=False),
+ sa.Column('claimed_at', sa.DateTime(timezone=True), nullable=False),
+ sa.ForeignKeyConstraint(['org_id'], ['org.id'], ondelete='CASCADE'),
+ sa.ForeignKeyConstraint(['claimed_by'], ['user.id']),
+ sa.PrimaryKeyConstraint('id'),
+ sa.UniqueConstraint('provider', 'git_organization', name='uq_provider_git_org'),
+ )
+
+
+def downgrade() -> None:
+ op.drop_table('org_git_claim')
diff --git a/enterprise/server/auth/authorization.py b/enterprise/server/auth/authorization.py
index ef2b7e91c4..89d1666f97 100644
--- a/enterprise/server/auth/authorization.py
+++ b/enterprise/server/auth/authorization.py
@@ -84,6 +84,9 @@ class Permission(str, Enum):
# Temporary permissions until we finish the API updates.
EDIT_ORG_SETTINGS = 'edit_org_settings'
+ # Git organization claims
+ MANAGE_ORG_CLAIMS = 'manage_org_claims'
+
class RoleName(str, Enum):
"""Role names used in the system."""
@@ -118,6 +121,8 @@ ROLE_PERMISSIONS: dict[RoleName, frozenset[Permission]] = {
# Organization Management (Owner only)
Permission.CHANGE_ORGANIZATION_NAME,
Permission.DELETE_ORGANIZATION,
+ # Git organization claims
+ Permission.MANAGE_ORG_CLAIMS,
]
),
RoleName.ADMIN: frozenset(
@@ -139,6 +144,8 @@ ROLE_PERMISSIONS: dict[RoleName, frozenset[Permission]] = {
# Organization Management
Permission.VIEW_ORG_SETTINGS,
Permission.EDIT_ORG_SETTINGS,
+ # Git organization claims
+ Permission.MANAGE_ORG_CLAIMS,
]
),
RoleName.MEMBER: frozenset(
diff --git a/enterprise/server/routes/org_models.py b/enterprise/server/routes/org_models.py
index dcccc6f9e8..e57c429101 100644
--- a/enterprise/server/routes/org_models.py
+++ b/enterprise/server/routes/org_models.py
@@ -485,6 +485,56 @@ class OrgAppSettingsUpdate(BaseModel):
return v
+VALID_GIT_PROVIDERS = {'github', 'gitlab', 'bitbucket'}
+
+
+class GitOrgClaimRequest(BaseModel):
+ """Request model for claiming a Git organization."""
+
+ provider: str
+ git_organization: str
+
+ @field_validator('provider')
+ @classmethod
+ def validate_provider(cls, v: str) -> str:
+ v = v.lower().strip()
+ if v not in VALID_GIT_PROVIDERS:
+ raise ValueError(
+ f'Invalid provider: "{v}". Must be one of: {", ".join(sorted(VALID_GIT_PROVIDERS))}'
+ )
+ return v
+
+ @field_validator('git_organization')
+ @classmethod
+ def validate_git_organization(cls, v: str) -> str:
+ v = v.strip().lower()
+ if not v:
+ raise ValueError('git_organization must not be empty')
+ return v
+
+
+class GitOrgClaimResponse(BaseModel):
+ """Response model for a Git organization claim."""
+
+ id: str
+ org_id: str
+ provider: str
+ git_organization: str
+ claimed_by: str
+ claimed_at: str
+
+
+class GitOrgAlreadyClaimedError(Exception):
+ """Raised when a Git organization is already claimed by another OpenHands org."""
+
+ def __init__(self, provider: str, git_organization: str):
+ self.provider = provider
+ self.git_organization = git_organization
+ super().__init__(
+ f'Git organization "{git_organization}" on {provider} is already claimed by another organization'
+ )
+
+
class OrgMemberFinancialResponse(BaseModel):
"""Financial data for a single organization member."""
diff --git a/enterprise/server/routes/orgs.py b/enterprise/server/routes/orgs.py
index d4ee26c3c5..a9a7c4d05e 100644
--- a/enterprise/server/routes/orgs.py
+++ b/enterprise/server/routes/orgs.py
@@ -10,6 +10,9 @@ from server.auth.authorization import (
from server.email_validation import get_admin_user_id
from server.routes.org_models import (
CannotModifySelfError,
+ GitOrgAlreadyClaimedError,
+ GitOrgClaimRequest,
+ GitOrgClaimResponse,
InsufficientPermissionError,
InvalidRoleError,
LastOwnerError,
@@ -46,6 +49,8 @@ from server.services.org_llm_settings_service import (
)
from server.services.org_member_financial_service import OrgMemberFinancialService
from server.services.org_member_service import OrgMemberService
+from sqlalchemy.exc import IntegrityError
+from storage.org_git_claim_store import OrgGitClaimStore
from storage.org_service import OrgService
from storage.user_store import UserStore
@@ -1212,3 +1217,181 @@ async def update_org_member(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
detail='Failed to update member',
)
+
+
+@org_router.get(
+ '/{org_id}/git-claims',
+ response_model=list[GitOrgClaimResponse],
+)
+async def get_git_claims(
+ org_id: UUID,
+ user_id: str = Depends(require_permission(Permission.MANAGE_ORG_CLAIMS)),
+) -> list[GitOrgClaimResponse]:
+ """Get all Git organization claims for an OpenHands organization.
+
+ Only admin and owner roles can view Git organization claims.
+
+ Args:
+ org_id: OpenHands organization UUID
+ user_id: Authenticated user ID (injected by permission check)
+
+ Returns:
+ List of GitOrgClaimResponse with claim details
+ """
+ try:
+ claims = await OrgGitClaimStore.get_claims_by_org_id(org_id=org_id)
+ return [
+ GitOrgClaimResponse(
+ id=str(claim.id),
+ org_id=str(claim.org_id),
+ provider=claim.provider,
+ git_organization=claim.git_organization,
+ claimed_by=str(claim.claimed_by),
+ claimed_at=claim.claimed_at.isoformat(),
+ )
+ for claim in claims
+ ]
+ except Exception:
+ logger.exception('Error fetching Git organization claims')
+ raise HTTPException(
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+ detail='Failed to fetch Git organization claims',
+ )
+
+
+@org_router.post(
+ '/{org_id}/git-claims',
+ response_model=GitOrgClaimResponse,
+ status_code=status.HTTP_201_CREATED,
+)
+async def claim_git_organization(
+ org_id: UUID,
+ request: GitOrgClaimRequest,
+ user_id: str = Depends(require_permission(Permission.MANAGE_ORG_CLAIMS)),
+) -> GitOrgClaimResponse:
+ """Claim a Git organization for an OpenHands organization.
+
+ Only admin and owner roles can claim Git organizations.
+ A Git organization can only be claimed by one OpenHands organization at a time.
+
+ Args:
+ org_id: OpenHands organization UUID
+ request: Claim request with provider and git_organization
+ user_id: Authenticated user ID (injected by permission check)
+
+ Returns:
+ GitOrgClaimResponse with the created claim details
+
+ Raises:
+ HTTPException 409: If the Git organization is already claimed
+ HTTPException 403: If user lacks permission
+ """
+ try:
+ # Check if this Git org is already claimed (early feedback for the common case)
+ existing_claim = await OrgGitClaimStore.get_claim_by_provider_and_git_org(
+ provider=request.provider,
+ git_organization=request.git_organization,
+ )
+
+ if existing_claim:
+ raise GitOrgAlreadyClaimedError(
+ provider=request.provider,
+ git_organization=request.git_organization,
+ )
+
+ # Create the claim β€” the DB unique constraint handles the race condition
+ # where two concurrent requests both pass the check above.
+ claim = await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider=request.provider,
+ git_organization=request.git_organization,
+ claimed_by=UUID(user_id),
+ )
+
+ return GitOrgClaimResponse(
+ id=str(claim.id),
+ org_id=str(claim.org_id),
+ provider=claim.provider,
+ git_organization=claim.git_organization,
+ claimed_by=str(claim.claimed_by),
+ claimed_at=claim.claimed_at.isoformat(),
+ )
+
+ except GitOrgAlreadyClaimedError as e:
+ raise HTTPException(
+ status_code=status.HTTP_409_CONFLICT,
+ detail=str(e),
+ )
+ except IntegrityError as e:
+ # Only treat the unique constraint violation as a duplicate claim.
+ # Other integrity errors (e.g. FK violations) should surface as 500s.
+ if 'uq_provider_git_org' in str(e.orig):
+ raise HTTPException(
+ status_code=status.HTTP_409_CONFLICT,
+ detail=str(
+ GitOrgAlreadyClaimedError(
+ provider=request.provider,
+ git_organization=request.git_organization,
+ )
+ ),
+ )
+ logger.exception('Integrity error claiming Git organization')
+ raise HTTPException(
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+ detail='Failed to claim Git organization',
+ )
+ except Exception:
+ logger.exception('Error claiming Git organization')
+ raise HTTPException(
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+ detail='Failed to claim Git organization',
+ )
+
+
+@org_router.delete(
+ '/{org_id}/git-claims/{claim_id}',
+ status_code=status.HTTP_200_OK,
+)
+async def disconnect_git_organization(
+ org_id: UUID,
+ claim_id: UUID,
+ user_id: str = Depends(require_permission(Permission.MANAGE_ORG_CLAIMS)),
+) -> dict:
+ """Remove a Git organization claim from an OpenHands organization.
+
+ Only admin and owner roles can disconnect Git organization claims.
+
+ Args:
+ org_id: OpenHands organization UUID
+ claim_id: Claim UUID to remove
+ user_id: Authenticated user ID (injected by permission check)
+
+ Returns:
+ dict: Confirmation message on successful deletion
+
+ Raises:
+ HTTPException 404: If the claim is not found for this organization
+ HTTPException 403: If user lacks permission
+ """
+ try:
+ deleted = await OrgGitClaimStore.delete_claim(
+ claim_id=claim_id,
+ org_id=org_id,
+ )
+
+ if not deleted:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail='Git organization claim not found',
+ )
+
+ return {'message': 'Git organization claim removed successfully'}
+
+ except HTTPException:
+ raise
+ except Exception:
+ logger.exception('Error disconnecting Git organization')
+ raise HTTPException(
+ status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+ detail='Failed to disconnect Git organization',
+ )
diff --git a/enterprise/storage/__init__.py b/enterprise/storage/__init__.py
index c427ec9222..8f2e987fd7 100644
--- a/enterprise/storage/__init__.py
+++ b/enterprise/storage/__init__.py
@@ -19,6 +19,7 @@ from storage.linear_workspace import LinearWorkspace
from storage.maintenance_task import MaintenanceTask, MaintenanceTaskStatus
from storage.openhands_pr import OpenhandsPR
from storage.org import Org
+from storage.org_git_claim import OrgGitClaim
from storage.org_invitation import OrgInvitation
from storage.org_member import OrgMember
from storage.proactive_convos import ProactiveConversation
@@ -65,6 +66,7 @@ __all__ = [
'MaintenanceTaskStatus',
'OpenhandsPR',
'Org',
+ 'OrgGitClaim',
'OrgInvitation',
'OrgMember',
'ProactiveConversation',
diff --git a/enterprise/storage/org.py b/enterprise/storage/org.py
index 3b0b898fd1..8f4f6ba2c5 100644
--- a/enterprise/storage/org.py
+++ b/enterprise/storage/org.py
@@ -64,6 +64,7 @@ class Org(Base): # type: ignore
slack_conversations = relationship('SlackConversation', back_populates='org')
slack_users = relationship('SlackUser', back_populates='org')
stripe_customers = relationship('StripeCustomer', back_populates='org')
+ git_claims = relationship('OrgGitClaim', back_populates='org')
def __init__(self, **kwargs):
# Handle known SQLAlchemy columns directly
diff --git a/enterprise/storage/org_git_claim.py b/enterprise/storage/org_git_claim.py
new file mode 100644
index 0000000000..4d5bf41be4
--- /dev/null
+++ b/enterprise/storage/org_git_claim.py
@@ -0,0 +1,30 @@
+"""
+SQLAlchemy model for Git Organization Claims.
+"""
+
+from uuid import uuid4
+
+from sqlalchemy import UUID, Column, DateTime, ForeignKey, String, UniqueConstraint
+from sqlalchemy.orm import relationship
+from storage.base import Base
+
+
+class OrgGitClaim(Base): # type: ignore
+ """Model for tracking which OpenHands org has claimed a Git organization."""
+
+ __tablename__ = 'org_git_claim'
+
+ id = Column(UUID(as_uuid=True), primary_key=True, default=uuid4)
+ org_id = Column(
+ UUID(as_uuid=True), ForeignKey('org.id', ondelete='CASCADE'), nullable=False
+ )
+ provider = Column(String, nullable=False)
+ git_organization = Column(String, nullable=False)
+ claimed_by = Column(UUID(as_uuid=True), ForeignKey('user.id'), nullable=False)
+ claimed_at = Column(DateTime(timezone=True), nullable=False)
+
+ __table_args__ = (
+ UniqueConstraint('provider', 'git_organization', name='uq_provider_git_org'),
+ )
+
+ org = relationship('Org', back_populates='git_claims')
diff --git a/enterprise/storage/org_git_claim_store.py b/enterprise/storage/org_git_claim_store.py
new file mode 100644
index 0000000000..95a9c366f8
--- /dev/null
+++ b/enterprise/storage/org_git_claim_store.py
@@ -0,0 +1,141 @@
+"""
+Store class for managing Git organization claims.
+"""
+
+from datetime import datetime, timezone
+from typing import Optional
+from uuid import UUID
+
+from sqlalchemy import and_, select
+from storage.database import a_session_maker
+from storage.org_git_claim import OrgGitClaim
+
+from openhands.core.logger import openhands_logger as logger
+
+
+class OrgGitClaimStore:
+ """Store for managing Git organization claims."""
+
+ @staticmethod
+ async def create_claim(
+ org_id: UUID,
+ provider: str,
+ git_organization: str,
+ claimed_by: UUID,
+ ) -> OrgGitClaim:
+ """Create a new Git organization claim.
+
+ Args:
+ org_id: OpenHands organization UUID
+ provider: Git provider ('github', 'gitlab', 'bitbucket')
+ git_organization: Name of the Git organization being claimed
+ claimed_by: User UUID who is making the claim
+
+ Returns:
+ OrgGitClaim: The created claim record
+ """
+ async with a_session_maker() as session:
+ claim = OrgGitClaim(
+ org_id=org_id,
+ provider=provider,
+ git_organization=git_organization,
+ claimed_by=claimed_by,
+ claimed_at=datetime.now(timezone.utc),
+ )
+ session.add(claim)
+ await session.commit()
+ await session.refresh(claim)
+
+ logger.info(
+ 'Created Git organization claim',
+ extra={
+ 'claim_id': str(claim.id),
+ 'org_id': str(org_id),
+ 'provider': provider,
+ 'git_organization': git_organization,
+ 'claimed_by': str(claimed_by),
+ },
+ )
+
+ return claim
+
+ @staticmethod
+ async def get_claim_by_provider_and_git_org(
+ provider: str,
+ git_organization: str,
+ ) -> Optional[OrgGitClaim]:
+ """Check if a Git organization is already claimed.
+
+ Args:
+ provider: Git provider name
+ git_organization: Name of the Git organization
+
+ Returns:
+ OrgGitClaim or None if not claimed
+ """
+ async with a_session_maker() as session:
+ result = await session.execute(
+ select(OrgGitClaim).filter(
+ and_(
+ OrgGitClaim.provider == provider,
+ OrgGitClaim.git_organization == git_organization,
+ )
+ )
+ )
+ return result.scalars().first()
+
+ @staticmethod
+ async def get_claims_by_org_id(org_id: UUID) -> list[OrgGitClaim]:
+ """Get all Git organization claims for an OpenHands organization.
+
+ Args:
+ org_id: OpenHands organization UUID
+
+ Returns:
+ List of OrgGitClaim records
+ """
+ async with a_session_maker() as session:
+ result = await session.execute(
+ select(OrgGitClaim).filter(OrgGitClaim.org_id == org_id)
+ )
+ return list(result.scalars().all())
+
+ @staticmethod
+ async def delete_claim(claim_id: UUID, org_id: UUID) -> bool:
+ """Delete a Git organization claim.
+
+ Args:
+ claim_id: Claim UUID to delete
+ org_id: OpenHands organization UUID (for ownership verification)
+
+ Returns:
+ True if deleted, False if not found
+ """
+ async with a_session_maker() as session:
+ result = await session.execute(
+ select(OrgGitClaim).filter(
+ and_(
+ OrgGitClaim.id == claim_id,
+ OrgGitClaim.org_id == org_id,
+ )
+ )
+ )
+ claim = result.scalars().first()
+
+ if not claim:
+ return False
+
+ await session.delete(claim)
+ await session.commit()
+
+ logger.info(
+ 'Deleted Git organization claim',
+ extra={
+ 'claim_id': str(claim_id),
+ 'org_id': str(org_id),
+ 'provider': claim.provider,
+ 'git_organization': claim.git_organization,
+ },
+ )
+
+ return True
diff --git a/enterprise/tests/unit/conftest.py b/enterprise/tests/unit/conftest.py
index e0a929a722..8777eee9e7 100644
--- a/enterprise/tests/unit/conftest.py
+++ b/enterprise/tests/unit/conftest.py
@@ -25,6 +25,7 @@ from storage.device_code import DeviceCode # noqa: F401
from storage.feedback import Feedback
from storage.github_app_installation import GithubAppInstallation
from storage.org import Org
+from storage.org_git_claim import OrgGitClaim # noqa: F401
from storage.org_invitation import OrgInvitation # noqa: F401
from storage.org_member import OrgMember
from storage.role import Role
diff --git a/enterprise/tests/unit/server/routes/test_org_git_claims.py b/enterprise/tests/unit/server/routes/test_org_git_claims.py
new file mode 100644
index 0000000000..a6687f61cb
--- /dev/null
+++ b/enterprise/tests/unit/server/routes/test_org_git_claims.py
@@ -0,0 +1,603 @@
+"""Tests for Git organization claim API endpoints.
+
+Tests the following endpoints:
+- GET /api/organizations/{org_id}/git-claims (list claims)
+- POST /api/organizations/{org_id}/git-claims (claim)
+- DELETE /api/organizations/{org_id}/git-claims/{claim_id} (disconnect)
+"""
+
+import uuid
+from datetime import datetime
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+from fastapi import FastAPI, status
+from fastapi.testclient import TestClient
+from server.routes.orgs import (
+ claim_git_organization,
+ disconnect_git_organization,
+ get_git_claims,
+ org_router,
+)
+from sqlalchemy.exc import IntegrityError
+from storage.org_git_claim import OrgGitClaim
+
+from openhands.server.user_auth import get_user_id
+
+TEST_USER_ID = str(uuid.uuid4())
+
+
+def org_id():
+ return uuid.uuid4()
+
+
+def user_id():
+ return str(uuid.uuid4())
+
+
+def make_claim():
+ """Factory to create mock OrgGitClaim objects."""
+
+ def _make(org_id, provider='github', git_organization='OpenHands', claimed_by=None):
+ claim = MagicMock(spec=OrgGitClaim)
+ claim.id = uuid.uuid4()
+ claim.org_id = org_id
+ claim.provider = provider
+ claim.git_organization = git_organization
+ claim.claimed_by = claimed_by or uuid.uuid4()
+ claim.claimed_at = datetime(2026, 4, 1, 12, 0, 0)
+ return claim
+
+ return _make
+
+
+# =============================================================================
+# GET /api/organizations/{org_id}/git-claims
+# =============================================================================
+
+
+class TestGetGitClaims:
+ """Tests for the get Git organization claims endpoint."""
+
+ @pytest.mark.asyncio
+ async def test_returns_empty_list_when_no_claims(self, org_id, user_id):
+ """
+ GIVEN: An organization with no Git claims
+ WHEN: GET /api/organizations/{org_id}/git-claims is called
+ THEN: An empty list is returned
+ """
+ with patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claims_by_org_id',
+ AsyncMock(return_value=[]),
+ ) as mock_get:
+ result = await get_git_claims(org_id=org_id, user_id=user_id)
+
+ assert result == []
+ mock_get.assert_called_once_with(org_id=org_id)
+
+ @pytest.mark.asyncio
+ async def test_returns_claims_for_organization(self, org_id, user_id, make_claim):
+ """
+ GIVEN: An organization with multiple Git claims
+ WHEN: GET /api/organizations/{org_id}/git-claims is called
+ THEN: All claims are returned with correct details
+ """
+ claim1 = make_claim(org_id, provider='github', git_organization='OpenHands')
+ claim2 = make_claim(org_id, provider='gitlab', git_organization='AcmeCo')
+
+ with patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claims_by_org_id',
+ AsyncMock(return_value=[claim1, claim2]),
+ ):
+ result = await get_git_claims(org_id=org_id, user_id=user_id)
+
+ assert len(result) == 2
+ assert result[0].id == str(claim1.id)
+ assert result[0].org_id == str(org_id)
+ assert result[0].provider == 'github'
+ assert result[0].git_organization == 'OpenHands'
+ assert result[0].claimed_by == str(claim1.claimed_by)
+ assert result[0].claimed_at == '2026-04-01T12:00:00'
+ assert result[1].id == str(claim2.id)
+ assert result[1].provider == 'gitlab'
+ assert result[1].git_organization == 'AcmeCo'
+
+ @pytest.mark.asyncio
+ async def test_returns_500_on_unexpected_error(self, org_id, user_id):
+ """
+ GIVEN: An unexpected error occurs when fetching claims
+ WHEN: GET /api/organizations/{org_id}/git-claims is called
+ THEN: A 500 Internal Server Error is returned
+ """
+ with patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claims_by_org_id',
+ AsyncMock(side_effect=RuntimeError('db connection failed')),
+ ):
+ with pytest.raises(Exception) as exc_info:
+ await get_git_claims(org_id=org_id, user_id=user_id)
+
+ assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
+# =============================================================================
+# POST /api/organizations/{org_id}/git-claims
+# =============================================================================
+
+
+class TestClaimGitOrganization:
+ """Tests for the claim Git organization endpoint."""
+
+ @pytest.mark.asyncio
+ async def test_claim_succeeds_for_unclaimed_org(self, org_id, user_id, make_claim):
+ """
+ GIVEN: A Git organization that has not been claimed
+ WHEN: POST /api/organizations/{org_id}/git-claims is called
+ THEN: The claim is created and returned with correct details
+ """
+ # Arrange
+ mock_claim = make_claim(org_id, claimed_by=uuid.UUID(user_id))
+ request = MagicMock()
+ request.provider = 'github'
+ request.git_organization = 'OpenHands'
+
+ with (
+ patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claim_by_provider_and_git_org',
+ AsyncMock(return_value=None),
+ ),
+ patch(
+ 'server.routes.orgs.OrgGitClaimStore.create_claim',
+ AsyncMock(return_value=mock_claim),
+ ) as mock_create,
+ ):
+ # Act
+ response = await claim_git_organization(
+ org_id=org_id, request=request, user_id=user_id
+ )
+
+ # Assert
+ assert response.id == str(mock_claim.id)
+ assert response.org_id == str(org_id)
+ assert response.provider == 'github'
+ assert response.git_organization == 'OpenHands'
+ assert response.claimed_by == user_id
+ mock_create.assert_called_once_with(
+ org_id=org_id,
+ provider='github',
+ git_organization='OpenHands',
+ claimed_by=uuid.UUID(user_id),
+ )
+
+ @pytest.mark.asyncio
+ async def test_claim_fails_when_already_claimed(self, org_id, user_id, make_claim):
+ """
+ GIVEN: A Git organization already claimed by another OpenHands org
+ WHEN: POST /api/organizations/{org_id}/git-claims is called
+ THEN: A 409 Conflict error is returned
+ """
+ # Arrange
+ other_org_id = uuid.uuid4()
+ existing_claim = make_claim(
+ other_org_id, provider='github', git_organization='AlreadyClaimed'
+ )
+ request = MagicMock()
+ request.provider = 'github'
+ request.git_organization = 'AlreadyClaimed'
+
+ with patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claim_by_provider_and_git_org',
+ AsyncMock(return_value=existing_claim),
+ ):
+ # Act & Assert
+ with pytest.raises(Exception) as exc_info:
+ await claim_git_organization(
+ org_id=org_id, request=request, user_id=user_id
+ )
+
+ assert exc_info.value.status_code == status.HTTP_409_CONFLICT
+
+ @pytest.mark.asyncio
+ async def test_claim_returns_500_on_unexpected_error(self, org_id, user_id):
+ """
+ GIVEN: An unexpected error occurs during claim creation
+ WHEN: POST /api/organizations/{org_id}/git-claims is called
+ THEN: A 500 Internal Server Error is returned
+ """
+ # Arrange
+ request = MagicMock()
+ request.provider = 'github'
+ request.git_organization = 'OpenHands'
+
+ with patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claim_by_provider_and_git_org',
+ AsyncMock(side_effect=RuntimeError('db connection failed')),
+ ):
+ # Act & Assert
+ with pytest.raises(Exception) as exc_info:
+ await claim_git_organization(
+ org_id=org_id, request=request, user_id=user_id
+ )
+
+ assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
+
+ @pytest.mark.asyncio
+ async def test_claim_race_condition_returns_409(self, org_id, user_id):
+ """
+ GIVEN: Pre-check passes but a concurrent request claims the org first
+ WHEN: create_claim raises IntegrityError (DB unique constraint)
+ THEN: A 409 Conflict error is returned instead of 500
+ """
+ # Arrange
+ request = MagicMock()
+ request.provider = 'github'
+ request.git_organization = 'RaceOrg'
+
+ with (
+ patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claim_by_provider_and_git_org',
+ AsyncMock(return_value=None),
+ ),
+ patch(
+ 'server.routes.orgs.OrgGitClaimStore.create_claim',
+ AsyncMock(
+ side_effect=IntegrityError(
+ 'duplicate',
+ '',
+ Exception('uq_provider_git_org'),
+ )
+ ),
+ ),
+ ):
+ # Act & Assert
+ with pytest.raises(Exception) as exc_info:
+ await claim_git_organization(
+ org_id=org_id, request=request, user_id=user_id
+ )
+
+ assert exc_info.value.status_code == status.HTTP_409_CONFLICT
+
+
+# =============================================================================
+# DELETE /api/organizations/{org_id}/git-claims/{claim_id}
+# =============================================================================
+
+
+class TestDisconnectGitOrganization:
+ """Tests for the disconnect Git organization endpoint."""
+
+ @pytest.mark.asyncio
+ async def test_disconnect_succeeds_for_existing_claim(self, org_id, user_id):
+ """
+ GIVEN: A valid claim belonging to the organization
+ WHEN: DELETE /api/organizations/{org_id}/git-claims/{claim_id} is called
+ THEN: The claim is deleted and a success message is returned
+ """
+ # Arrange
+ claim_id = uuid.uuid4()
+
+ with patch(
+ 'server.routes.orgs.OrgGitClaimStore.delete_claim',
+ AsyncMock(return_value=True),
+ ) as mock_delete:
+ # Act
+ result = await disconnect_git_organization(
+ org_id=org_id, claim_id=claim_id, user_id=user_id
+ )
+
+ # Assert
+ assert result == {'message': 'Git organization claim removed successfully'}
+ mock_delete.assert_called_once_with(claim_id=claim_id, org_id=org_id)
+
+ @pytest.mark.asyncio
+ async def test_disconnect_fails_when_claim_not_found(self, org_id, user_id):
+ """
+ GIVEN: A claim_id that does not exist for this organization
+ WHEN: DELETE /api/organizations/{org_id}/git-claims/{claim_id} is called
+ THEN: A 404 Not Found error is returned
+ """
+ # Arrange
+ claim_id = uuid.uuid4()
+
+ with patch(
+ 'server.routes.orgs.OrgGitClaimStore.delete_claim',
+ AsyncMock(return_value=False),
+ ):
+ # Act & Assert
+ with pytest.raises(Exception) as exc_info:
+ await disconnect_git_organization(
+ org_id=org_id, claim_id=claim_id, user_id=user_id
+ )
+
+ assert exc_info.value.status_code == status.HTTP_404_NOT_FOUND
+
+ @pytest.mark.asyncio
+ async def test_disconnect_returns_500_on_unexpected_error(self, org_id, user_id):
+ """
+ GIVEN: An unexpected error occurs during claim deletion
+ WHEN: DELETE /api/organizations/{org_id}/git-claims/{claim_id} is called
+ THEN: A 500 Internal Server Error is returned
+ """
+ # Arrange
+ claim_id = uuid.uuid4()
+
+ with patch(
+ 'server.routes.orgs.OrgGitClaimStore.delete_claim',
+ AsyncMock(side_effect=RuntimeError('db connection failed')),
+ ):
+ # Act & Assert
+ with pytest.raises(Exception) as exc_info:
+ await disconnect_git_organization(
+ org_id=org_id, claim_id=claim_id, user_id=user_id
+ )
+
+ assert exc_info.value.status_code == status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
+# =============================================================================
+# Validation tests for GitOrgClaimRequest
+# =============================================================================
+
+
+class TestGitOrgClaimRequestValidation:
+ """Tests for request model validation."""
+
+ def test_valid_providers_are_accepted(self):
+ """Each supported provider is accepted and normalized to lowercase."""
+ from server.routes.org_models import GitOrgClaimRequest
+
+ for provider in ['github', 'GitLab', 'BITBUCKET']:
+ req = GitOrgClaimRequest(provider=provider, git_organization='test-org')
+ assert req.provider == provider.lower().strip()
+
+ def test_invalid_provider_is_rejected(self):
+ """An unsupported provider raises a validation error."""
+ from pydantic import ValidationError
+ from server.routes.org_models import GitOrgClaimRequest
+
+ with pytest.raises(ValidationError, match='Invalid provider'):
+ GitOrgClaimRequest(provider='azure_devops', git_organization='test-org')
+
+ def test_empty_git_organization_is_rejected(self):
+ """An empty git_organization raises a validation error."""
+ from pydantic import ValidationError
+ from server.routes.org_models import GitOrgClaimRequest
+
+ with pytest.raises(ValidationError, match='git_organization must not be empty'):
+ GitOrgClaimRequest(provider='github', git_organization=' ')
+
+ def test_git_organization_is_normalized_to_lowercase(self):
+ """git_organization is lowercased to prevent case-sensitive duplicates."""
+ from server.routes.org_models import GitOrgClaimRequest
+
+ req = GitOrgClaimRequest(provider='github', git_organization='OpenHands')
+ assert req.git_organization == 'openhands'
+
+
+# =============================================================================
+# Integration tests β€” TestClient with real HTTP, auth, and Pydantic validation
+# =============================================================================
+
+
+def mock_app():
+ """FastAPI app with org routes and mocked user authentication."""
+ app = FastAPI()
+ app.include_router(org_router)
+
+ app.dependency_overrides[get_user_id] = lambda: TEST_USER_ID
+ return app
+
+
+def mock_owner_role():
+ role = MagicMock()
+ role.name = 'owner'
+ return role
+
+
+def mock_member_role():
+ role = MagicMock()
+ role.name = 'member'
+ return role
+
+
+class TestGitClaimsAuthorization:
+ """Integration tests verifying authorization through the real HTTP cycle."""
+
+ def test_non_member_gets_403_on_get(self, mock_app):
+ """
+ GIVEN: A user who is not a member of the target organization
+ WHEN: GET /api/organizations/{org_id}/git-claims via HTTP
+ THEN: 403 is returned by require_permission
+ """
+ org_id = uuid.uuid4()
+
+ with patch(
+ 'server.auth.authorization.get_user_org_role',
+ AsyncMock(return_value=None),
+ ):
+ client = TestClient(mock_app)
+ response = client.get(f'/api/organizations/{org_id}/git-claims')
+
+ assert response.status_code == status.HTTP_403_FORBIDDEN
+ assert 'not a member' in response.json()['detail']
+
+ def test_member_without_permission_gets_403_on_post(
+ self, mock_app, mock_member_role
+ ):
+ """
+ GIVEN: A user with member role (lacks MANAGE_ORG_CLAIMS)
+ WHEN: POST /api/organizations/{org_id}/git-claims via HTTP
+ THEN: 403 is returned by require_permission
+ """
+ org_id = uuid.uuid4()
+
+ with patch(
+ 'server.auth.authorization.get_user_org_role',
+ AsyncMock(return_value=mock_member_role),
+ ):
+ client = TestClient(mock_app)
+ response = client.post(
+ f'/api/organizations/{org_id}/git-claims',
+ json={'provider': 'github', 'git_organization': 'SomeOrg'},
+ )
+
+ assert response.status_code == status.HTTP_403_FORBIDDEN
+ assert 'manage_org_claims' in response.json()['detail']
+
+ def test_member_without_permission_gets_403_on_delete(
+ self, mock_app, mock_member_role
+ ):
+ """
+ GIVEN: A user with member role (lacks MANAGE_ORG_CLAIMS)
+ WHEN: DELETE /api/organizations/{org_id}/git-claims/{claim_id} via HTTP
+ THEN: 403 is returned by require_permission
+ """
+ org_id = uuid.uuid4()
+ claim_id = uuid.uuid4()
+
+ with patch(
+ 'server.auth.authorization.get_user_org_role',
+ AsyncMock(return_value=mock_member_role),
+ ):
+ client = TestClient(mock_app)
+ response = client.delete(
+ f'/api/organizations/{org_id}/git-claims/{claim_id}'
+ )
+
+ assert response.status_code == status.HTTP_403_FORBIDDEN
+ assert 'manage_org_claims' in response.json()['detail']
+
+
+class TestGitClaimsHTTPIntegration:
+ """Integration tests for the full request/response cycle via TestClient."""
+
+ def test_post_claim_with_invalid_provider_returns_422(
+ self, mock_app, mock_owner_role
+ ):
+ """
+ GIVEN: A request with an unsupported provider
+ WHEN: POST /api/organizations/{org_id}/git-claims via HTTP
+ THEN: 422 is returned by Pydantic validation
+ """
+ org_id = uuid.uuid4()
+
+ with patch(
+ 'server.auth.authorization.get_user_org_role',
+ AsyncMock(return_value=mock_owner_role),
+ ):
+ client = TestClient(mock_app)
+ response = client.post(
+ f'/api/organizations/{org_id}/git-claims',
+ json={'provider': 'azure_devops', 'git_organization': 'test'},
+ )
+
+ assert response.status_code == status.HTTP_422_UNPROCESSABLE_ENTITY
+
+ def test_post_claim_success_returns_201(self, mock_app, mock_owner_role):
+ """
+ GIVEN: A valid claim request by an authorized admin/owner
+ WHEN: POST /api/organizations/{org_id}/git-claims via HTTP
+ THEN: 201 is returned with the claim details
+ """
+ org_id = uuid.uuid4()
+ mock_claim = MagicMock(spec=OrgGitClaim)
+ mock_claim.id = uuid.uuid4()
+ mock_claim.org_id = org_id
+ mock_claim.provider = 'github'
+ mock_claim.git_organization = 'openhands'
+ mock_claim.claimed_by = uuid.UUID(TEST_USER_ID)
+ mock_claim.claimed_at = datetime(2026, 4, 1, 12, 0, 0)
+
+ with (
+ patch(
+ 'server.auth.authorization.get_user_org_role',
+ AsyncMock(return_value=mock_owner_role),
+ ),
+ patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claim_by_provider_and_git_org',
+ AsyncMock(return_value=None),
+ ),
+ patch(
+ 'server.routes.orgs.OrgGitClaimStore.create_claim',
+ AsyncMock(return_value=mock_claim),
+ ),
+ ):
+ client = TestClient(mock_app)
+ response = client.post(
+ f'/api/organizations/{org_id}/git-claims',
+ json={'provider': 'github', 'git_organization': 'OpenHands'},
+ )
+
+ assert response.status_code == status.HTTP_201_CREATED
+ data = response.json()
+ assert data['org_id'] == str(org_id)
+ assert data['provider'] == 'github'
+ assert data['git_organization'] == 'openhands'
+
+ def test_delete_claim_success_returns_200(self, mock_app, mock_owner_role):
+ """
+ GIVEN: A valid disconnect request by an authorized admin/owner
+ WHEN: DELETE /api/organizations/{org_id}/git-claims/{claim_id} via HTTP
+ THEN: 200 is returned with a success message
+ """
+ org_id = uuid.uuid4()
+ claim_id = uuid.uuid4()
+
+ with (
+ patch(
+ 'server.auth.authorization.get_user_org_role',
+ AsyncMock(return_value=mock_owner_role),
+ ),
+ patch(
+ 'server.routes.orgs.OrgGitClaimStore.delete_claim',
+ AsyncMock(return_value=True),
+ ),
+ ):
+ client = TestClient(mock_app)
+ response = client.delete(
+ f'/api/organizations/{org_id}/git-claims/{claim_id}'
+ )
+
+ assert response.status_code == status.HTTP_200_OK
+ assert (
+ response.json()['message'] == 'Git organization claim removed successfully'
+ )
+
+ def test_get_claims_success_returns_200(self, mock_app, mock_owner_role):
+ """
+ GIVEN: An authorized user requests claims for their organization
+ WHEN: GET /api/organizations/{org_id}/git-claims via HTTP
+ THEN: 200 is returned with the list of claims
+ """
+ org_id = uuid.uuid4()
+ mock_claim = MagicMock(spec=OrgGitClaim)
+ mock_claim.id = uuid.uuid4()
+ mock_claim.org_id = org_id
+ mock_claim.provider = 'github'
+ mock_claim.git_organization = 'openhands'
+ mock_claim.claimed_by = uuid.UUID(TEST_USER_ID)
+ mock_claim.claimed_at = datetime(2026, 4, 1, 12, 0, 0)
+
+ with (
+ patch(
+ 'server.auth.authorization.get_user_org_role',
+ AsyncMock(return_value=mock_owner_role),
+ ),
+ patch(
+ 'server.routes.orgs.OrgGitClaimStore.get_claims_by_org_id',
+ AsyncMock(return_value=[mock_claim]),
+ ),
+ ):
+ client = TestClient(mock_app)
+ response = client.get(f'/api/organizations/{org_id}/git-claims')
+
+ assert response.status_code == status.HTTP_200_OK
+ data = response.json()
+ assert len(data) == 1
+ assert data[0]['provider'] == 'github'
+ assert data[0]['git_organization'] == 'openhands'
diff --git a/enterprise/tests/unit/storage/test_org_git_claim_store.py b/enterprise/tests/unit/storage/test_org_git_claim_store.py
new file mode 100644
index 0000000000..1bd92f6ca2
--- /dev/null
+++ b/enterprise/tests/unit/storage/test_org_git_claim_store.py
@@ -0,0 +1,210 @@
+"""Tests for OrgGitClaimStore with real in-memory SQLite database.
+
+Covers CRUD operations and unique constraint enforcement.
+"""
+
+import uuid
+from unittest.mock import patch
+
+import pytest
+from sqlalchemy.exc import IntegrityError
+from storage.org import Org
+from storage.org_git_claim_store import OrgGitClaimStore
+from storage.org_member import OrgMember
+from storage.role import Role
+from storage.user import User
+
+
+async def seed_org_and_user(async_session_maker):
+ """Create a minimal org, role, user, and org_member for FK satisfaction."""
+ org_id = uuid.uuid4()
+ user_id = uuid.uuid4()
+ role_id = 1
+
+ async with async_session_maker() as session:
+ session.add(Role(id=role_id, name='owner', rank=10))
+ session.add(Org(id=org_id, name='test-org'))
+ session.add(User(id=user_id, current_org_id=org_id, role_id=role_id))
+ session.add(
+ OrgMember(
+ org_id=org_id,
+ user_id=user_id,
+ role_id=role_id,
+ status='active',
+ llm_api_key='test-key',
+ )
+ )
+ await session.commit()
+
+ return org_id, user_id
+
+
+class TestOrgGitClaimStoreCreate:
+ """Tests for OrgGitClaimStore.create_claim."""
+
+ @pytest.mark.asyncio
+ async def test_create_claim_persists_and_returns(
+ self, async_session_maker, seed_org_and_user
+ ):
+ """A new claim is persisted with correct fields and returned."""
+ org_id, user_id = seed_org_and_user
+
+ with patch('storage.org_git_claim_store.a_session_maker', async_session_maker):
+ claim = await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider='github',
+ git_organization='OpenHands',
+ claimed_by=user_id,
+ )
+
+ assert claim.org_id == org_id
+ assert claim.provider == 'github'
+ assert claim.git_organization == 'OpenHands'
+ assert claim.claimed_by == user_id
+ assert claim.claimed_at is not None
+
+ @pytest.mark.asyncio
+ async def test_create_duplicate_raises_integrity_error(
+ self, async_session_maker, seed_org_and_user
+ ):
+ """Creating a duplicate (provider, git_organization) violates the unique constraint."""
+ org_id, user_id = seed_org_and_user
+
+ with patch('storage.org_git_claim_store.a_session_maker', async_session_maker):
+ await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider='github',
+ git_organization='DuplicateOrg',
+ claimed_by=user_id,
+ )
+
+ with pytest.raises(IntegrityError):
+ await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider='github',
+ git_organization='DuplicateOrg',
+ claimed_by=user_id,
+ )
+
+
+class TestOrgGitClaimStoreLookup:
+ """Tests for OrgGitClaimStore lookup methods."""
+
+ @pytest.mark.asyncio
+ async def test_get_claim_by_provider_and_git_org_found(
+ self, async_session_maker, seed_org_and_user
+ ):
+ """Returns the claim when provider+git_organization exists."""
+ org_id, user_id = seed_org_and_user
+
+ with patch('storage.org_git_claim_store.a_session_maker', async_session_maker):
+ await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider='gitlab',
+ git_organization='MyGroup',
+ claimed_by=user_id,
+ )
+
+ result = await OrgGitClaimStore.get_claim_by_provider_and_git_org(
+ provider='gitlab', git_organization='MyGroup'
+ )
+
+ assert result is not None
+ assert result.provider == 'gitlab'
+ assert result.git_organization == 'MyGroup'
+
+ @pytest.mark.asyncio
+ async def test_get_claim_by_provider_and_git_org_not_found(
+ self, async_session_maker
+ ):
+ """Returns None when no matching claim exists."""
+ with patch('storage.org_git_claim_store.a_session_maker', async_session_maker):
+ result = await OrgGitClaimStore.get_claim_by_provider_and_git_org(
+ provider='github', git_organization='NonExistent'
+ )
+
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_get_claims_by_org_id(self, async_session_maker, seed_org_and_user):
+ """Returns all claims belonging to the given org."""
+ org_id, user_id = seed_org_and_user
+
+ with patch('storage.org_git_claim_store.a_session_maker', async_session_maker):
+ await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider='github',
+ git_organization='Org1',
+ claimed_by=user_id,
+ )
+ await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider='gitlab',
+ git_organization='Org2',
+ claimed_by=user_id,
+ )
+
+ claims = await OrgGitClaimStore.get_claims_by_org_id(org_id)
+
+ assert len(claims) == 2
+
+
+class TestOrgGitClaimStoreDelete:
+ """Tests for OrgGitClaimStore.delete_claim."""
+
+ @pytest.mark.asyncio
+ async def test_delete_existing_claim_returns_true(
+ self, async_session_maker, seed_org_and_user
+ ):
+ """Deleting an existing claim returns True and removes it from the DB."""
+ org_id, user_id = seed_org_and_user
+
+ with patch('storage.org_git_claim_store.a_session_maker', async_session_maker):
+ claim = await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider='github',
+ git_organization='ToDelete',
+ claimed_by=user_id,
+ )
+
+ result = await OrgGitClaimStore.delete_claim(
+ claim_id=claim.id, org_id=org_id
+ )
+
+ assert result is True
+
+ @pytest.mark.asyncio
+ async def test_delete_nonexistent_claim_returns_false(
+ self, async_session_maker, seed_org_and_user
+ ):
+ """Deleting a claim that doesn't exist returns False."""
+ org_id, _ = seed_org_and_user
+
+ with patch('storage.org_git_claim_store.a_session_maker', async_session_maker):
+ result = await OrgGitClaimStore.delete_claim(
+ claim_id=uuid.uuid4(), org_id=org_id
+ )
+
+ assert result is False
+
+ @pytest.mark.asyncio
+ async def test_delete_claim_wrong_org_returns_false(
+ self, async_session_maker, seed_org_and_user
+ ):
+ """Deleting a claim with a mismatched org_id returns False."""
+ org_id, user_id = seed_org_and_user
+
+ with patch('storage.org_git_claim_store.a_session_maker', async_session_maker):
+ claim = await OrgGitClaimStore.create_claim(
+ org_id=org_id,
+ provider='github',
+ git_organization='WrongOrg',
+ claimed_by=user_id,
+ )
+
+ result = await OrgGitClaimStore.delete_claim(
+ claim_id=claim.id, org_id=uuid.uuid4()
+ )
+
+ assert result is False