Merge pull request circleci#3662 from circleci/michelle-luna-patch-7

update gh-bb-integration doc

Author: michelle-luna

jekyll/_cci2/gh-bb-integration.md

@@ -54,6 +54,18 @@ Integrated status also appears on the pull request screen, to show that all test
 
 ![Status Badge After PR]({{ site.baseurl }}/assets/img/docs/status_check.png)
 
+## Best Practices for Keys
+
+- Use Deploy Keys whenever possible.
+- When Deploy Keys cannot be used, Machine User Keys must be used, and have their access restricted to the most limited set of repos and permissions necessary.
+- Never use non-Machine user keys (keys should be associated with the build, not with a specific person).
+- You must rotate the Deploy or User key as part of revoking user access to that repo.
+    1. After revoking the user’s access in github, delete keys in GitHub.
+    2. Delete the keys in the CircleCI project.
+    3. Regenerate the keys in CircleCI project.
+- Ensure no developer has access to a build in a repo with a User Key that requires more access than they have.
+
+
 ## Enable Your Project to Check Out Additional Private Repositories
 
 If your testing process refers to multiple repositories, CircleCI will need a
@@ -92,7 +104,7 @@ Permission denied (publickey).
 ## Controlling Access Via a Machine User
 
 For fine-grained access to multiple repositories,
-consider creating a machine user
+it is best practice to create a machine user
 for your CircleCI projects.
 A [machine user](https://developer.github.com/v3/guides/managing-deploy-keys/#machine-users) is a GitHub user
 that you create for running automated tasks.
@@ -210,7 +222,7 @@ If you want to push to the repository from your builds, you will need a deployme
 
 A user key is a user-specific SSH key. Your VCS has the public key, and CircleCI stores the private key. Possession of the private key gives the ability to act as that user, for purposes of 'git' access to projects.
 
-### Creating a GitHub User Key
+### Creating a GitHub Deploy Key
 {:.no_toc}
 
 In this example,
@@ -306,7 +318,7 @@ For this reason, a deploy key isn't sufficiently powerful for projects with addi
 
 ### What about security?
 
-The private keys of the checkout keypairs CircleCI generates never leave the CircleCI systems (only the public key is transmitted to GitHub) and are safely encrypted in storage. However, since they are installed into your build containers, any code that you run in CircleCI can read them.
+The private keys of the checkout keypairs CircleCI generates never leave the CircleCI systems (only the public key is transmitted to GitHub) and are safely encrypted in storage. However, since the keys are installed into your build containers, any code that you run in CircleCI can read them. Likewise, developers that can SSH in will have direct access to this key.
 
 **Isn't there a difference between deploy keys and user keys?**