⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
feat: separate github sso and integration
Tindc4c67dd45c8
diff --git a/.env.sample b/.env.sampleindex f17a843e5..5befc6230 100644--- a/.env.sample+++ b/.env.sample@@ -11,12 +11,18 @@ POSTGRES_PASSWORD=# AuthenticationAUTH_SECRET=-# GitHub SSO & Integration+# GitHub SSO (Sign in with GitHub — OAuth App)+GITHUB_OAUTH_CLIENT_ID=+GITHUB_OAUTH_CLIENT_SECRET=+# Legacy fallback for SSO (used only if GITHUB_OAUTH_* are unset)GITHUB_CLIENT_ID=GITHUB_CLIENT_SECRET=++# GitHub integration (GitHub App — repository sync, webhooks)GITHUB_APP_ID=GITHUB_WEBHOOK_SECRET=GITHUB_PRIVATE_KEY=+GITHUB_APP_NAME=# SMTP ConfigurationSMTP_HOST=diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.mdindex 460cbfe3c..a3a284537 100644--- a/ENVIRONMENT_SETUP.md+++ b/ENVIRONMENT_SETUP.md@@ -43,7 +43,8 @@ For local development, the web app also supports:### Optional VariablesKaneo supports many optional configuration options including:-- SSO providers (GitHub, Google, Discord, Custom OAuth/OIDC)+- SSO providers (GitHub OAuth via `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET`, Google, Discord, Custom OAuth/OIDC)+- GitHub repository integration (GitHub App: `GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY`, `GITHUB_WEBHOOK_SECRET`, optional `GITHUB_APP_NAME`) — separate from GitHub SSO- SMTP configuration for email- Access control settings- CORS configurationdiff --git a/apps/api/src/auth.ts b/apps/api/src/auth.tsindex 50384e085..ea245ea2c 100644--- a/apps/api/src/auth.ts+++ b/apps/api/src/auth.ts@@ -25,9 +25,12 @@ import db, { schema } from "./database";import { publishEvent } from "./events";import { checkRegistrationAllowed } from "./utils/check-registration-allowed";import { generateDemoName } from "./utils/generate-demo-name";+import { getGithubSsoOAuthCredentials } from "./utils/github-sso-env";config();+const githubSso = getGithubSsoOAuthCredentials();+const isRegistrationDisabled = process.env.DISABLE_REGISTRATION === "true";const isPasswordRegistrationDisabled =process.env.DISABLE_PASSWORD_REGISTRATION === "true";@@ -173,8 +176,8 @@ export const auth = betterAuth({},socialProviders: {github: {- clientId: process.env.GITHUB_CLIENT_ID || "",- clientSecret: process.env.GITHUB_CLIENT_SECRET || "",+ clientId: githubSso.clientId,+ clientSecret: githubSso.clientSecret,scope: ["user:email"],},google: {diff --git a/apps/api/src/utils/get-settings.ts b/apps/api/src/utils/get-settings.tsindex 9f5e845a5..eb95099ed 100644--- a/apps/api/src/utils/get-settings.ts+++ b/apps/api/src/utils/get-settings.ts@@ -1,4 +1,5 @@import { config } from "dotenv-mono";+import { isGithubSsoConfigured } from "./github-sso-env";config();@@ -14,9 +15,7 @@ function getSettings() {Boolean(process.env.SMTP_SECURE) &&Boolean(process.env.SMTP_USER) &&Boolean(process.env.SMTP_PASSWORD),- hasGithubSignIn:- Boolean(process.env.GITHUB_CLIENT_ID) &&- Boolean(process.env.GITHUB_CLIENT_SECRET),+ hasGithubSignIn: isGithubSsoConfigured(),hasGoogleSignIn:Boolean(process.env.GOOGLE_CLIENT_ID) &&Boolean(process.env.GOOGLE_CLIENT_SECRET),diff --git a/apps/api/src/utils/github-sso-env.ts b/apps/api/src/utils/github-sso-env.tsnew file mode 100644index 000000000..560d765f1--- /dev/null+++ b/apps/api/src/utils/github-sso-env.ts@@ -0,0 +1,24 @@+/**+ * GitHub "Sign in with GitHub" uses OAuth client credentials.+ * Prefer `GITHUB_OAUTH_*` so GitHub App integration env vars can be set+ * without implicitly enabling SSO. Legacy `GITHUB_CLIENT_*` is still supported.+ */+export function getGithubSsoOAuthCredentials(): {+ clientId: string;+ clientSecret: string;+} {+ const oauthId = process.env.GITHUB_OAUTH_CLIENT_ID?.trim();+ const oauthSecret = process.env.GITHUB_OAUTH_CLIENT_SECRET?.trim();+ if (oauthId && oauthSecret) {+ return { clientId: oauthId, clientSecret: oauthSecret };+ }+ return {+ clientId: process.env.GITHUB_CLIENT_ID?.trim() || "",+ clientSecret: process.env.GITHUB_CLIENT_SECRET?.trim() || "",+ };+}++export function isGithubSsoConfigured(): boolean {+ const { clientId, clientSecret } = getGithubSsoOAuthCredentials();+ return Boolean(clientId && clientSecret);+}diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdxindex 88ddb986e..f1cfd20c1 100644--- a/apps/docs/core/installation/environment-variables.mdx+++ b/apps/docs/core/installation/environment-variables.mdx@@ -15,7 +15,8 @@ The variables are split up into the following sections:- [Authentication](#authentication)- [Object Storage](#object-storage)- [Access Control](#access-control)-- [GitHub SSO & Integration](#github-sso-&-integration)+- [GitHub SSO](#github-sso)+- [GitHub integration](#github-integration)- [Google SSO](#google-sso)- [Discord SSO](#discord-sso)- [Custom OAuth/OIDC](#custom-oauth-oidc)@@ -81,15 +82,27 @@ Name | Description | Default || `DISABLE_REGISTRATION` | Disable public user registration. When set to `true`, the sign-up option will not be shown on the sign-in page and new user creation is blocked (including via SSO). **Note:** Users with valid workspace invitations can still register even when this is enabled. | `false` || `DISABLE_PASSWORD_REGISTRATION` | Disable password-based account creation. When set to `true`, email/password sign-up is blocked, but social/OIDC registration remains available unless `DISABLE_REGISTRATION=true`. | `false` |-### GitHub SSO & Integration+### GitHub SSO++Sign in with GitHub uses a [GitHub OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app). Set `GITHUB_OAUTH_CLIENT_ID` and `GITHUB_OAUTH_CLIENT_SECRET` (or rely on the legacy variables below).++Name | Description |+--- | --- |+| `GITHUB_OAUTH_CLIENT_ID` | OAuth client ID for GitHub sign-in.+| `GITHUB_OAUTH_CLIENT_SECRET` | OAuth client secret for GitHub sign-in.+| `GITHUB_CLIENT_ID` | Legacy fallback for OAuth client ID when `GITHUB_OAUTH_*` is not set.+| `GITHUB_CLIENT_SECRET` | Legacy fallback for OAuth client secret when `GITHUB_OAUTH_*` is not set.++### GitHub integration++Repository sync and webhooks use a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps). These variables do not enable GitHub sign-in; configure [GitHub SSO](#github-sso) separately if you want both.Name | Description |--- | --- |-| `GITHUB_CLIENT_ID` | The GitHub client ID.-| `GITHUB_CLIENT_SECRET` | The GitHub client secret.-| `GITHUB_APP_ID` | The GitHub app ID.-| `GITHUB_WEBHOOK_SECRET` | The GitHub webhook secret.-| `GITHUB_PRIVATE_KEY` | The GitHub private key.+| `GITHUB_APP_ID` | The GitHub App ID.+| `GITHUB_WEBHOOK_SECRET` | Secret used to verify GitHub webhook payloads.+| `GITHUB_PRIVATE_KEY` | PEM private key for the GitHub App (JWT authentication).+| `GITHUB_APP_NAME` | (Optional) GitHub App slug, used for installation links in the UI.### Google SSO@@ -134,7 +147,8 @@ Name | Description |## Key points-- If you enable GitHub SSO, you need to set up the GitHub app which is used to authenticate users in the [GitHub Developer Settings](https://github.com/settings/developers). See the [GitHub SSO guide](/core/social-providers/github).+- If you enable GitHub SSO, create a GitHub OAuth App in [GitHub Developer Settings](https://github.com/settings/developers) and set `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET` (or the legacy `GITHUB_CLIENT_*` variables). See the [GitHub SSO guide](/core/social-providers/github).+- If you use the GitHub repository integration, configure a GitHub App and set the integration variables in [GitHub integration](#github-integration). See the [GitHub integration configuration](/core/integrations/github/configuration) guide.- If you enable Google SSO, you need to set up the Google app which is used to authenticate users in the [Google Cloud Console](https://console.cloud.google.com/). See the [Google SSO guide](/core/social-providers/google).- If you enable Discord SSO, you need to set up the Discord application which is used to authenticate users in the [Discord Developer Portal](https://discord.com/developers/applications). See the [Discord SSO guide](/core/social-providers/discord).- If you enable Custom OAuth/OIDC, you need to configure your identity provider with the appropriate redirect URI. See the [Custom OAuth/OIDC guide](/core/social-providers/custom-oauth).diff --git a/apps/docs/core/integrations/github/configuration.mdx b/apps/docs/core/integrations/github/configuration.mdxindex 2b2bbb060..2850924e6 100644--- a/apps/docs/core/integrations/github/configuration.mdx+++ b/apps/docs/core/integrations/github/configuration.mdx@@ -15,10 +15,8 @@ Make sure you've completed the [GitHub App setup](/core/integrations/github/setuAdd the following environment variables to your Kaneo deployment:```bash-# GitHub App Configuration+# GitHub App (integration only — repository sync, webhooks)GITHUB_APP_ID=123456-GITHUB_CLIENT_ID=Iv1.abc123def456-GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stuGITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEA...[Full contents of your private key]@@ -26,20 +24,22 @@ MIIEpAIBAAKCAQEA...-----END RSA PRIVATE KEY-----"GITHUB_WEBHOOK_SECRET=your-webhook-secret-here-# Optional: GitHub App Name for installation URLs+# Optional: GitHub App slug for installation URLs in the UIGITHUB_APP_NAME=kaneo-your-instance-name```+<Info>+GitHub sign-in uses separate OAuth variables (`GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET`). You can run the integration without enabling GitHub SSO. See [GitHub SSO](/core/social-providers/github) and [Environment variables](/core/installation/environment-variables#github-sso).+</Info>+### Variable Reference| Variable | Description | Required | Example ||----------|-------------|----------|---------|| `GITHUB_APP_ID` | Your GitHub App's ID | ✅ | `123456` |-| `GITHUB_CLIENT_ID` | OAuth client ID from your app | ✅ | `Iv1.abc123def456` |-| `GITHUB_CLIENT_SECRET` | OAuth client secret | ✅ | `abc123def456ghi789jkl012mno345pqr678stu` || `GITHUB_PRIVATE_KEY` | Full private key content (with newlines) | ✅ | `-----BEGIN RSA...` || `GITHUB_WEBHOOK_SECRET` | Secret for webhook verification | ✅ | `your-secret` |-| `GITHUB_APP_NAME` | App name for installation URLs | ⚠️ | `kaneo-mycompany` |+| `GITHUB_APP_NAME` | App slug for installation URLs in the UI | ⚠️ | `kaneo-mycompany` |<Warning>`GITHUB_APP_NAME` is optional but recommended. It's used to generate direct installation links in the UI.@@ -58,8 +58,6 @@ services:environment:# ... other environment variablesGITHUB_APP_ID: "123456"- GITHUB_CLIENT_ID: "Iv1.abc123def456"- GITHUB_CLIENT_SECRET: "abc123def456ghi789jkl012mno345pqr678stu"GITHUB_PRIVATE_KEY: |-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEA...@@ -88,8 +86,6 @@ metadata:type: OpaquestringData:GITHUB_APP_ID: "123456"- GITHUB_CLIENT_ID: "Iv1.abc123def456"- GITHUB_CLIENT_SECRET: "abc123def456ghi789jkl012mno345pqr678stu"GITHUB_PRIVATE_KEY: |-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEA...@@ -125,8 +121,6 @@ For development or simple deployments, create a `.env` file:```bash# .env fileGITHUB_APP_ID=123456-GITHUB_CLIENT_ID=Iv1.abc123def456-GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stuGITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----MIIEpAIBAAKCAQEA...[Full contents of your private key]diff --git a/apps/docs/core/integrations/github/setup.mdx b/apps/docs/core/integrations/github/setup.mdxindex 0b0d68a20..aac805282 100644--- a/apps/docs/core/integrations/github/setup.mdx+++ b/apps/docs/core/integrations/github/setup.mdx@@ -137,13 +137,13 @@ Keep this private key secure! It's used to authenticate your Kaneo instance withFrom the app settings page, note down these important values:- **App ID** (shown at the top of the page)-- **Client ID** (in the "Basic information" section)-- **Client Secret** (click "Generate a new client secret")- **Webhook Secret** (the one you created earlier)- **Private Key** (contents of the downloaded `.pem` file)+The GitHub App also shows an OAuth **Client ID** and **Client Secret** under "Basic information". Kaneo’s **repository integration** does not use those environment variables; they are only relevant if you enable **Sign in with GitHub** using `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET` (see [GitHub SSO](/core/social-providers/github)).+<Info>-You'll need all of these values for the [configuration step](/core/integrations/github/configuration).+You need **App ID**, **private key**, and **webhook secret** for the [configuration step](/core/integrations/github/configuration).</Info></Step></Steps>diff --git a/apps/docs/core/integrations/github/troubleshooting.mdx b/apps/docs/core/integrations/github/troubleshooting.mdxindex 8c201304e..da25f2978 100644--- a/apps/docs/core/integrations/github/troubleshooting.mdx+++ b/apps/docs/core/integrations/github/troubleshooting.mdx@@ -105,10 +105,9 @@ Use the "Browse Repositories" feature in Kaneo to see which repositories your ap**Solutions**:1. **Verify All Variables Are Set**```bash- # Check if environment variables are loaded+ # Check if integration environment variables are loaded (do not print secrets)echo $GITHUB_APP_ID- echo $GITHUB_CLIENT_ID- # etc.+ if [ -n "$GITHUB_WEBHOOK_SECRET" ]; then echo "GITHUB_WEBHOOK_SECRET is set"; else echo "GITHUB_WEBHOOK_SECRET is missing"; fi```2. **Check Private Key Format**@@ -257,11 +256,10 @@ Follow these steps to systematically test your integration:1. **Verify Environment Variables**```bash- # Check that all required variables are set (don't print private key!)+ # Check that all required integration variables are set (don't print private key or webhook secret!)echo "App ID: $GITHUB_APP_ID"- echo "Client ID: $GITHUB_CLIENT_ID"- echo "Webhook Secret: [REDACTED]"echo "App Name: $GITHUB_APP_NAME"+ if [ -n "$GITHUB_WEBHOOK_SECRET" ]; then echo "GITHUB_WEBHOOK_SECRET is set"; else echo "GITHUB_WEBHOOK_SECRET is missing"; fi```2. **Test Repository Access**diff --git a/apps/docs/core/social-providers/github.mdx b/apps/docs/core/social-providers/github.mdxindex 6dc78c3e1..184d30440 100644--- a/apps/docs/core/social-providers/github.mdx+++ b/apps/docs/core/social-providers/github.mdx@@ -13,9 +13,9 @@ GitHub is a social provider for Kaneo. It allows users to sign in to Kaneo using2. Create a new OAuth app.3. Set the redirect URI to `KANEO_API_URL/api/auth/callback/github`.4. Copy the client ID and client secret.-5. Set the `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` environment variables.+5. Set `GITHUB_OAUTH_CLIENT_ID` and `GITHUB_OAUTH_CLIENT_SECRET` (or the legacy `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` if you prefer).-For more information on what your `KANEO_API_URL` is, see the [Environment variables](/core/installation/environment-variables#github-sso--integration) page.+For more information on what your `KANEO_API_URL` is, see the [Environment variables](/core/installation/environment-variables#github-sso) page.## Usagediff --git a/tests/api-integration/setup.ts b/tests/api-integration/setup.tsindex db8273b2c..55c94adf2 100644--- a/tests/api-integration/setup.ts+++ b/tests/api-integration/setup.ts@@ -72,6 +72,8 @@ process.env.SMTP_PORT = "";process.env.SMTP_SECURE = "";process.env.SMTP_USER = "";process.env.SMTP_PASSWORD = "";+process.env.GITHUB_OAUTH_CLIENT_ID = "";+process.env.GITHUB_OAUTH_CLIENT_SECRET = "";process.env.GITHUB_CLIENT_ID = "";process.env.GITHUB_CLIENT_SECRET = "";process.env.GOOGLE_CLIENT_ID = "";diff --git a/tests/api/utils/github-sso-env.test.ts b/tests/api/utils/github-sso-env.test.tsnew file mode 100644index 000000000..1c4ed41be--- /dev/null+++ b/tests/api/utils/github-sso-env.test.ts@@ -0,0 +1,75 @@+import { afterEach, beforeEach, describe, expect, it } from "vitest";+import {+ getGithubSsoOAuthCredentials,+ isGithubSsoConfigured,+} from "../../../apps/api/src/utils/github-sso-env";++const keys = [+ "GITHUB_OAUTH_CLIENT_ID",+ "GITHUB_OAUTH_CLIENT_SECRET",+ "GITHUB_CLIENT_ID",+ "GITHUB_CLIENT_SECRET",+] as const;++describe("github-sso-env", () => {+ const original: Partial<Record<(typeof keys)[number], string | undefined>> =+ {};++ beforeEach(() => {+ for (const key of keys) {+ original[key] = process.env[key];+ delete process.env[key];+ }+ });++ afterEach(() => {+ for (const key of keys) {+ const value = original[key];+ if (value === undefined) {+ delete process.env[key];+ } else {+ process.env[key] = value;+ }+ }+ });++ it("prefers GITHUB_OAUTH_* when both are set", () => {+ process.env.GITHUB_OAUTH_CLIENT_ID = "oauth-id";+ process.env.GITHUB_OAUTH_CLIENT_SECRET = "oauth-secret";+ process.env.GITHUB_CLIENT_ID = "legacy-id";+ process.env.GITHUB_CLIENT_SECRET = "legacy-secret";+ expect(getGithubSsoOAuthCredentials()).toEqual({+ clientId: "oauth-id",+ clientSecret: "oauth-secret",+ });+ expect(isGithubSsoConfigured()).toBe(true);+ });++ it("falls back to legacy GITHUB_CLIENT_* when OAuth vars are unset", () => {+ process.env.GITHUB_CLIENT_ID = "legacy-id";+ process.env.GITHUB_CLIENT_SECRET = "legacy-secret";+ expect(getGithubSsoOAuthCredentials()).toEqual({+ clientId: "legacy-id",+ clientSecret: "legacy-secret",+ });+ expect(isGithubSsoConfigured()).toBe(true);+ });++ it("returns empty credentials when nothing is configured", () => {+ expect(getGithubSsoOAuthCredentials()).toEqual({+ clientId: "",+ clientSecret: "",+ });+ expect(isGithubSsoConfigured()).toBe(false);+ });++ it("treats partial OAuth pair as absent and falls back to legacy", () => {+ process.env.GITHUB_OAUTH_CLIENT_ID = "only-id";+ process.env.GITHUB_CLIENT_ID = "legacy-id";+ process.env.GITHUB_CLIENT_SECRET = "legacy-secret";+ expect(getGithubSsoOAuthCredentials()).toEqual({+ clientId: "legacy-id",+ clientSecret: "legacy-secret",+ });+ });+});