more docs, add installation step

runatlantis.io/docs/access-credentials.md

@@ -7,7 +7,7 @@ that Atlantis will use to make API calls.
 ## Create an Atlantis user (optional)
 We recommend creating a new user named **@atlantis** (or something close) or using a dedicated CI user.
 
-This isn't required (you can use an existing user), however all the comments that Atlantis writes
+This isn't required (you can use an existing user or github app credentials), however all the comments that Atlantis writes
 will come from that user so it might be confusing if its coming from a personal account.
 
 ![Example Comment](./images/example-comment.png)
@@ -16,13 +16,14 @@ will come from that user so it might be confusing if its coming from a personal
 ## Generating an Access Token
 Once you've created a new user (or decided to use an existing one), you need to
 generate an access token. Read on for the instructions for your specific Git host:
-* [GitHub](#github)
+* [GitHub](#github-user)
+* [GitHub app](#github-app)
 * [GitLab](#gitlab)
 * [Bitbucket Cloud (bitbucket.org)](#bitbucket-cloud-bitbucket-org)
 * [Bitbucket Server (aka Stash)](#bitbucket-server-aka-stash)
 * [Azure DevOps](#azure-devops)
 
-### GitHub
+### GitHub user
 - Create a Personal Access Token by following: [https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token)
 - Create the token with **repo** scope
 - Record the access token
@@ -31,6 +32,16 @@ Your Atlantis user must also have "Write permissions" (for repos in an organizat
 ![Atlantis status](./images/status.png)
 :::
 
+### GitHub app
+- Start Atlantis with fake github username and token
+- Visit `$ATLANTIS_HOST/github-app/setup` and click on **Setup** to create the app on Github. You'll be redirected back to Atlantis
+- A link to install your app, along its secrets, will be shown on the screen. Record your app's credentials and install your app for your user/org by following said link.
+- Restart Atlantis
+
+::: warning
+Only a single installation per Github App is supported at the moment.
+:::
+
 ### GitLab
 - Follow: [https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#creating-a-personal-access-token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#creating-a-personal-access-token)
 - Create a token with **api** scope

server/events/vcs/github_client.go

@@ -41,10 +41,15 @@ type GithubClient struct {
 
 // GithubAppTemporarySecrets hold app credentials obtained from github after creation
 type GithubAppTemporarySecrets struct {
-	ID            int64
-	Key           string
-	Name          string
+	// The app ID
+	ID int64
+	// The app's PEM-encoded key
+	Key  string
+	Name string
+	// The generated webhook secret for this app
 	WebhookSecret string
+	// A link to the app, like https://github.com/apps/octoapp
+	URL string
 }
 
 // NewGithubClient returns a valid GitHub client.
@@ -331,6 +336,7 @@ func (g *GithubClient) ExchangeCode(code string) (*GithubAppTemporarySecrets, er
 		Key:           cfg.GetPEM(),
 		WebhookSecret: cfg.GetWebhookSecret(),
 		Name:          cfg.GetName(),
+		URL:           cfg.GetHTMLURL(),
 	}
 
 	return data, err

server/events/working_dir.go

@@ -314,11 +314,7 @@ func (g *GithubAppWorkingDir) Clone(log *logging.SimpleLogger, baseRepo models.R
 	}
 
 	authURL := fmt.Sprintf("://x-access-token:%s", token)
-	if baseRepo.CloneURL != "" {
-		baseRepo.CloneURL = strings.Replace(baseRepo.CloneURL, "://:", authURL, 1)
-	}
-	if headRepo.CloneURL != "" {
-		headRepo.CloneURL = strings.Replace(headRepo.CloneURL, "://:", authURL, 1)
-	}
+	baseRepo.CloneURL = strings.Replace(baseRepo.CloneURL, "://:", authURL, 1)
+	headRepo.CloneURL = strings.Replace(headRepo.CloneURL, "://:", authURL, 1)
 	return g.WorkingDir.Clone(log, baseRepo, headRepo, p, workspace)
 }

server/github_app_controller.go

@@ -74,6 +74,7 @@ func (g *GithubAppController) ExchangeCode(w http.ResponseWriter, r *http.Reques
 		ID:            app.ID,
 		Key:           app.Key,
 		WebhookSecret: app.WebhookSecret,
+		URL:           app.URL,
 	})
 	if err != nil {
 		g.Logger.Err(err.Error())

server/web_templates.go

@@ -237,6 +237,7 @@ type GithubSetupData struct {
 	ID            int64
 	Key           string
 	WebhookSecret string
+	URL           string
 }
 
 var githubAppSetupTemplate = template.Must(template.New("github-app.html.tmpl").Parse(`
@@ -309,7 +310,7 @@ var githubAppSetupTemplate = template.Must(template.New("github-app.html.tmpl").
       <button type="submit">Setup</button>
     </form>
     {{ else }}
-      <p>Please update the following values in your config and restart Atlantis:</p>
+      <p>Visit <a href="{{ .URL }}/installations/new" target="_blank">{{ .URL }}/installations/new</a> to install the app for your user or organization, then <strong>update the following values</strong> in your config and <strong>restart Atlantis<strong>:</p>
 
       <ul>
         <li class="config"><strong>gh-app-id:</strong> <pre>{{ .ID }}</pre></li>