Implementation:OpenHands OpenHands Integration Router Pattern

Knowledge Sources	OpenHands
Domains	Server_Architecture, SaaS_Infrastructure
Last Updated	2026-02-11 21:00 GMT

Overview

Concrete tool for conditionally including integration-specific API routers based on environment variable flags during server assembly, provided by the OpenHands enterprise server layer.

Description

The Integration Router Pattern is implemented in the SaaS server assembly module where each third-party integration router is mounted only when its corresponding environment variable or configuration flag is set. The pattern checks for the presence of credentials such as GITHUB_APP_CLIENT_ID, GITLAB_APP_CLIENT_ID, and feature flags like ENABLE_JIRA before calling app.include_router() for the respective integration. Each integration router is a standard FastAPI APIRouter instance that encapsulates all endpoints for that integration, including OAuth flows, webhook handlers, and CRUD operations. When a credential is not configured, the router is simply not mounted, and those endpoints do not exist in the running application.

Usage

Use this pattern during SaaS server assembly to selectively enable integration endpoints. Each integration module exports a router that can be independently tested and developed. The conditional mounting occurs in the server startup sequence and determines the final API surface of the deployed application.

Code Reference

Source Location

• Repository: OpenHands
• File: enterprise/saas_server.py:L68-100

Signature

# Conditional router inclusion based on environment variables
if os.environ.get("GITHUB_APP_CLIENT_ID"):
    from enterprise.server.routes.github_integration import router as github_integration_router
    base_app.include_router(github_integration_router)

if os.environ.get("GITLAB_APP_CLIENT_ID"):
    from enterprise.server.routes.gitlab_integration import router as gitlab_integration_router
    base_app.include_router(gitlab_integration_router)

if os.environ.get("ENABLE_JIRA"):
    from enterprise.server.routes.jira_integration import router as jira_integration_router
    base_app.include_router(jira_integration_router)

Import

import os
from enterprise.server.routes.github_integration import router as github_integration_router
from enterprise.server.routes.gitlab_integration import router as gitlab_integration_router
from enterprise.server.routes.jira_integration import router as jira_integration_router

I/O Contract

Inputs

Name	Type	Required	Description
GITHUB_APP_CLIENT_ID	str (env var)	No	GitHub OAuth App client ID; if set, the GitHub integration router is mounted
GITLAB_APP_CLIENT_ID	str (env var)	No	GitLab OAuth App client ID; if set, the GitLab integration router is mounted
ENABLE_JIRA	str (env var)	No	Feature flag to enable Jira integration; if set, the Jira integration router is mounted
base_app	FastAPI	Yes	The FastAPI application instance to mount routers onto

Outputs

Name	Type	Description
base_app	FastAPI	The FastAPI application with integration routers conditionally mounted

Usage Examples

Basic Usage

import os
from fastapi import FastAPI

base_app = FastAPI()

# Mount GitHub integration only if credentials are configured
if os.environ.get("GITHUB_APP_CLIENT_ID"):
    from enterprise.server.routes.github_integration import router as github_router
    base_app.include_router(github_router)

# Mount GitLab integration only if credentials are configured
if os.environ.get("GITLAB_APP_CLIENT_ID"):
    from enterprise.server.routes.gitlab_integration import router as gitlab_router
    base_app.include_router(gitlab_router)

# Mount Jira integration only if feature flag is enabled
if os.environ.get("ENABLE_JIRA"):
    from enterprise.server.routes.jira_integration import router as jira_router
    base_app.include_router(jira_router)

Related Pages

Implements Principle

• Principle:OpenHands_OpenHands_Integration_Router_Mounting