Add Azure DevOps support as alternative project source provider

- Add Microsoft Entra ID authentication via next-auth
- Implement AzureDevOpsClient for REST API interactions
- Add AzureDevOpsProjectDataSource and AzureDevOpsRepositoryDataSource
- Create unified IBlobProvider interface for file content fetching
- Support binary image files in blob API
- Configure via PROJECT_SOURCE_PROVIDER env var (github or azure-devops)

Author: ulrikandersen

.env.example

@@ -15,13 +15,26 @@ HIDDEN_REPOSITORIES=
 NEW_PROJECT_TEMPLATE_REPOSITORY=shapehq/starter-openapi
 PROXY_API_MAXIMUM_FILE_SIZE_IN_MEGABYTES = 10
 PROXY_API_TIMEOUT_IN_SECONDS = 30
+
+# Project Source Provider: "github" or "azure-devops" (default: github)
+PROJECT_SOURCE_PROVIDER=github
+
+# GitHub Configuration (required if PROJECT_SOURCE_PROVIDER=github)
 GITHUB_WEBHOOK_SECRET=preshared secret also put in app configuration in GitHub
 GITHUB_WEBHOK_REPOSITORY_ALLOWLIST=
 GITHUB_WEBHOK_REPOSITORY_DISALLOWLIST=
 GITHUB_CLIENT_ID=GitHub App client ID
 GITHUB_CLIENT_SECRET=GitHub App client secret
 GITHUB_APP_ID=123456
 GITHUB_PRIVATE_KEY_BASE_64=base 64 encoded version of the private key - see README.md for more info
+
+# Azure DevOps Configuration (required if PROJECT_SOURCE_PROVIDER=azure-devops)
+# Uses Microsoft Entra ID (Azure AD) for authentication
+AZURE_ENTRA_ID_CLIENT_ID=Microsoft Entra ID App Registration client ID
+AZURE_ENTRA_ID_CLIENT_SECRET=Microsoft Entra ID App Registration client secret
+AZURE_ENTRA_ID_TENANT_ID=Microsoft Entra ID tenant/directory ID
+AZURE_DEVOPS_ORGANIZATION=your-azure-devops-organization-name
+
 ENCRYPTION_PUBLIC_KEY_BASE_64=base 64 encoded version of the public key
 ENCRYPTION_PRIVATE_KEY_BASE_64=base 64 encoded version of the private key
 NEXT_PUBLIC_ENABLE_DIFF_SIDEBAR=true

src/app/api/blob/[owner]/[repository]/[...path]/route.ts

@@ -1,30 +1,32 @@
 import { NextRequest, NextResponse } from "next/server"
-import { session, userGitHubClient } from "@/composition"
+import { session, blobProvider } from "@/composition"
 import { makeUnauthenticatedAPIErrorResponse } from "@/common"
 
