Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

6.3 KB
Raw Blame
from typing import Optional, cast

from products.warehouse_sources.sources.linear._config import LinearSourceConfig
from products.warehouse_sources.sources.linear.linear import (
    LinearResumeConfig,
    linear_source,
    validate_credentials as validate_linear_credentials,
)
from products.warehouse_sources.sources.linear.settings import ENDPOINTS, INCREMENTAL_FIELDS, SHOULD_SYNC_DEFAULT
from products.warehouse_sources.sources.sdk import (
    CanonicalDescriptions,
    DataWarehouseSourceCategory,
    ExternalDataSourceType,
    FieldType,
    OauthIntegration,
    OAuthMixin,
    ReleaseStatus,
    ResumableSource,
    ResumableSourceManager,
    SourceConfig,
    SourceFieldOauthConfig,
    SourceInputs,
    SourceRegistry,
    SourceResponse,
    SourceSchema,
    build_endpoint_schemas,
    detect,
)


@SourceRegistry.register
class LinearSource(ResumableSource[LinearSourceConfig, LinearResumeConfig], OAuthMixin):
    codebase_detection = detect(
        env=(
            "^LINEAR_API_KEY$",
            "^LINEAR_WEBHOOK_SECRET$",
            "^LINEAR_CLIENT_ID$",
            "^LINEAR_CLIENT_SECRET$",
            "^LINEAR_ACCESS_KEY$",
            "^LINEAR_WEBHOOK_SIGNING_SECRET$",
        ),
        npm=("@linear/sdk", "@linear/import", "@linear/cli"),
    )

    api_docs_url = "https://developers.linear.app/docs"

    lists_tables_without_credentials = True  # static endpoint catalog — safe for public docs

    @property
    def source_type(self) -> ExternalDataSourceType:
        return ExternalDataSourceType.LINEAR

    @property
    def get_source_config(self) -> SourceConfig:
        return SourceConfig(
            name=ExternalDataSourceType.LINEAR,
            category=DataWarehouseSourceCategory.PRODUCTIVITY,
            label="Linear",
            releaseStatus=ReleaseStatus.GA,
            caption="Connect your Linear workspace to sync issues, projects, teams, and more.",
            iconPath="/static/services/linear.png",
            fields=cast(
                list[FieldType],
                [
                    SourceFieldOauthConfig(
                        name="linear_integration_id",
                        label="Linear account",
                        required=True,
                        kind="linear",
                    ),
                ],
            ),
        )

    def get_canonical_descriptions(self) -> CanonicalDescriptions:
        from products.warehouse_sources.sources.linear.canonical_descriptions import CANONICAL_DESCRIPTIONS

        return CANONICAL_DESCRIPTIONS

    def get_non_retryable_errors(self) -> dict[str, str | None]:
        return {
            "401 Client Error": "Invalid Linear credentials. Please reconnect your account.",
            "403 Client Error": "Access forbidden. Your token may lack required permissions.",
            # The linked OAuth integration was deleted while the source still references it.
            # Retrying can never resolve this — the integration won't reappear — so stop and
            # ask the user to reconnect. Matched as a substring; the trailing integration id varies.
            "Integration not found": "The linked Linear integration no longer exists. Please reconnect your Linear account.",
            # "Linear app not configured" is not here on purpose. It means the worker that ran the job
            # has no Linear client credentials, which is a PostHog fault that the customer can't fix,
            # so it must not disable the schema.
        }

    def get_retryable_errors(self) -> set[str]:
        # linear.py's own tenacity retry already rides out 5xx, 429, GraphQL-wrapped internal
        # errors and transient network blips (LINEAR_MAX_RETRY_ATTEMPTS attempts with backoff).
        # A LinearRetryableError only reaches here once that in-process budget is exhausted, so
        # Temporal retrying the whole activity is the self-recovering next step, not a bug to page on.
        return {
            "Linear: server error",
            "Linear: rate limited",
            "Linear: internal server error",
            "Linear: transient network error",
            "Linear: incomplete JSON response",
        }

    def _get_access_token(self, config: LinearSourceConfig, team_id: int) -> str:
        integration = self.get_oauth_integration(config.linear_integration_id, team_id)

        oauth_integration = OauthIntegration(integration)
        if oauth_integration.access_token_expired():
            oauth_integration.refresh_access_token()

        if not integration.access_token:
            raise ValueError("Linear access token not found")
        return integration.access_token

    def get_schemas(
        self,
        config: LinearSourceConfig,
        team_id: int,
        with_counts: bool = False,
        names: list[str] | None = None,
        force_refresh: bool = False,
        api_version: str | None = None,
    ) -> list[SourceSchema]:
        return build_endpoint_schemas(
            ENDPOINTS,
            INCREMENTAL_FIELDS,
            names,
            should_sync_default=SHOULD_SYNC_DEFAULT,
        )

    def validate_credentials(
        self,
        config: LinearSourceConfig,
        team_id: int,
        schema_name: Optional[str] = None,
        api_version: str | None = None,
    ) -> tuple[bool, str | None]:
        try:
            access_token = self._get_access_token(config, team_id)
            return validate_linear_credentials(access_token)
        except Exception as e:
            return False, str(e)

    def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[LinearResumeConfig]:
        return ResumableSourceManager[LinearResumeConfig](inputs, LinearResumeConfig)

    def source_for_pipeline(
        self,
        config: LinearSourceConfig,
        resumable_source_manager: ResumableSourceManager[LinearResumeConfig],
        inputs: SourceInputs,
    ) -> SourceResponse:
        access_token = self._get_access_token(config, inputs.team_id)

        return linear_source(
            access_token=access_token,
            endpoint_name=inputs.schema_name,
            logger=inputs.logger,
            resumable_source_manager=resumable_source_manager,
            should_use_incremental_field=inputs.should_use_incremental_field,
            db_incremental_field_last_value=inputs.db_incremental_field_last_value
            if inputs.should_use_incremental_field
            else None,
        )