Document AutoScan for SonarCloud (#1245)

3 files changed, 124 insertions, 11 deletions

diff --git a/server/sonar-docs/src/pages/sonarcloud/autoscan.md b/server/sonar-docs/src/pages/sonarcloud/autoscan.md
new file mode 100644
index 00000000000..6af5fa03961
--- /dev/null
+++ b/server/sonar-docs/src/pages/sonarcloud/autoscan.md
@@ -0,0 +1,96 @@
+---
+title: AutoScan Beta Feature
+nav: AutoScan
+url: /autoscan/
+---
+
+SonarCloud can autonomously scan your code, by simply reading it from your repository! We call that AutoScan.
+
+[[info]]
+| This is currently a Beta feature, with a limited scope and some caveats. Those limitations will be removed along the way.
+
+
+## Prerequisites
+
+* The first version of this Beta feature works only for GitHub repositories. 
+* The automatic analysis can be activated only on projects which were set up through the SonarCloud web interface.
+
+## What to expect
+
+Once activated, SonarCloud will automatically analyze: 
+* the default branch of the repository
+* the pull requests (PR) on that default branch
+
+It will take care of doing it whenever you push on your repository.
+
+The following languages are currently supported: 
+* ABAP
+* Apex
+* CSS
+* Flex
+* Go
+* HTML
+* JS
+* Kotlin
+* PHP
+* PL/SQL
+* Python
+* Ruby
+* Scala
+* Swift
+* TypeScript
+* TSQL
+* XML
+
+## How to activate the feature?
+
+To enable the automatic analysis, you need to add a `.sonarcloud.properties` file in your repository.
+
+If you're starting from scratch:
+
+1. Do the [setup for your project](/#sonarcloud#/projects/create) (from the `+ > Analyze new project` top right menu)
+    * ![](/images/exclamation.svg) Remember that your project must absolutely be created by selecting a GitHub repository - otherwise it won't work.
+1. Once the setup is done on SonarCloud, you end up on the project home page which shows a tutorial. Ignore it and simply add a `.sonarcloud.properties` file in the base directory of your default branch (or on a PR which targets this default branch). 
+1. After a while, the analysis results will be visible in SonarCloud (and your PR will be annotated with comments if you pushed the file on a PR)
+
+Here are the supported optional settings for the `.sonarcloud.properties` file:
+```
+# Path to sources
+#sonar.sources=.
+#sonar.exclusions=
+#sonar.inclusions=
+
+# Path to tests
+#sonar.tests=
+#sonar.test.exclusions=
+#sonar.test.inclusions=
+
+# Source encoding
+#sonar.sourceEncoding=UTF-8
+
+# Exclusions for copy-paste detection
+#sonar.cpd.exclusions=
+```
+
+Note that you can just push an empty `.sonarcloud.properties` file, this will work fine. In this case, every file in the repository will be considered as a source file.
+
+## Current limitations/caveats
+
+* There is no visual feedback (yet) in the UI when SonarCloud runs an analysis.
+* A consequence of the previous point is that if - for any reason, SonarCloud fails to successfully run the analysis, nothing will be displayed. In that case, just come on [the forum](https://community.sonarsource.com/tags/c/help/sc/autoscan) and ask a question, we'll monitor that closely.
+* Pull requests from forks are not analyzed (only PRs from the same repository)
+* Code coverage information is not supported
+* Import of external rule engine reports is not supported
+
+## Noteworthy
+
+* This Beta feature works for any project - public or private.
+* It can be activated with no extra cost.
+* Sources are cloned only during the analysis, and only when the `.sonarcloud.properties` file exists (i.e. when the feature is activated). The cloned repository is fully deleted at the end of the analysis, and SonarCloud does not keep a copy of it.
+* Non supported languages (Java, C#, VB.NET, C/C++, ObjectiveC) are not analyzed at all.
+
+## How to give feedback?
+
+Create a new thread on the forum, under ["Get Help > SonarCloud"](https://community.sonarsource.com/tags/c/help/sc/autoscan), with the "autoscan" tag.
+
+We'd love to hear your feedback about this new upcoming feature, may it be about bugs, improvements, or anything you want to share with us!
diff --git a/server/sonar-docs/src/pages/sonarcloud/integrations/github.md b/server/sonar-docs/src/pages/sonarcloud/integrations/github.md
index 74b87569486..2349f929649 100644
--- a/server/sonar-docs/src/pages/sonarcloud/integrations/github.md
+++ b/server/sonar-docs/src/pages/sonarcloud/integrations/github.md
@@ -3,26 +3,40 @@ title: GitHub
 url: /integrations/github/
 ---
 
-You can connect to SonarCloud using your GitHub account. On the [login page](/#sonarcloud#/sessions/new), just click on the "Log in with GitHub" button.
+## Sign up and set up your first project
+
+1. On the [login page](/#sonarcloud#/sessions/new), click on the "Log in with GitHub" button and connect to SonarCloud using your GitHub account.
+2. Click on "Analyze your code" and follow the path to set up a first project
+3. You will be asked to install the SonarCould application on your organization, which will allow you to choose which
+   repository you want to analyze.
 
 ## Trigger analyses
 
-SonarCloud currently does not trigger analyses automatically. It's up to you to launch them inside your
-existing CI scripts. Please follow the [tutorial](/#sonarcloud#/onboarding) to get started.
+For GitHub repositories, there are 2 ways to have your code analyzed:
+
+### ... with AutoScan
+
+With AutoScan, SonarCloud will autonomously pull your code and scan your default branch and your pull requests.
+Please read the ["AutoScan Beta Feature"](/autoscan/) documentation page to get the details.
+
+![](/images/exclamation.svg) This is currently a Beta feature which does not work for all languages and comes with limitations. 
 
-### Using Travis CI?
+### ... using your CI service
+
+If AutoScan does not make sense yet for your repository, you need to configure your CI service to trigger the analysis.
+
+**If you are using Travis CI**, the SonarCloud Travis Add-on will make it easier to activate analyses:
 
-If you are using Travis CI, the SonarCloud Travis Add-on will make it easier to activate analyses: 
 * Read the [guide to integrate with Travis CI](https://docs.travis-ci.com/user/sonarcloud/)
 * Check out the [various sample projects](https://github.com/SonarSource/sonarcloud_examples) (Java, TypeScript, C/C++, Go, ... etc) that are analyzed on SonarCloud on a frequent basis
 
-## Activating pull request decoration
+**If you are using another CI service**, you will need to read:
 
-To have your pull requests decorated by SonarCloud in GitHub, you need to [install the SonarCloud application](https://github.com/apps/sonarcloud) on your GitHub organization(s).
-
-Once installed, there is nothing more to do if you are using the Travis Add-on. In any other case, you will need
-to pass the following properties in your script during the analysis:
+* the ["Analyzing Source Code" overview page](/analysis/overview/)
+* the ["Branches" overview page](/branches/overview/)
+* the ["Pull Request Analysis" page](/analysis/pull-request/)
 
+Here is an example of configuration for pull requests when you are not on Travis CI and you need to configure your CI jobs:
 ```
 sonar.pullrequest.base=master
 sonar.pullrequest.branch=feature/my-new-feature
@@ -30,3 +44,6 @@ sonar.pullrequest.key=5
 sonar.pullrequest.provider=GitHub
 sonar.pullrequest.github.repository=my-company/my-repo
 ```
+
+[[info]]
+| Pull request decoration works only if [the SonarCloud application](https://github.com/apps/sonarcloud) is installed on your GitHub organization(s) and configured to have acccess to the repositories.
diff --git a/server/sonar-docs/static/SonarCloudNavigationTree.json b/server/sonar-docs/static/SonarCloudNavigationTree.json
index a058cd055cc..d6005e9ae8b 100644
--- a/server/sonar-docs/static/SonarCloudNavigationTree.json
+++ b/server/sonar-docs/static/SonarCloudNavigationTree.json
@@ -64,6 +64,6 @@
   },
   {
     "title": "Appendices",
-    "children": ["/sonarcloud-pricing/", "/privacy/", "/security/", "/faq/"]
+    "children": ["/sonarcloud-pricing/", "/privacy/", "/security/", "/faq/", "/autoscan/"]
   }
 ]