Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

feat: separate github sso and integration

Tindc4c67dd45c8
diff --git a/.env.sample b/.env.sample
index f17a843e5..5befc6230 100644
--- a/.env.sample
+++ b/.env.sample
@@ -11,12 +11,18 @@ POSTGRES_PASSWORD=
# Authentication
AUTH_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 Configuration
SMTP_HOST=
diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.md
index 460cbfe3c..a3a284537 100644
--- a/ENVIRONMENT_SETUP.md
+++ b/ENVIRONMENT_SETUP.md
@@ -43,7 +43,8 @@ For local development, the web app also supports:
### Optional Variables
Kaneo 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 configuration
diff --git a/apps/api/src/auth.ts b/apps/api/src/auth.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.mdx
index 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.mdx
index 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/setu
Add 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=abc123def456ghi789jkl012mno345pqr678stu
GITHUB_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 UI
GITHUB_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 variables
GITHUB_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: Opaque
stringData:
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 file
GITHUB_APP_ID=123456
-GITHUB_CLIENT_ID=Iv1.abc123def456
-GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stu
GITHUB_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.mdx
index 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 with
From 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.mdx
index 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.mdx
index 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 using
2. 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.
## Usage
diff --git a/tests/api-integration/setup.ts b/tests/api-integration/setup.ts
index 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.ts
new file mode 100644
index 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",
+ });
+ });
+});