docs: update faqs for v7 features

setchy · setchy · commit 77f898ebe84f · 2026-07-22T10:19:36.000+10:00
Signed-off-by: Adam Setch &lt;adam.setch@outlook.com&gt;
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -14,5 +14,8 @@
   },
   "[typescript]": {
     "editor.defaultFormatter": "biomejs.biome"
-  }
+  },
+  "cSpell.words": [
+    "Gitify"
+  ]
 }
diff --git a/src/components/Footer.astro b/src/components/Footer.astro
@@ -25,8 +25,9 @@ const isHomepage = currentPathname === '/';
     </a>
 
     <div class="my-3">
-      Copyright ©
+      Copyright ©{' '}
       <a href={siteMetadata.author.site}>{siteMetadata.author.name}</a>
+      {' '}
       {new Date().getFullYear()}
     </div>
   </div>
diff --git a/src/constants.ts b/src/constants.ts
@@ -12,7 +12,7 @@ export const siteMetadata = {
     site: 'https://github.com/orgs/gitify-app/people',
   },
   keywords:
-    'gitify,desktop,application,github,notifications,unread,menu bar,electron,open source,mac,windows,linux',
+    'gitify,desktop,application,github,gitea,codeberg,forgejo,bitbucket,notifications,unread,menu bar,electron,open source,mac,windows,linux',
   google: {
     gtags: ['G-QXML81DEDV', 'G-H4MTPZP3HW'],
     siteVerification: 'jJNnPZ2wu7F1tlSab57og1N3RNrMqhzTCzRrbztY8WU',
diff --git a/src/faqs/getting-started/authentication-methods.md b/src/faqs/getting-started/authentication-methods.md
@@ -3,10 +3,20 @@ title: "What authentication methods does Gitify support?"
 category: "Getting Started"
 order: 1
 ---
-Gitify offers three ways to authenticate with GitHub:
+Authentication methods vary by forge:
+
+### GitHub Cloud & GitHub Enterprise Server
 
 - **Login with GitHub** — The easiest option. Uses the OAuth Device Flow: Gitify generates a code, opens `github.com/login/device` in your browser, and completes authentication automatically. Supports GitHub Cloud only.
 - **Personal Access Token (PAT)** — Authenticate with a token generated in your GitHub account settings. Supports both GitHub Cloud and GitHub Enterprise Server.
 - **OAuth App** — Authenticate using a Client ID and Client Secret from a GitHub OAuth App you create. Supports both GitHub Cloud and GitHub Enterprise Server.
 
 If you are unsure which method to use, **Login with GitHub** is recommended for most users on GitHub Cloud. For GitHub Enterprise Server, use a PAT or OAuth App.
+
+### Gitea, Forgejo & Codeberg
+
+- **Personal Access Token (PAT)** — Generate a token in your Gitea/Forgejo/Codeberg account under _Settings → Applications_, then enter it in Gitify along with your instance hostname (e.g. `codeberg.org` or your self-hosted URL).
+
+### Bitbucket Cloud
+
+- **Personal Access Token (PAT)** — Generate an app password in your Bitbucket account under _Personal settings → App passwords_ and use it as your token in Gitify.
diff --git a/src/faqs/getting-started/github-enterprise-server.md b/src/faqs/getting-started/github-enterprise-server.md
@@ -3,10 +3,14 @@ title: "Does Gitify support GitHub Enterprise Server?"
 category: "Getting Started"
 order: 3
 ---
-Yes. Gitify supports both GitHub Cloud and **GitHub Enterprise Server (GHES)**.
+Yes. Gitify supports **GitHub Enterprise Server (GHES)** and **GitHub Enterprise Cloud with Data Residency** alongside GitHub Cloud.
 
-When signing in via **Personal Access Token** or **OAuth App**, you will see a _Hostname_ field that defaults to `github.com`. Replace this with your GHES hostname (e.g. `github.mycompany.com`) to connect to your Enterprise instance.
+> **Note:** This entry covers GitHub-specific setup. If you are using Gitea, Forgejo, Codeberg, or Bitbucket Cloud, see [Which Git forges does Gitify support?](/faq/#supported-forges) and [What authentication methods does Gitify support?](/faq/#authentication-methods).
 
-> **Note:** The **Login with GitHub** (Device Flow) method only supports GitHub Cloud and does not expose a hostname field.
+When signing in via **Personal Access Token** or **OAuth App**, you will see a _Hostname_ field that defaults to `github.com`. Replace this with your instance hostname to connect:
+- **GitHub Enterprise Server**: your self-hosted hostname, e.g. `github.mycompany.com`
+- **GitHub Enterprise Cloud (Data Residency)**: your tenant hostname, e.g. `myorg.ghe.com`
 
-Multiple accounts across different hostnames (e.g. `github.com` and your GHES instance) can be signed in simultaneously — see _"How do I add multiple GitHub accounts?"_ for details.
+> **Note:** The **Login with GitHub** (Device Flow) method only supports GitHub Cloud (`github.com`) and does not expose a hostname field.
+
+Multiple accounts across different hostnames (e.g. `github.com` and your GHES instance) can be signed in simultaneously — see [How do I add multiple accounts?](/faq/#multiple-accounts) for details.
diff --git a/src/faqs/getting-started/github-scopes.md b/src/faqs/getting-started/github-scopes.md
@@ -1,9 +1,11 @@
 ---
 title: "What GitHub scopes does Gitify require?"
 category: "Getting Started"
-order: 3
+order: 6
 ---
 
+> **Note:** This entry covers **GitHub Cloud and GitHub Enterprise Server** only. Gitea, Forgejo, Codeberg, and Bitbucket Cloud use standard read access tokens — see [What authentication methods does Gitify support?](/faq/#authentication-methods).
+
 The required GitHub scopes depend on your chosen authentication method.
 
 **Login with GitHub** (Device Flow) and **OAuth App**:
@@ -18,3 +20,5 @@ When generating a PAT, the following scopes are required:
 - `repo` — to enrich notification details for public and private repositories
 
 > **Note:** If you only need access to public repositories, you can use `public_repo` instead of `repo`.
+
+For help generating a PAT, see [GitHub → Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens). If notifications still aren't appearing after setting up a PAT, see [Why aren't my notifications showing?](/faq/#notifications-not-showing).
diff --git a/src/faqs/getting-started/github-sso-pat-authorization.md b/src/faqs/getting-started/github-sso-pat-authorization.md
@@ -0,0 +1,18 @@
+---
+title: "How do I authorize my PAT for a GitHub SSO organization?"
+category: "Getting Started"
+order: 7
+---
+If your GitHub organization enforces **SAML single sign-on (SSO)**, you must explicitly authorize your Personal Access Token to access that organization's data — including notifications. Without this step, Gitify will not show notifications from repositories in that organization even if your PAT has the correct scopes.
+
+To authorize a PAT for SSO:
+- Open [GitHub → Settings → Personal access tokens](https://github.com/settings/tokens)
+- Find the token you use with Gitify
+- Click **Configure SSO** next to the token
+- Click **Authorize** next to each SSO-enabled organization you want to grant access
+- Complete the SSO authentication flow for each organization
+
+Once authorized, Gitify will be able to fetch notifications from repositories in those organizations. Re-authorization may be required if your SSO session expires or your organization's SSO configuration changes.
+
+For more details, see the [GitHub documentation on authorizing a PAT for use with SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-single-sign-on/authorizing-a-personal-access-token-for-use-with-single-sign-on).
+
diff --git a/src/faqs/getting-started/multiple-accounts.md b/src/faqs/getting-started/multiple-accounts.md
@@ -1,15 +1,17 @@
 ---
-title: "How do I add multiple GitHub accounts?"
+title: "How do I add multiple accounts?"
 category: "Getting Started"
 order: 4
 ---
-Gitify supports signing in to multiple accounts simultaneously — for example, a personal GitHub Cloud account alongside a GitHub Enterprise Server account.
+Gitify supports signing in to multiple accounts simultaneously — for example, a personal GitHub Cloud account alongside a Gitea or Bitbucket Cloud account.
 
 To add an account:
 - Open the **Accounts** screen from the Gitify sidebar
-- Click **Add new account** and choose your preferred authentication method
+- Click **Add new account** and choose your forge and preferred authentication method
 - Complete the sign-in flow for the additional account
 
 All signed-in accounts will appear on the Accounts screen. You can designate a **primary account** by clicking the star icon next to an account — the primary account is used as the default where applicable.
 
 Each account can be individually refreshed or signed out at any time.
+
+For a full list of supported forges, see [Which Git forges does Gitify support?](/faq/#supported-forges).
diff --git a/src/faqs/getting-started/oauth-app-setup.md b/src/faqs/getting-started/oauth-app-setup.md
@@ -3,7 +3,9 @@ title: "How do I configure OAuth App authentication?"
 category: "Getting Started"
 order: 2
 ---
-To authenticate via an **OAuth App**:
+> **Note:** OAuth App authentication is available for **GitHub Cloud and GitHub Enterprise Server only**. For Gitea, Forgejo, Codeberg, and Bitbucket Cloud, use a [Personal Access Token](/faq/#authentication-methods).
+
+To authenticate via an **OAuth App** with GitHub:
 - Open [GitHub → Settings → Developer settings → OAuth Apps](https://github.com/settings/developers)
 - Click _New OAuth App_
 - Set _Authorization callback URL_ to `gitify://oauth`
diff --git a/src/faqs/getting-started/supported-forges.md b/src/faqs/getting-started/supported-forges.md
@@ -0,0 +1,18 @@
+---
+title: "Which Git forges does Gitify support?"
+category: "Getting Started"
+order: 0
+---
+Gitify supports notifications from the following Git forges:
+
+- **GitHub Cloud** — `github.com`
+- **GitHub Enterprise Server (GHES)** — self-hosted GitHub instances
+- **GitHub Enterprise Cloud (Data Residency)** — `[tenant].ghe.com`
+- **Gitea** — including self-hosted instances
+- **Forgejo** — compatible with the Gitea authentication flow
+- **Codeberg** — powered by Forgejo, fully supported
+- **Bitbucket Cloud** — `bitbucket.org`
+
+Multiple accounts across different forges can be signed in simultaneously. See [How do I add multiple accounts?](/faq/#multiple-accounts) for details.
+
+For authentication setup, see [What authentication methods does Gitify support?](/faq/#authentication-methods).
diff --git a/src/faqs/troubleshooting/chrome-sandbox-linux.md b/src/faqs/troubleshooting/chrome-sandbox-linux.md
@@ -1,5 +1,5 @@
 ---
-title: "How do I fix 'Chrome Sandbox' permissions on Linux?"
+title: "How do I fix Chrome Sandbox permissions on Linux?"
 category: "Troubleshooting"
 order: 3
 ---
diff --git a/src/faqs/troubleshooting/notifications-not-showing.md b/src/faqs/troubleshooting/notifications-not-showing.md
@@ -3,13 +3,18 @@ title: "Why aren't my notifications showing?"
 category: "Troubleshooting"
 order: 1
 ---
-When authenticating via **Personal Access Token (PAT)**:
+
+### GitHub Cloud & GitHub Enterprise Server
+
+**Personal Access Token (PAT):**
 - Open [GitHub → Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)
 - Confirm that your PAT has the following recommended permissions: `notifications`, `read:user` and `repo`
 
-> **Note:** If you only want Gitify to access public repositories, you can use `notifications`, `read:user` and `public_repo` instead.
+> **Note:** If you only want Gitify to access public repositories, you can use `notifications`, `read:user` and `public_repo` instead. See [What GitHub scopes does Gitify require?](/faq/#github-scopes) for full details.
 
-When authenticating via **Gitify GitHub App**:
+> **Note:** If your organization enforces SAML SSO, your PAT must also be explicitly authorized for that organization. See [How do I authorize my PAT for a GitHub SSO organization?](/faq/#github-sso-pat-authorization).
+
+**Login with GitHub (Device Flow):**
 - Some organizations require GitHub Apps to request access prior to allowing access to organization data (including notifications)
 - To check if Gitify is approved by your organization:
   - Open [GitHub → Settings → Applications → Authorized GitHub Apps](https://github.com/settings/applications)
@@ -22,4 +27,15 @@ When authenticating via **Gitify GitHub App**:
 | **Request** button | Access not yet granted — click to ask your org admins to approve |
 | _Disallowed by org owner_ | The organization has blocked third-party GitHub App access entirely — contact your org admin |
 
-> **Note:** If an organization shows **Request** or **Disallowed by org owner**, you will not receive notifications from that organization until access is approved.
+> **Note:** If an organization shows **Request** or **Disallowed by org owner**, you will not receive notifications from that organization until access is approved.
+
+### Gitea, Forgejo & Codeberg
+
+- Verify your PAT is valid and has not expired — regenerate it in your account under _Settings → Applications_ if needed
+- Confirm the hostname saved in your Gitify account settings exactly matches your instance URL (e.g. `codeberg.org` or your self-hosted domain)
+- Ensure your PAT has sufficient read permissions for notifications and repositories on your instance
+
+### Bitbucket Cloud
+
+- Verify your app password is valid and has not been revoked — regenerate it in _Personal settings → App passwords_ if needed
+- Ensure your app password grants **Read** access to: Account, Repositories, and Pull requests
diff --git a/src/faqs/using-gitify/unsubscribe-from-thread.md b/src/faqs/using-gitify/unsubscribe-from-thread.md
@@ -1,8 +1,8 @@
 ---
-title: "What does 'Unsubscribe from Thread' mean?"
+title: "What does the Unsubscribe from Thread option do?"
 category: "Using Gitify"
 order: 2
 ---
 When you **Unsubscribe from Thread**, you will not receive future notifications for the thread until you either comment on the thread or get a **@mention**.
 
-> **Note:** If you are watching a repository, you receive notifications for all threads by default.
+> **Note:** Depending on your notification subscription settings for the repository, you may continue to receive some notifications even after unsubscribing from a specific thread.
diff --git a/src/pages/index.astro b/src/pages/index.astro
@@ -13,7 +13,7 @@ import SectionRow from '~/layouts/SectionRow.astro';
 
     <SectionRow
       title="All your Git notifications, right on your desktop."
-      description="<p>Gitify is all about making your life easier.</p><br /><p>Always visible on your menu bar, Gitify delivers real-time notifications across all your GitHub Cloud, GitHub Enterprise and Gitea (incl. Forgejo, Codeberg) accounts.</p><br /><p>Stay on top of your work, effortlessly.</p>"
+      description="<p>Gitify is all about making your life easier.</p><br /><p>Always visible on your menu bar, Gitify delivers real-time notifications across all your GitHub Cloud, GitHub Enterprise, Gitea (incl. Forgejo, Codeberg) and Bitbucket Cloud accounts.</p><br /><p>Stay on top of your work, effortlessly.</p>"
       screenshot={{
         path: "all-read",
         alt: "Screenshot when there are no notifications read",
