From 41fbc8d3b02146195d8bdc1a5d125ae22958d549 Mon Sep 17 00:00:00 2001 From: Adam Setch Date: Sun, 25 Oct 2026 10:32:07 -0400 Subject: [PATCH] docs(faq): cover device flow setup for custom OAuth apps Custom OAuth app sign-in in Gitify v8 uses the OAuth device flow: enable the app's device flow, copy its Client ID, and enter it with the hostname. The client secret and gitify:// callback are no longer used. Keep the oauth-app-setup slug so existing links keep working. --- .../getting-started/authentication-methods.md | 8 ++++---- .../github-enterprise-server.md | 4 +++- src/faqs/getting-started/github-scopes.md | 2 +- src/faqs/getting-started/oauth-app-setup.md | 19 +++++++++++-------- 4 files changed, 19 insertions(+), 14 deletions(-) diff --git a/src/faqs/getting-started/authentication-methods.md b/src/faqs/getting-started/authentication-methods.md index 46b718a..39defdf 100644 --- a/src/faqs/getting-started/authentication-methods.md +++ b/src/faqs/getting-started/authentication-methods.md @@ -3,7 +3,7 @@ title: "What authentication methods does Gitify support?" category: "Getting Started" order: 1 --- -How you sign in depends on the forge. On GitHub.com, start with **Login with GitHub**. On other GitHub hostnames, use a personal access token (PAT) or a GitHub OAuth app. On Gitea, Forgejo, Codeberg, and GitLab, use a PAT. On Bitbucket Cloud, use an app password. +How you sign in depends on the forge. On GitHub.com, start with **Login with GitHub**. On other GitHub hostnames, use a personal access token (PAT) or a custom GitHub OAuth app. On Gitea, Forgejo, Codeberg, and GitLab, use a PAT. On Bitbucket Cloud, use an app password. ### GitHub @@ -11,9 +11,9 @@ GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server: - **Login with GitHub** — The simplest option on GitHub.com. Gitify shows a code, opens `github.com/login/device` in your browser, and finishes sign-in for you. This method is for GitHub.com only. - **Personal access token (classic)** — A classic token from your GitHub account settings. Works on GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server. -- **GitHub OAuth app** — A Client ID and Client Secret from an OAuth app you create. Works on GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server. +- **Custom GitHub OAuth app** — A Client ID from an OAuth app you create, with the app's device flow enabled. Works on GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server. -If you are unsure, use **Login with GitHub** on GitHub.com. On GitHub Enterprise Cloud or GitHub Enterprise Server, use a classic personal access token or a GitHub OAuth app. +If you are unsure, use **Login with GitHub** on GitHub.com. On GitHub Enterprise Cloud or GitHub Enterprise Server, use a classic personal access token or a custom GitHub OAuth app. ### Gitea, Forgejo, Codeberg @@ -29,4 +29,4 @@ GitLab Cloud and Self-Managed: - **Personal access token (PAT)** — Create a token under _User settings → Access tokens_, then enter it in Gitify with your instance hostname. -**Related:** [Which Git forges does Gitify support?](/faq/#supported-forges) · [How do I configure GitHub OAuth app authentication?](/faq/#oauth-app-setup) · [What GitHub scopes does Gitify require?](/faq/#github-scopes) +**Related:** [Which Git forges does Gitify support?](/faq/#supported-forges) · [How do I configure a custom GitHub OAuth app?](/faq/#oauth-app-setup) · [What GitHub scopes does Gitify require?](/faq/#github-scopes) diff --git a/src/faqs/getting-started/github-enterprise-server.md b/src/faqs/getting-started/github-enterprise-server.md index 74262ab..ddacf85 100644 --- a/src/faqs/getting-started/github-enterprise-server.md +++ b/src/faqs/getting-started/github-enterprise-server.md @@ -5,12 +5,14 @@ order: 3 --- Yes. Gitify works with **GitHub.com**, **GitHub Enterprise Cloud** (including **GitHub Enterprise Cloud with data residency (GHDR)**), and **GitHub Enterprise Server (GHES)**. -When you sign in with a **personal access token (classic)** or a **GitHub OAuth app**, Gitify shows a **Hostname** field. It defaults to `github.com`. Change it to match your instance: +When you sign in with a **personal access token (classic)** or a **custom GitHub OAuth app**, Gitify shows a **Hostname** field. It defaults to `github.com`. Change it to match your instance: - **GitHub Enterprise Server (GHES):** your self-hosted hostname, for example `github.mycompany.com` - **GitHub Enterprise Cloud with data residency (GHDR):** your tenant hostname, for example `myorg.ghe.com` - **GitHub.com / GitHub Enterprise Cloud on github.com:** leave the hostname as `github.com` +A custom GitHub OAuth app must have its device flow enabled; see [How do I configure a custom GitHub OAuth app?](/faq/#oauth-app-setup). + > **Note:** Enterprise Managed Users (EMU) is an account model, not a separate forge. Your enterprise policy may limit which sign-in methods you can use. > **Note:** **Login with GitHub** only works on GitHub.com (`github.com`) and does not show a hostname field. diff --git a/src/faqs/getting-started/github-scopes.md b/src/faqs/getting-started/github-scopes.md index abad3b0..2ffcb1d 100644 --- a/src/faqs/getting-started/github-scopes.md +++ b/src/faqs/getting-started/github-scopes.md @@ -7,7 +7,7 @@ Gitify needs specific GitHub permissions so it can read your notifications and p This article covers **GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server** only. -#### Login with GitHub and GitHub OAuth app +#### Login with GitHub and custom GitHub OAuth app Gitify requests the scopes for you during sign-in. You do not choose them yourself. diff --git a/src/faqs/getting-started/oauth-app-setup.md b/src/faqs/getting-started/oauth-app-setup.md index b3be551..405373e 100644 --- a/src/faqs/getting-started/oauth-app-setup.md +++ b/src/faqs/getting-started/oauth-app-setup.md @@ -1,17 +1,20 @@ --- -title: "How do I configure GitHub OAuth app authentication?" +title: "How do I configure a custom GitHub OAuth app?" category: "Getting Started" order: 2 --- -You can sign in with a GitHub OAuth app on GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server by registering an app and pasting its client ID and secret into Gitify. +You can sign in with a custom GitHub OAuth app on GitHub.com, GitHub Enterprise Cloud, or GitHub Enterprise Server by registering an app, enabling its device flow, and entering its public Client ID in Gitify. -1. On GitHub.com, open [GitHub → Settings → Developer settings → OAuth Apps](https://github.com/settings/developers). On GitHub Enterprise Cloud or GitHub Enterprise Server, open the same page on your GitHub hostname. +1. Open [GitHub → Settings → Developer settings → OAuth Apps](https://github.com/settings/developers), or the same page on your GitHub hostname. 2. Click **New OAuth App**. -3. Set **Authorization callback URL** to `gitify://oauth`. -4. Fill in the other required fields. -5. Click **Register application**. -6. Click **Generate a new client secret**. -7. Enter the client ID and secret in Gitify. +3. Fill in **Application name** and **Homepage URL**. +4. Set **Authorization callback URL** to `https://gitify.io`. The device flow does not use it, but GitHub's form asks for one. +5. Tick **Enable Device Flow**, then click **Register application**. You can also tick this later on the app's settings page and click **Update application**. +6. Copy the app's **Client ID**. No other credential is needed. +7. In Gitify, choose **Add new account → GitHub → Custom OAuth App**, enter your hostname and the client ID, then continue. +8. Gitify copies a one-time code to your clipboard and opens your host's `/login/device` page. Enter the code and authorize the app. + +> **Note:** Device flow is off for new OAuth apps until you enable it. If Gitify says device flow is not enabled, tick the toggle in step 5, update the app, and try again. > **Note:** Create a separate OAuth app for each GitHub hostname. Enterprise Managed Users (EMU) and enterprise policies may block OAuth apps. For Gitea, Forgejo, Codeberg, GitLab, and Bitbucket Cloud, use a [personal access token or app password](/faq/#authentication-methods) instead.