diff --git a/deploy/github.mdx b/deploy/github.mdx index ec41a6cf18..67b4175ef7 100644 --- a/deploy/github.mdx +++ b/deploy/github.mdx @@ -98,6 +98,10 @@ When installing the GitHub App, you can grant access to all of your repositories Change the organization, repository, or branch that your documentation builds from in the [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) section of your dashboard. + + Switching the connected repository doesn't automatically migrate the [Mintlify Slack app](/agent/slack) or automation [Slack notifications](/automations/manage#slack-notifications). After you switch, reinstall the Slack app and reselect notification channels for each automation so notifications resume against the new repository. + + ## GitHub Enterprise with IP allowlists If your GitHub Enterprise Cloud organization has an IP allowlist enabled, you need to add Mintlify's egress IP address (`54.242.90.151`) to your allowlist for the GitHub App to function properly. diff --git a/deploy/preview-deployments.mdx b/deploy/preview-deployments.mdx index d54ac2ac42..5658fe1861 100644 --- a/deploy/preview-deployments.mdx +++ b/deploy/preview-deployments.mdx @@ -117,6 +117,7 @@ Mintlify generates preview URLs automatically. The subdomain and domain are not If your preview deployment fails, try these troubleshooting steps. +- **Pull request from a fork**: Automatic previews aren't created for pull requests opened from a forked repository, because the Mintlify GitHub App can't be installed on a fork you don't control. Push the contributor's branch to the upstream repository and open the pull request from there, or create a [manual preview](#manual-previews) against a branch in the upstream repository. - **View the build logs**: In your [dashboard](https://app.mintlify.com/), go to **Previews** and click the failed preview. The deployment logs show errors that caused failures. - **Check your configuration**: - Missing `docs.json` at the configured content root. If your `docs.json` is in a subdirectory, confirm the **docs.json is in a subdirectory** setting points to the correct path. diff --git a/editor/branching-and-publishing.mdx b/editor/branching-and-publishing.mdx index 288f5d155f..c5c0c5118d 100644 --- a/editor/branching-and-publishing.mdx +++ b/editor/branching-and-publishing.mdx @@ -183,3 +183,53 @@ Sign commits with your GitHub account by authorizing it in your [account setting For a reference of how editor actions map to Git operations, see [Git essentials](/editor/git-essentials#how-the-editor-maps-to-git). +## Troubleshooting + +### The editor prompts you to connect GitHub and won't load + +If the editor shows a **Connect GitHub** prompt or gets stuck after you accept one, the editor session lost its link to the Mintlify GitHub App. This usually happens after the app is uninstalled, its permissions change, or the repository is switched in [Git Settings](https://app.mintlify.com/settings/deployment/git-settings). + +Reset the connection to restore the editor: + + + + Follow the reset steps in [GitHub app connection issues](/deploy/github#github-app-connection-issues) to uninstall, revoke, and reinstall the Mintlify GitHub App. + + + In your [GitHub App settings](https://github.com/apps/mintlify/installations/new), grant the app access to the repository shown in [Git Settings](https://app.mintlify.com/settings/deployment/git-settings). + + + Close the editor tab and reopen it from your [dashboard](https://app.mintlify.com/). The prompt should be gone and the editor should load on your deployment branch. + + + +If the prompt returns after reinstalling, your GitHub organization may require admin approval for the app installation. Ask an organization owner to approve the request, then reload the editor. + +### A pull request action returns a 502 or other transient error + +Merging, approving, or creating a pull request from the publish menu can occasionally fail with a **502 Bad Gateway** or similar transient error when GitHub, GitLab, or the Mintlify API is slow to respond. The commit is often created even when the response fails. + +1. Refresh the editor and reopen the publish menu. +1. Check the pull request in your Git provider to confirm whether the merge or approval already went through. +1. If the pull request is still open, retry the action from the publish menu. +1. If retries keep failing, complete the merge or approval directly in GitHub or GitLab. The editor picks up the merged state on its next Git sync. + +### Preview deployments aren't created for pull requests from forks + +Mintlify does not generate [preview deployments](/deploy/preview-deployments) for pull requests opened from a forked repository. The Mintlify GitHub App can only run on repositories it's installed in, and it can't be installed on a fork you don't control. + +To preview changes from an external contributor: + +- Ask the contributor to open the pull request from a branch in the upstream repository if they have write access. +- Otherwise, check out the fork's branch locally, push it to a branch in the upstream repository, and open a pull request from that branch. The preview builds against the upstream branch. +- Alternatively, create a [manual preview](/deploy/preview-deployments#manual-previews) from your dashboard against a branch in the upstream repository that mirrors the fork's changes. + +### Slack notifications stop after switching the connected repository + +Changing the organization, repository, or branch in [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) doesn't migrate the Slack integration. Automation Slack notifications and the Mintlify Slack agent continue to point at the previous deployment's configuration until you reconnect them. + +After you switch repositories: + +1. Reinstall the Mintlify Slack app from the [Agent](https://app.mintlify.com/products/agent) page of your dashboard. See [Reconnect or reinstall the agent](/agent/slack#reconnect-or-reinstall-the-agent). +1. Reselect the notification channels for each automation on the [Automations](https://app.mintlify.com/products/automations) page. See [Slack notifications](/automations/manage#slack-notifications). +