diff --git a/src/constants.ts b/src/constants.ts index 9c3b14d4..86a13dac 100644 --- 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,gitea,codeberg,forgejo,bitbucket,notifications,unread,menu bar,electron,open source,mac,windows,linux', + 'gitify,desktop,application,github,gitea,codeberg,forgejo,gitlab,bitbucket,notifications,unread,menu bar,electron,open source,mac,windows,linux', google: { gtags: ['G-QXML81DEDV', 'G-H4MTPZP3HW'], siteVerification: 'jJNnPZ2wu7F1tlSab57og1N3RNrMqhzTCzRrbztY8WU', diff --git a/src/faqs/contributing/how-to-contribute.md b/src/faqs/contributing/how-to-contribute.md index 818802e3..48ca8102 100644 --- a/src/faqs/contributing/how-to-contribute.md +++ b/src/faqs/contributing/how-to-contribute.md @@ -3,10 +3,9 @@ title: "How can I contribute to Gitify?" category: "Contributing" order: 1 --- -You can contribute to Gitify by opening an issue or pull request on GitHub at [gitify-app/gitify](https://github.com/gitify-app/gitify). +You can help Gitify by opening an issue or pull request on GitHub at [gitify-app/gitify](https://github.com/gitify-app/gitify). -Before contributing, please review our [CONTRIBUTING.md](https://github.com/gitify-app/gitify/blob/main/CONTRIBUTING.md) guide for details on branch naming, the PR process, and code style. +1. Read [CONTRIBUTING.md](https://github.com/gitify-app/gitify/blob/main/CONTRIBUTING.md) for branch naming, the pull request process, and code style. +2. Browse [open issues](https://github.com/gitify-app/gitify/issues) and pick something you want to work on. -Check out our [open issues](https://github.com/gitify-app/gitify/issues) and see if there is an existing idea you would like to work on. - -Not a developer? You can still help by reporting bugs, improving documentation, or starring and sharing the project. \ No newline at end of file +Not a developer? You can still help by reporting bugs, improving docs, or starring and sharing the project. diff --git a/src/faqs/getting-started/authentication-methods.md b/src/faqs/getting-started/authentication-methods.md index 6aca0f6d..46b718ab 100644 --- a/src/faqs/getting-started/authentication-methods.md +++ b/src/faqs/getting-started/authentication-methods.md @@ -3,20 +3,30 @@ title: "What authentication methods does Gitify support?" category: "Getting Started" order: 1 --- -Authentication methods vary by forge: +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. -### GitHub Cloud & GitHub Enterprise Server +### GitHub -- **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. +GitHub.com, GitHub Enterprise 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. +- **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. -### Gitea, Forgejo & Codeberg +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. -- **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). +### Gitea, Forgejo, Codeberg + +- **Personal access token (PAT)** — Create a token under _Settings → Applications_, then enter it in Gitify with your instance hostname (for example `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. +- **App password** — Create an app password under _Personal settings → App passwords_ and enter it as your token in Gitify. + +### GitLab + +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) diff --git a/src/faqs/getting-started/github-enterprise-server.md b/src/faqs/getting-started/github-enterprise-server.md index bada8551..74262ab0 100644 --- a/src/faqs/getting-started/github-enterprise-server.md +++ b/src/faqs/getting-started/github-enterprise-server.md @@ -1,16 +1,18 @@ --- -title: "Does Gitify support GitHub Enterprise Server?" +title: "Does Gitify support GitHub Enterprise Cloud and GitHub Enterprise Server?" category: "Getting Started" order: 3 --- -Yes. Gitify supports **GitHub Enterprise Server (GHES)** and **GitHub Enterprise Cloud with Data Residency** alongside GitHub Cloud. +Yes. Gitify works with **GitHub.com**, **GitHub Enterprise Cloud** (including **GitHub Enterprise Cloud with data residency (GHDR)**), and **GitHub Enterprise Server (GHES)**. -> **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). +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 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` +- **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` -> **Note:** The **Login with GitHub** (Device Flow) method only supports GitHub Cloud (`github.com`) and does not expose a hostname field. +> **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. -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. +> **Note:** **Login with GitHub** only works on GitHub.com (`github.com`) and does not show a hostname field. + +**Related:** [What authentication methods does Gitify support?](/faq/#authentication-methods) · [How do I add multiple accounts?](/faq/#multiple-accounts) · [Which Git forges does Gitify support?](/faq/#supported-forges) diff --git a/src/faqs/getting-started/github-scopes.md b/src/faqs/getting-started/github-scopes.md index 386384d3..abad3b00 100644 --- a/src/faqs/getting-started/github-scopes.md +++ b/src/faqs/getting-started/github-scopes.md @@ -1,24 +1,28 @@ --- title: "What GitHub scopes does Gitify require?" category: "Getting Started" -order: 6 +order: 4 --- +Gitify needs specific GitHub permissions so it can read your notifications and profile. The required GitHub scopes depend on how you sign in. -> **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). +This article covers **GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server** only. -The required GitHub scopes depend on your chosen authentication method. +#### Login with GitHub and GitHub OAuth app -**Login with GitHub** (Device Flow) and **OAuth App**: +Gitify requests the scopes for you during sign-in. You do not choose them yourself. -Scopes are pre-configured by Gitify and requested automatically during sign-in. No manual scope selection is required. +#### Classic personal access token (PAT) -**Personal Access Token (PAT)**: +When you create a classic PAT, select: -When generating a PAT, the following scopes are required: - `notifications` — to read GitHub notifications - `read:user` — to read your GitHub user details (name, profile, avatar) - `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`. +> **Note:** If you only need 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). +Fine-grained PATs use repository and account permissions instead of these classic scopes. Confirm that your Gitify version and GitHub deployment support the permissions required by fine-grained PATs before using one. + +On GitHub.com, create a classic token at [GitHub → Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens). On GitHub Enterprise Cloud or GitHub Enterprise Server, open the same page on your GitHub hostname. + +**Related:** [What authentication methods does Gitify support?](/faq/#authentication-methods) · [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 index 804acfd8..4b550cd8 100644 --- a/src/faqs/getting-started/github-sso-pat-authorization.md +++ b/src/faqs/getting-started/github-sso-pat-authorization.md @@ -1,18 +1,20 @@ --- -title: "How do I authorize my PAT for a GitHub SSO organization?" +title: "How do I authorize my classic PAT for a GitHub SSO organization?" category: "Getting Started" -order: 7 +order: 5 --- -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. +If your GitHub organization uses SAML single sign-on (SSO), you must authorize your classic personal access token (PAT) for that organization. Until you do, Gitify will not show notifications from that organization's repositories, even if the token has the right 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 +1. On GitHub.com, open [GitHub → Settings → Personal access tokens](https://github.com/settings/tokens). On GitHub Enterprise Cloud or GitHub Enterprise Server, open the same page on your GitHub hostname. +2. Find the token you use with Gitify. +3. Click **Configure SSO** next to the token. +4. Click **Authorize** next to each SSO-enabled organization you want to allow. +5. Complete the SSO sign-in 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. +After that, Gitify can fetch notifications from those organizations. You may need to authorize again if your SSO session expires or your organization's SSO setup 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). +Fine-grained PATs use different SSO and repository-permission controls. +For more detail, see [GitHub's documentation on authorizing a PAT for 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). + +**Related:** [What GitHub scopes does Gitify require?](/faq/#github-scopes) · [Why aren't my notifications showing?](/faq/#notifications-not-showing) diff --git a/src/faqs/getting-started/launch-at-login.md b/src/faqs/getting-started/launch-at-login.md index 51298f5c..a3f35947 100644 --- a/src/faqs/getting-started/launch-at-login.md +++ b/src/faqs/getting-started/launch-at-login.md @@ -1,13 +1,12 @@ --- title: "How do I launch Gitify at login?" category: "Getting Started" -order: 5 +order: 7 --- -Gitify can be configured to start automatically when you log in to your computer. +Gitify can start automatically when you log in to your computer. -To enable this: -- Open **Settings** in Gitify -- Navigate to the **System** section -- Toggle **Open at startup** +1. Open **Settings** in Gitify. +2. Go to the **System** section. +3. Turn on **Open at startup**. -> **Note:** This setting is available on **macOS and Windows** only. On Linux, startup behaviour is managed by your desktop environment or init system. +> **Note:** This setting is available on **macOS and Windows** only. On Linux, use your desktop environment or init system to start Gitify at login. diff --git a/src/faqs/getting-started/multiple-accounts.md b/src/faqs/getting-started/multiple-accounts.md index 77212d07..377ddb55 100644 --- a/src/faqs/getting-started/multiple-accounts.md +++ b/src/faqs/getting-started/multiple-accounts.md @@ -1,17 +1,16 @@ --- title: "How do I add multiple accounts?" category: "Getting Started" -order: 4 +order: 6 --- -Gitify supports signing in to multiple accounts simultaneously — for example, a personal GitHub Cloud account alongside a Gitea or Bitbucket Cloud account. +Gitify can stay signed in to more than one account at once. You can add several GitHub.com accounts, or mix accounts from different forges — for example GitHub.com with GitHub Enterprise Server, Gitea, or Bitbucket Cloud. -To add an account: -- Open the **Accounts** screen from the Gitify sidebar -- Click **Add new account** and choose your forge and preferred authentication method -- Complete the sign-in flow for the additional account +1. Open the **Accounts** screen from the Gitify sidebar. +2. Click **Add new account** and choose your forge and sign-in method. +3. Finish sign-in for the extra 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. +All signed-in accounts appear on the Accounts screen. Click the star next to an account to make it the **primary account** — Gitify uses that account as the default where it needs one. -Each account can be individually refreshed or signed out at any time. +You can refresh or sign out of each account on its own. -For a full list of supported forges, see [Which Git forges does Gitify support?](/faq/#supported-forges). +**Related:** [Which Git forges does Gitify support?](/faq/#supported-forges) · [What authentication methods does Gitify support?](/faq/#authentication-methods) diff --git a/src/faqs/getting-started/oauth-app-setup.md b/src/faqs/getting-started/oauth-app-setup.md index 9c36c597..b3be551f 100644 --- a/src/faqs/getting-started/oauth-app-setup.md +++ b/src/faqs/getting-started/oauth-app-setup.md @@ -1,15 +1,18 @@ --- -title: "How do I configure OAuth App authentication?" +title: "How do I configure GitHub OAuth app authentication?" category: "Getting Started" order: 2 --- -> **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). +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. -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` -- Complete all remaining mandatory fields -- Click _Register application_ -- Click _Generate a new client secret_ -- Use this client/secret pair within Gitify to authenticate. \ No newline at end of file +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. +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. + +> **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. + +**Related:** [What authentication methods does Gitify support?](/faq/#authentication-methods) · [Does Gitify support GitHub Enterprise Cloud and GitHub Enterprise Server?](/faq/#github-enterprise-server) diff --git a/src/faqs/getting-started/supported-forges.md b/src/faqs/getting-started/supported-forges.md index 32a7dae5..abd21496 100644 --- a/src/faqs/getting-started/supported-forges.md +++ b/src/faqs/getting-started/supported-forges.md @@ -3,16 +3,17 @@ title: "Which Git forges does Gitify support?" category: "Getting Started" order: 0 --- -Gitify supports notifications from the following Git forges: +Gitify can show notifications from several Git hosts, not only GitHub.com. -- **GitHub Cloud** — `github.com` -- **GitHub Enterprise Server (GHES)** — self-hosted GitHub instances -- **GitHub Enterprise Cloud (Data Residency)** — `[tenant].ghe.com` +- **GitHub.com** — the public `github.com` service, including GitHub Enterprise Cloud organizations hosted there +- **GitHub Enterprise Server (GHES)** — a self-hosted GitHub instance +- **GitHub Enterprise Cloud with data residency (GHDR)** — GitHub Enterprise Cloud on `[tenant].ghe.com` - **Gitea** — including self-hosted instances -- **Forgejo** — compatible with the Gitea authentication flow -- **Codeberg** — powered by Forgejo, fully supported +- **Forgejo** — uses the same sign-in flow as Gitea +- **Codeberg** — powered by Forgejo - **Bitbucket Cloud** — `bitbucket.org` +- **GitLab Cloud and Self-Managed** — GitLab.com and self-hosted GitLab -Multiple accounts across different forges can be signed in simultaneously. See [How do I add multiple accounts?](/faq/#multiple-accounts) for details. +You can stay signed in to more than one account at the same time, including accounts on different forges. -For authentication setup, see [What authentication methods does Gitify support?](/faq/#authentication-methods). +**Related:** [What authentication methods does Gitify support?](/faq/#authentication-methods) · [How do I add multiple accounts?](/faq/#multiple-accounts) diff --git a/src/faqs/troubleshooting/chrome-sandbox-linux.md b/src/faqs/troubleshooting/chrome-sandbox-linux.md index abe63dc1..82cae519 100644 --- a/src/faqs/troubleshooting/chrome-sandbox-linux.md +++ b/src/faqs/troubleshooting/chrome-sandbox-linux.md @@ -3,16 +3,19 @@ title: "How do I fix Chrome Sandbox permissions on Linux?" category: "Troubleshooting" order: 3 --- -If you experience issues opening Gitify on Linux due to `Chrome Sandbox` permissions, the Electron sandbox requires root ownership and the SUID bit to be set on the sandbox binary. Run the following commands to fix this: +If Gitify will not open on Linux because of `Chrome Sandbox` permissions, the Electron sandbox binary must be owned by root and have the set-user-ID (SUID) bit set. + +1. Run: ``` sudo chown root:root /opt/Gitify/chrome-sandbox sudo chmod 4755 /opt/Gitify/chrome-sandbox ``` -> **Note:** The path `/opt/Gitify/chrome-sandbox` assumes a standard installation. If you installed Gitify via AppImage or to a custom directory, adjust the path accordingly. +2. If Gitify still fails to start, check logs with: -To check for startup errors: ``` journalctl -xe | grep gitify -``` \ No newline at end of file +``` + +> **Note:** `/opt/Gitify/chrome-sandbox` is the path for a standard install. If you installed Gitify as an AppImage or in a custom directory, change the path to match. diff --git a/src/faqs/troubleshooting/debugging.md b/src/faqs/troubleshooting/debugging.md index 317e5f20..2d427c03 100644 --- a/src/faqs/troubleshooting/debugging.md +++ b/src/faqs/troubleshooting/debugging.md @@ -3,15 +3,19 @@ title: "How do I debug Gitify?" category: "Troubleshooting" order: 2 --- -Using **Chrome Developer Tools** (console logs, network requests, etc): +You can inspect Gitify with developer tools or by reading its log files. -Right-click the tray icon and select _Developer → Toggle Developer Tools_, or use the keyboard shortcut for your platform: -- macOS: `command + opt + i` -- Windows / Linux: `ctrl + shift + i` +### Chrome Developer Tools -Using **Application Log Files**: +Console logs, network requests, and similar: -Right-click the tray icon and select _Developer → View Application Logs_, or navigate directly to the log directory for your platform: -- macOS: `~/Library/Logs/gitify` -- Windows: `%USERPROFILE%\AppData\Roaming\gitify\logs` -- Linux: `~/.config/gitify/logs` \ No newline at end of file +1. Right-click the tray icon and select **Developer → Toggle Developer Tools**, or use the shortcut for your platform: + - macOS: `command + opt + i` + - Windows / Linux: `ctrl + shift + i` + +### Application log files + +1. Right-click the tray icon and select **Developer → View Application Logs**, or open the log folder for your platform: + - macOS: `~/Library/Logs/gitify` + - Windows: `%USERPROFILE%\AppData\Roaming\gitify\logs` + - Linux: `~/.config/gitify/logs` diff --git a/src/faqs/troubleshooting/notifications-not-showing.md b/src/faqs/troubleshooting/notifications-not-showing.md index 75032d16..89cac77d 100644 --- a/src/faqs/troubleshooting/notifications-not-showing.md +++ b/src/faqs/troubleshooting/notifications-not-showing.md @@ -3,39 +3,52 @@ title: "Why aren't my notifications showing?" category: "Troubleshooting" order: 1 --- +Gitify is signed in but your inbox is empty? Check the steps for your forge below. -### GitHub Cloud & GitHub Enterprise Server +### GitHub -**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` +GitHub.com, GitHub Enterprise Cloud, and GitHub Enterprise Server: -> **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. +#### Classic personal access token (PAT) -> **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). +1. On GitHub.com, open [GitHub → Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens). On GitHub Enterprise Cloud or GitHub Enterprise Server, open the same page on your GitHub hostname. +2. Confirm the token Gitify uses is a **classic PAT** with the scopes listed in [What GitHub scopes does Gitify require?](/faq/#github-scopes). -**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) - - Click on the _Gitify_ application - - Under _Organization access_, you will see one of three states for each organization: +> **Note:** If your organization uses SAML single sign-on (SSO), authorize the PAT for that organization. See [How do I authorize my classic PAT for a GitHub SSO organization?](/faq/#github-sso-pat-authorization). + +#### Login with GitHub + +Gitify signs in with its GitHub OAuth app. Some organizations must approve that app before Gitify can see their notifications. + +1. Open [GitHub → Settings → Applications → Authorized OAuth Apps](https://github.com/settings/applications). +2. Click the **Gitify** application. +3. Under **Organization access**, check the state for each organization: | State | Meaning | |---|---| | ✅ Green check | Access granted — notifications from this org will appear | | **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 | +| _Disallowed by org owner_ | The organization has blocked third-party OAuth apps — 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 get notifications from that organization until access is approved. -### Gitea, Forgejo & Codeberg +### 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 +- Check your personal access token (PAT) is valid and has not expired — create a new one under _Settings → Applications_ if needed +- Confirm the hostname in Gitify matches your instance URL exactly (for example `codeberg.org` or your self-hosted domain) +- Confirm the PAT can read notifications and repositories on that 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 \ No newline at end of file +- Check your **app password** is valid and has not been revoked — create a new one under _Personal settings → App passwords_ if needed +- Confirm the app password grants **Read** access to Account, Repositories, and Pull requests + +### GitLab + +GitLab Cloud and Self-Managed: + +- Check your personal access token (PAT) is valid and has not expired — create a new one under _User settings → Access tokens_ if needed +- Confirm the hostname in Gitify matches your instance URL exactly (for example `gitlab.com` or your self-hosted domain) +- Confirm the PAT can read notifications and repositories on that instance + +**Related:** [What authentication methods does Gitify support?](/faq/#authentication-methods) · [What GitHub scopes does Gitify require?](/faq/#github-scopes) diff --git a/src/faqs/using-gitify/appearance.md b/src/faqs/using-gitify/appearance.md index 8ab15607..d786d08d 100644 --- a/src/faqs/using-gitify/appearance.md +++ b/src/faqs/using-gitify/appearance.md @@ -1,15 +1,14 @@ --- title: "How do I change the appearance of Gitify?" category: "Using Gitify" -order: 4 +order: 2 --- - -You can customize the look of Gitify from **Settings → Appearance**: +You can change how Gitify looks from **Settings → Appearance**. - **Design** — choose **Classic** or **Glass** -- **Theme** — choose **System** (follows your operating system), **Light**, or **Dark**. Additional themes are available depending on your design, including color-blind friendly and dimmed variants -- **Increase contrast** — toggle higher contrast for text and UI elements -- **Show status icon colors** — toggle colored status icons in the menu bar +- **Theme** — choose **System** (follows your operating system), **Light**, or **Dark**. Extra themes depend on your design, including color-blind friendly and dimmed variants +- **Increase contrast** — use higher contrast for text and UI +- **Show status icon colors** — show colored status icons in the menu bar - **Zoom** — zoom in, zoom out, or reset zoom for the whole app -- **Show account header** — toggle the account header in the sidebar -- **Show full notification title** — toggle full notification titles (otherwise they are truncated) +- **Show account header** — show the account header in the sidebar +- **Show full notification title** — show full notification titles instead of truncating them diff --git a/src/faqs/using-gitify/filters.md b/src/faqs/using-gitify/filters.md index a9f5c941..e0d5cc96 100644 --- a/src/faqs/using-gitify/filters.md +++ b/src/faqs/using-gitify/filters.md @@ -1,12 +1,11 @@ --- -title: "How do Filters work?" +title: "How do filters work?" category: "Using Gitify" -order: 1 +order: 0 --- +Filters let you hide notifications you do not need so you can focus on the ones that matter. -Filters in Gitify help you manage which notifications are shown in the app, allowing you to concentrate on the most crucial ones for your workflow. +Open **Filters** from the left-hand sidebar. By default, Gitify shows all notifications. You can filter by reason (for example _Mentioned_, _Review Requested_, or _Assigned_), repository, or account. -Filters can be accessed from the left-hand sidebar. By default, all notifications are shown. You can filter by properties such as notification reason (e.g. _Mentioned_, _Review Requested_, _Assigned_), repository, or account. - -If you apply multiple filters, your inbox will display notifications based on a `LOGICAL AND` condition — for example, selecting _Mentioned_ and a specific repository will only show notifications where both conditions are true. +If you turn on more than one filter, Gitify shows only notifications that match **every** selected filter. For example, _Mentioned_ plus a specific repository shows mentions in that repository only. diff --git a/src/faqs/using-gitify/keyboard-shortcuts.md b/src/faqs/using-gitify/keyboard-shortcuts.md index 0ca5a4a8..1a91c906 100644 --- a/src/faqs/using-gitify/keyboard-shortcuts.md +++ b/src/faqs/using-gitify/keyboard-shortcuts.md @@ -1,10 +1,9 @@ --- title: "How do keyboard shortcuts work?" category: "Using Gitify" -order: 5 +order: 3 --- - -Gitify includes keyboard shortcuts for common actions: +Gitify includes keyboard shortcuts for common actions. - `h` — go home - `n` — open My Notifications diff --git a/src/faqs/using-gitify/sounds-and-notifications.md b/src/faqs/using-gitify/sounds-and-notifications.md index 48511a48..da36325a 100644 --- a/src/faqs/using-gitify/sounds-and-notifications.md +++ b/src/faqs/using-gitify/sounds-and-notifications.md @@ -1,11 +1,10 @@ --- title: "How do I control sounds and system notifications?" category: "Using Gitify" -order: 6 +order: 1 --- +You can choose how Gitify alerts you to new notifications from **Settings → System**. -You can control how Gitify alerts you to new notifications from **Settings → System**: - -- **Show system notifications** — display native operating system notifications for new unread notifications +- **Show system notifications** — show native operating system notifications for new unread items - **Play sound** — play a sound when new notifications arrive -- **Volume** — use the volume buttons to adjust the notification sound level (or reset it) +- **Volume** — use the volume buttons to change the notification sound level, or reset it diff --git a/src/faqs/using-gitify/unsubscribe-from-thread.md b/src/faqs/using-gitify/unsubscribe-from-thread.md index 42b90faf..7893ca10 100644 --- 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 the Unsubscribe from Thread option do?" category: "Using Gitify" -order: 2 +order: 4 --- -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**. +**Unsubscribe from Thread** stops future notifications for that thread until you comment on it or get an **@mention**. -> **Note:** Depending on your notification subscription settings for the repository, you may continue to receive some notifications even after unsubscribing from a specific thread. \ No newline at end of file +> **Note:** Depending on your notification subscription settings for the repository, you may still get some notifications after unsubscribing from a single thread. diff --git a/src/faqs/using-gitify/updating.md b/src/faqs/using-gitify/updating.md index 982313df..dd3882aa 100644 --- a/src/faqs/using-gitify/updating.md +++ b/src/faqs/using-gitify/updating.md @@ -1,10 +1,10 @@ --- title: "How do I update Gitify?" category: "Using Gitify" -order: 3 +order: 5 --- -Gitify checks for updates automatically on launch and every 24 hours. +Gitify checks for updates when it starts and every 24 hours. -When an update is available, it downloads in the background. Once downloaded, a dialog will prompt you to **Restart** to apply the update or choose **Later** to apply it the next time Gitify restarts. +When an update is ready, it downloads in the background. Gitify then asks you to **Restart** now or choose **Later** to apply it the next time Gitify restarts. -You can also trigger a manual check by right-clicking the tray icon and selecting **Check for Updates**. \ No newline at end of file +To check manually, right-click the tray icon and select **Check for Updates**. diff --git a/src/pages/faq.astro b/src/pages/faq.astro index 1e3b5fb2..f4554f5c 100644 --- a/src/pages/faq.astro +++ b/src/pages/faq.astro @@ -55,9 +55,13 @@ const grouped = CATEGORY_ORDER.map((category) => ({
-
+
Frequently Asked Questions
+

+ Answers are grouped by topic. Use the copy-link control on a question to + share it. +

{grouped.map(({ category, faqs }) => (

{category}

@@ -150,25 +154,125 @@ document.querySelectorAll('.faq-item').forEach((item) => { summary.appendChild(btn); }); -// Open + scroll to item matching the URL hash -function openFromHash() { - const hash = window.location.hash.slice(1); - if (!hash) { +function slugifyHeading(text: string): string { + return text + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-+|-+$/g, ''); +} + +// Add heading ids, jump lists on long answers, and a Related footer +document.querySelectorAll('.faq-item').forEach((item) => { + const slug = item.id; + const content = item.querySelector('.faq'); + if (!content || !slug) { return; } - const wrapper = document.getElementById(hash); - if (!wrapper) { - return; + content.querySelectorAll('h3, h4').forEach((heading) => { + heading.id = `${slug}-${slugifyHeading(heading.textContent ?? '')}`; + }); + + const headings = content.querySelectorAll('h3'); + if (headings.length > 1) { + const nav = document.createElement('nav'); + nav.className = 'faq-jump'; + nav.setAttribute('aria-label', 'On this answer'); + + const label = document.createElement('span'); + label.className = 'faq-meta-label'; + label.textContent = 'Jump to'; + nav.appendChild(label); + + headings.forEach((heading) => { + const link = document.createElement('a'); + link.href = `#${heading.id}`; + link.textContent = heading.textContent ?? ''; + nav.appendChild(link); + }); + + content.insertBefore(nav, headings[0]); + } + + const paragraphs = content.querySelectorAll('p'); + const last = paragraphs[paragraphs.length - 1]; + if (last?.textContent?.trim().startsWith('Related:')) { + const links = last.querySelectorAll('a'); + if (links.length > 0) { + const nav = document.createElement('nav'); + nav.className = 'faq-related'; + nav.setAttribute('aria-label', 'Related questions'); + + const label = document.createElement('span'); + label.className = 'faq-meta-label'; + label.textContent = 'Related'; + nav.appendChild(label); + + links.forEach((link) => { + nav.appendChild(link.cloneNode(true)); + }); + + last.replaceWith(nav); + } + } +}); + +function faqTargetFromHash(hash: string): HTMLElement | null { + const id = hash.replace(/^#/, ''); + if (!id) { + return null; } - const details = wrapper.querySelector('details'); - if (details) { + return document.getElementById(id); +} + +function openAndScrollTo(target: HTMLElement) { + const wrapper = target.classList.contains('faq-item') + ? target + : target.closest('.faq-item'); + const details = wrapper?.querySelector('details'); + if (details && !details.open) { details.open = true; - wrapper.scrollIntoView({ behavior: 'smooth', block: 'start' }); + } + + requestAnimationFrame(() => { + requestAnimationFrame(() => { + target.scrollIntoView({ behavior: 'smooth', block: 'start' }); + }); + }); +} + +function openFromHash() { + const target = faqTargetFromHash(window.location.hash); + if (target) { + openAndScrollTo(target); } } +document.addEventListener('click', (event) => { + const anchor = (event.target as Element | null)?.closest('a'); + if (!anchor?.href) { + return; + } + + const url = new URL(anchor.href, window.location.href); + if (url.pathname !== window.location.pathname) { + return; + } + + const target = faqTargetFromHash(url.hash); + if (!target) { + return; + } + + event.preventDefault(); + if (window.location.hash !== url.hash) { + history.pushState(null, '', url.hash); + } + openAndScrollTo(target); +}); + openFromHash(); window.addEventListener('hashchange', openFromHash); +window.addEventListener('popstate', openFromHash); diff --git a/src/pages/index.astro b/src/pages/index.astro index a36f1d15..e57d1672 100644 --- a/src/pages/index.astro +++ b/src/pages/index.astro @@ -13,10 +13,10 @@ import SectionRow from '~/layouts/SectionRow.astro';
{openSourceLibs.map((item) => ( diff --git a/src/styles/app.css b/src/styles/app.css index 20f10f54..4cfefd2e 100644 --- a/src/styles/app.css +++ b/src/styles/app.css @@ -30,7 +30,8 @@ a:not(.gitify-repo) { } .faq ul > li { - @apply ml-2; + @apply ml-2 my-1; + overflow-wrap: break-word; } .faq ol { @@ -38,11 +39,49 @@ a:not(.gitify-repo) { } .faq ol > li { - @apply ml-2; + @apply ml-2 my-1; + overflow-wrap: break-word; } .faq h3 { - @apply mt-4 mb-2 text-base font-semibold; + @apply mt-6 mb-2 pb-1 text-sm font-semibold tracking-wide text-gray-700 dark:text-gray-300 border-b border-gray-200 dark:border-gray-700; + scroll-margin-top: 1rem; +} + +.faq h4 { + @apply mt-4 mb-1.5 text-sm font-semibold text-gray-800 dark:text-gray-200; + scroll-margin-top: 1rem; +} + +.faq-meta-label { + @apply text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400 mr-1; +} + +.faq-jump, +.faq-related { + @apply flex flex-wrap items-center gap-2 my-4 px-3 py-2.5 rounded-lg bg-gray-50 dark:bg-gray-800/70; +} + +.faq-jump { + @apply mb-5; +} + +.faq-jump + h3 { + @apply mt-2; +} + +.faq-related { + @apply mt-6; +} + +.faq-jump a, +.faq-related a { + @apply inline-flex items-center rounded-full px-2.5 py-1 text-sm font-semibold no-underline bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-600 text-gitify-button-rest; +} + +.faq-jump a:hover, +.faq-related a:hover { + @apply bg-blue-50 dark:bg-blue-950 border-blue-200 dark:border-blue-800; } .faq code { @@ -77,14 +116,12 @@ a:not(.gitify-repo) { @apply border-b-0; } -.accordion__title { - h3 { - @apply text-base font-medium; - } +.faq-item .accordion__title h3 { + @apply text-lg font-semibold; } -.accordion__content { - @apply text-base; +.faq-item .accordion__content { + @apply ml-1 pl-5 border-l-2 border-gray-200 dark:border-gray-700 text-base; } .faq-item summary {