-export async function GET(req: NextRequest, { params }: { params: Promise<{ owner: string; repository: string; path: string[] }> }) {
+export async function GET(
+  req: NextRequest,
+  { params }: { params: Promise<{ owner: string; repository: string; path: string[] }> }
+) {
   const isAuthenticated = await session.getIsAuthenticated()
   if (!isAuthenticated) {
     return makeUnauthenticatedAPIErrorResponse()
   }
   const { path: paramsPath, owner, repository } = await params
   const path = paramsPath.join("/")
-  const item = await userGitHubClient.getRepositoryContent({
-    repositoryOwner: owner,
-    repositoryName: repository,
-    path: path,
-    ref: req.nextUrl.searchParams.get("ref") ?? undefined
-  })
-  const url = new URL(item.downloadURL)
-  const imageRegex = /\.(jpg|jpeg|png|webp|avif|gif)$/;
-  const file = await fetch(url).then(r => r.blob())
+  const ref = req.nextUrl.searchParams.get("ref") ?? "main"
+
+  const content = await blobProvider.getFileContent(owner, repository, path, ref)
+  if (content === null) {
+    return NextResponse.json({ error: `File not found: ${path}` }, { status: 404 })
+  }
+
   const headers = new Headers()
-  if (new RegExp(imageRegex).exec(path)) {
+  const imageRegex = /\.(jpg|jpeg|png|webp|avif|gif)$/
+  if (imageRegex.test(path)) {
     const cacheExpirationInSeconds = 60 * 60 * 24 * 30 // 30 days
-    headers.set("Content-Type", "image/*");
+    headers.set("Content-Type", "image/*")
     headers.set("Cache-Control", `max-age=${cacheExpirationInSeconds}`)
   } else {
-    headers.set("Content-Type", "text/plain");
+    headers.set("Content-Type", "text/plain")
   }
-  return new NextResponse(file, { status: 200, headers })
+  return new NextResponse(content, { status: 200, headers })
 }

src/app/api/hooks/github/route.ts

@@ -2,6 +2,12 @@ import { NextRequest, NextResponse } from "next/server"
 import { gitHubHookHandler } from "@/composition"
 
 export const POST = async (req: NextRequest): Promise<NextResponse> => {
+  if (!gitHubHookHandler) {
+    return NextResponse.json(
+      { error: "GitHub webhooks not available" },
+      { status: 404 }
+    )
+  }
   await gitHubHookHandler.handle(req)
   return NextResponse.json({ status: "OK" })
 }

src/app/auth/signin/page.tsx

@@ -3,12 +3,13 @@ import { Box, Button, Stack, Typography } from "@mui/material"
 import { signIn } from "@/composition"
 import { env } from "@/common"
 import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
-import { faGithub } from "@fortawesome/free-brands-svg-icons"
+import { faGithub, faMicrosoft } from "@fortawesome/free-brands-svg-icons"
 import SignInTexts from "@/features/auth/view/SignInTexts"
 import MessageLinkFooter from "@/common/ui/MessageLinkFooter"
 
 const SITE_NAME = env.getOrThrow("FRAMNA_DOCS_TITLE")
 const HELP_URL = env.get("FRAMNA_DOCS_HELP_URL")
+const PROJECT_SOURCE_PROVIDER = env.get("PROJECT_SOURCE_PROVIDER") || "github"
 
 // Force page to be rendered dynamically to ensure we read the correct values for the environment variables.
 export const dynamic = "force-dynamic"
@@ -74,7 +75,7 @@ const SignInColumn = () => {
           }}>
             {title}
           </Typography>
-          <SignInWithGitHub />
+          <SignInButton />
         </Stack>
       </Box>
       {HELP_URL && (
@@ -89,20 +90,25 @@ const SignInColumn = () => {
   )
 }
 
-const SignInWithGitHub = () => {
+const SignInButton = () => {
+  const isAzureDevOps = PROJECT_SOURCE_PROVIDER === "azure-devops"
+  const providerId = isAzureDevOps ? "microsoft-entra-id" : "github"
+  const providerName = isAzureDevOps ? "Microsoft" : "GitHub"
+  const providerIcon = isAzureDevOps ? faMicrosoft : faGithub
+
   return (
     <form
       action={async () => {
         "use server"
-          await signIn("github", { redirectTo: "/" })
+        await signIn(providerId, { redirectTo: "/" })
       }}
     >
       <Button variant="outlined" type="submit">
         <Stack direction="row" alignItems="center" spacing={1} padding={1}>
-          <FontAwesomeIcon icon={faGithub} size="2xl" />
-            <Typography variant="h6" sx={{ display: "flex" }}>
-              Sign in with GitHub
-            </Typography>
+          <FontAwesomeIcon icon={providerIcon} size="2xl" />
+          <Typography variant="h6" sx={{ display: "flex" }}>
+            Sign in with {providerName}
+          </Typography>
         </Stack>
       </Button>
     </form>

src/common/azure-devops/AzureDevOpsClient.ts

@@ -0,0 +1,135 @@
+import IAzureDevOpsClient, {
+  AzureDevOpsRepository,
+  AzureDevOpsRef,
+  AzureDevOpsItem
+} from "./IAzureDevOpsClient"
+import { AzureDevOpsError } from "./AzureDevOpsError"
+
+interface IOAuthTokenDataSource {
+  getOAuthToken(): Promise<{ accessToken: string }>
+}
+
+type AzureDevOpsApiResponse<T> = {
+  value: T[]
+  count: number
+}
+
+export default class AzureDevOpsClient implements IAzureDevOpsClient {
+  private readonly organization: string
+  private readonly oauthTokenDataSource: IOAuthTokenDataSource
+  private readonly apiVersion = "7.1"
+
+  constructor(config: {
+    organization: string
+    oauthTokenDataSource: IOAuthTokenDataSource
+  }) {
+    this.organization = config.organization
+    this.oauthTokenDataSource = config.oauthTokenDataSource
+  }
+
+  private async fetch<T>(endpoint: string): Promise<T> {
+    const oauthToken = await this.oauthTokenDataSource.getOAuthToken()
+    const url = `https://dev.azure.com/${this.organization}${endpoint}`
+    const separator = endpoint.includes("?") ? "&" : "?"
+    const fullUrl = `${url}${separator}api-version=${this.apiVersion}`
+
+    const response = await fetch(fullUrl, {
+      headers: {
+        Authorization: `Bearer ${oauthToken.accessToken}`,
+        Accept: "application/json"
+      },
+      // Don't follow redirects - Azure DevOps returns 302 for auth failures
+      redirect: "manual"
+    })
+
+    // Check for redirect (302) - Azure DevOps redirects to login on auth failure
+    if (response.status === 302) {
+      const location = response.headers.get("location") || ""
+      // Check if redirecting to a sign-in page (auth error)
+      const isAuthRedirect = location.includes("/_signin") || location.includes("/login")
+      throw new AzureDevOpsError(
+        `Azure DevOps API redirect (302) to: ${location}`,
+        302,
+        isAuthRedirect // only trigger token refresh for auth redirects
+      )
+    }
+
+    // Check for authentication errors (401/403)
+    if (response.status === 401 || response.status === 403) {
+      const text = await response.text()
+      throw new AzureDevOpsError(
+        `Azure DevOps API authentication error: ${response.status} ${response.statusText} - ${text.substring(0, 200)}`,
+        response.status,
+        true // isAuthError - trigger token refresh
+      )
+    }
+
+    if (!response.ok) {
+      const text = await response.text()
+      throw new AzureDevOpsError(
+        `Azure DevOps API error: ${response.status} ${response.statusText} - ${text.substring(0, 200)}`,
+        response.status,
+        false
+      )
+    }
+
+    return await response.json() as T
+  }
+
+  async getRepositories(): Promise<AzureDevOpsRepository[]> {
+    const response = await this.fetch<AzureDevOpsApiResponse<AzureDevOpsRepository>>(
+      "/_apis/git/repositories"
+    )
+    return response.value
+  }
+
+  async getRefs(repositoryId: string): Promise<AzureDevOpsRef[]> {
+    const response = await this.fetch<AzureDevOpsApiResponse<AzureDevOpsRef>>(
+      `/_apis/git/repositories/${repositoryId}/refs`
+    )
+    return response.value
+  }
+
+  async getItems(repositoryId: string, scopePath: string, version: string): Promise<AzureDevOpsItem[]> {
+    try {
+      const response = await this.fetch<AzureDevOpsApiResponse<AzureDevOpsItem>>(
+        `/_apis/git/repositories/${repositoryId}/items?scopePath=${encodeURIComponent(scopePath)}&recursionLevel=OneLevel&versionDescriptor.version=${encodeURIComponent(version)}`
+      )
+      return response.value
+    } catch {
+      return []
+    }
+  }
+
+  private isImageFile(path: string): boolean {
+    const imageExtensions = [".jpg", ".jpeg", ".png", ".gif", ".webp", ".avif", ".svg", ".ico"]
+    const lowerPath = path.toLowerCase()
+    return imageExtensions.some(ext => lowerPath.endsWith(ext))
+  }
+
+  async getFileContent(repositoryId: string, path: string, version: string): Promise<string | ArrayBuffer | null> {
+    try {
+      const oauthToken = await this.oauthTokenDataSource.getOAuthToken()
+      const url = `https://dev.azure.com/${this.organization}/_apis/git/repositories/${repositoryId}/items?path=${encodeURIComponent(path)}&versionDescriptor.version=${encodeURIComponent(version)}&api-version=${this.apiVersion}`
+
+      const isImage = this.isImageFile(path)
+      const response = await fetch(url, {
+        headers: {
+          Authorization: `Bearer ${oauthToken.accessToken}`,
+          Accept: isImage ? "application/octet-stream" : "text/plain"
+        }
+      })
+
+      if (!response.ok) {
+        return null
+      }
+
+      if (isImage) {
+        return await response.arrayBuffer()
+      }
+      return await response.text()
+    } catch {
+      return null
+    }
+  }
+}

src/common/azure-devops/AzureDevOpsError.ts

@@ -0,0 +1,16 @@
+/**
+ * Error thrown by Azure DevOps API client when requests fail.
+ * Includes HTTP status code for proper error handling.
+ */
+export class AzureDevOpsError extends Error {
+  readonly status: number
+  readonly isAuthError: boolean
+
+  constructor(message: string, status: number, isAuthError: boolean) {
+    super(message)
+    this.name = "AzureDevOpsError"
+    this.status = status
+    this.isAuthError = isAuthError
+  }
+}
+

src/common/azure-devops/IAzureDevOpsClient.ts

@@ -0,0 +1,27 @@
+export type AzureDevOpsRepository = {
+  readonly id: string
+  readonly name: string
+  readonly defaultBranch?: string
+  readonly webUrl: string
+  readonly project: {
+    readonly id: string
+    readonly name: string
+  }
+}
+
+export type AzureDevOpsRef = {
+  readonly name: string // e.g., "refs/heads/main"
+  readonly objectId: string
+}
+
+export type AzureDevOpsItem = {
+  readonly path: string
+  readonly gitObjectType: "blob" | "tree"
+}
+
+export default interface IAzureDevOpsClient {
+  getRepositories(): Promise<AzureDevOpsRepository[]>
+  getRefs(repositoryId: string): Promise<AzureDevOpsRef[]>
+  getItems(repositoryId: string, scopePath: string, version: string): Promise<AzureDevOpsItem[]>
+  getFileContent(repositoryId: string, path: string, version: string): Promise<string | ArrayBuffer | null>
+}