add GitHub OAuth error solution (#540)

ericpaulsen · web-flow · commit 70576b8ca50a · 2021-08-06T15:09:42.000-05:00
diff --git a/assets/guides/troubleshooting/oauth-error.png b/assets/guides/troubleshooting/oauth-error.png
diff --git a/guides/troubleshooting/docker-problems.md b/guides/troubleshooting/docker-problems.md
@@ -1,5 +1,5 @@
 ---
-title: Docker troubleshooting
+title: Docker
 description: Learn how to solve Docker issues inside Coder workspaces.
 ---
 
@@ -21,7 +21,7 @@ and size of keys each user can have.
 ## Resolution
 
 To fix this error, you can increase `maxkeys` and `maxbytes`. These are global
-settings that apply to *all* users sharing the same system. You can modify this
+settings that apply to _all_ users sharing the same system. You can modify this
 by adding the following to the `sysctl` configuration file:
 
 ```console
diff --git a/guides/troubleshooting/git-oauth.md b/guides/troubleshooting/git-oauth.md
@@ -0,0 +1,34 @@
+---
+title: GitHub OAuth integration
+description: Learn how to fix a "Failed to link account" OAuth error.
+---
+
+When configuring the OAuth integration between Coder and GitHub, you may
+encounter the following error:
+
+![Failed to link](../../assets/guides/troubleshooting/oauth-error.png)
+
+## Why this happens
+
+This error occurs when your Coder public key has been uploaded to your GitHub
+profile; when you attempt to link Coder and GitHub, the OAuth integration
+attempts to add your public key again to GitHub.
+
+## Solution
+
+1. [Remove your Coder public key](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/reviewing-your-ssh-keys)
+   from your GitHub account.
+
+1. In Coder, navigate to **Account** > **Linked Accounts** and click **Link Your
+   GitHub Account**.
+
+1. If successful, you will be re-directed back to the **Account** page. There
+   will be a message in the bottom right corner that says:
+
+   ```console
+   Successfully linked to GitHub account <your-GitHub-username>
+   ```
+
+If the steps above do not fix the problem, the error may be related to the
+GitHub configuration values set using Coder's **Admin** panel. Site managers can
+view and update these values at **Manage** > **Admin** > **Git OAuth**.
diff --git a/guides/troubleshooting/registry.md b/guides/troubleshooting/registry.md
@@ -1,5 +1,5 @@
 ---
-title: Image registry troubleshooting
+title: Image registry
 description: Learn how to resolve issues connecting to an image registry.
 ---
 
@@ -18,8 +18,7 @@ certificate signed by unknown authority
 The local registry you are configuring is expecting a valid certificate to
 authenticate the connection with Coder. You will receive this error if:
 
-- You do not have a certificate
-configured
+- You do not have a certificate configured
 - There is an issue with the certificate itself
 
 > Coder uses Docker's Registry 2.0 implementation, which supports self-signed
@@ -28,8 +27,9 @@ configured
 ## Troubleshooting steps
 
 - If you haven't created the local registry, and you haven't generated the
-  self-signed certificate, [please see our
-  documentation](../../setup/air-gapped/infrastructure.md) on setting these up.
+  self-signed certificate,
+  [please see our documentation](../../setup/air-gapped/infrastructure.md) on
+  setting these up.
 
 - Check to see if your `registry.crt` file is stored in the correct location on
   each of your Kubernetes nodes. Depending upon your Linux distribution and
@@ -53,9 +53,9 @@ configured
 Ensure that you've created the self-signed certificate secret in your Kubernetes
 cluster:
 
-  ```console
-  kubectl -n coder get secret local-registry-cert -o yaml
-  ```
+```console
+kubectl -n coder get secret local-registry-cert -o yaml
+```
 
-If none of these steps resolve the issue, please [contact
-us](https://coder.com/contact) for further support.
+If none of these steps resolve the issue, please
+[contact us](https://coder.com/contact) for further support.
