Move some duplicate documentation, link across multiple pages and clarify some texts

doc/05-repositories.md

@@ -316,23 +316,10 @@ Please note:
 
 #### BitBucket Driver Configuration
 
-The BitBucket driver uses OAuth to access your private repositories via the BitBucket REST APIs, and you will need to create an OAuth consumer to use the driver, please refer to [Atlassian's Documentation](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html). You will need to fill the callback url with something to satisfy BitBucket, but the address does not need to go anywhere and is not used by Composer.
+> **Note that the repository endpoint for BitBucket needs to be https rather than git.**
 
-After creating an OAuth consumer in the BitBucket control panel, you need to setup your auth.json file with
+After setting up your bitbucket repository, you will also need to set up authentication.
-the credentials like this (more info [here](https://getcomposer.org/doc/06-config.md#bitbucket-oauth)):
+Documentation for that [has moved here](articles/authentication-for-private-packages.md#bitbucket-oauth)
-```json
-{
-    "bitbucket-oauth": {
-        "bitbucket.org": {
-            "consumer-key": "myKey",
-            "consumer-secret": "mySecret"
-        }
-    }
-}
-```
-**Note that the repository endpoint needs to be https rather than git.**
-
-Alternatively if you prefer not to have your OAuth credentials on your filesystem you may export the ```bitbucket-oauth``` block above to the [COMPOSER_AUTH](https://getcomposer.org/doc/03-cli.md#composer-auth) environment variable instead.
 
 #### Subversion Options
 

doc/06-config.md

@@ -82,6 +82,7 @@ A list of domain names and oauth keys. For example using `{"gitlab.com":
 private repositories on gitlab. Please note: If the package is not hosted at
 gitlab.com the domain names must be also specified with the
 [`gitlab-domains`](06-config.md#gitlab-domains) option.
+Further info can also be found [here](articles/authentication-for-private-packages.md#gitlab-oauth)
 
 ## gitlab-token
 
@@ -95,6 +96,7 @@ Please note: If the package is not hosted at
 gitlab.com the domain names must be also specified with the
 [`gitlab-domains`](06-config.md#gitlab-domains) option. The token must have
 `api` or `read_api` scope.
+Further info can also be found [here](articles/authentication-for-private-packages.md#gitlab-token)
 
 ## disable-tls
 
@@ -114,8 +116,8 @@ get a free SSL certificate is generally a better alternative.
 ## bitbucket-oauth
 
 A list of domain names and consumers. For example using `{"bitbucket.org":
-{"consumer-key": "myKey", "consumer-secret": "mySecret"}}`. [Read](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html)
+{"consumer-key": "myKey", "consumer-secret": "mySecret"}}`.
-how to set up a consumer on Bitbucket.
+Read more [here](articles/authentication-for-private-packages.md#bitbucket-oauth).
 
 ## cafile
 
@@ -134,11 +136,7 @@ capath must be a correctly hashed certificate directory.
 A list of domain names and username/passwords to authenticate against them. For
 example using `{"example.org": {"username": "alice", "password": "foo"}}` as the
 value of this option will let Composer authenticate against example.org.
-
+More info can be found [here](articles/authentication-for-private-packages.md#http-basic).
-> **Note:** Authentication-related config options like `http-basic`, `bearer` and
-> `github-oauth` can also be specified inside a `auth.json` file that goes
-> besides your `composer.json`. That way you can gitignore it and every
-> developer can place their own credentials in there.
 
 ## bearer
 

doc/articles/authentication-for-private-packages.md

@@ -1,13 +1,12 @@
 <!--
-    tagline: Access privately hosted packages
+    tagline: Access privately hosted packages/repositories
 -->
 
-# Authentication for privately hosted packages
+# Authentication for privately hosted packages and repositories
 
-Your [private package server](handling-private-packages.md) is probably secured with one
+Your [private package server](handling-private-packages.md) or version control system is probably secured with one
 or more authentication options. In order to allow your project to have access to these
-packages you will have to tell Composer how to authenticate with the server that hosts the
+packages and repositories you will have to tell Composer how to authenticate with the server that hosts them.
-package(s).
 
 # Authentication principles
 
@@ -53,6 +52,8 @@ For all authentication methods it is possible to edit them using the command lin
  - [Inline http-basic](#command-line-inline-http-basic)
  - [gitlab-oauth](#command-line-gitlab-oauth)
  - [gitlab-token](#command-line-gitlab-token)
+ - [github-oauth](#command-line-github-oauth)
+ - [bitbucket-oauth](#command-line-bitbucket-oauth)
 
 ### Manually editing global authentication credentials
 
@@ -71,6 +72,8 @@ For specific authentication implementations, see their sections;
  - [custom header](#manual-custom-token-authentication)
  - [gitlab-oauth](#manual-gitlab-oauth)
  - [gitlab-token](#manual-gitlab-token)
+ - [github-oauth](#manual-github-oauth)
+ - [bitbucket-oauth](#manual-bitbucket-oauth)
 
 Manually editing this file instead of using the command line may result in invalid json errors.
 To fix this you need to open the file in an editor and fix the error. To find the location of
@@ -97,12 +100,13 @@ section or directly in the repository definition.
 
 ## Authentication using the COMPOSER_AUTH environment variable
 
-> **Note:** Using this method also has security implications.
+> **Note:** Using the command line environment variable method also has security implications.
-> Credentials passed using command line environment variables will most likely be stored in memory,
+> These credentials will most likely be stored in memory,
 > and on be persisted to a file like ```~/.bash_history```(linux) or ```ConsoleHost_history.txt```
-> (Powershell on Windows) when closing a session.
+> (PowerShell on Windows) when closing a session.
 
 The final option to supply Composer with credentials is to use the ```COMPOSER_AUTH``` environment variable.
+These variables can be either passed as command line variables or set in actual environment variables.
 Read more about the usage of this environment variable [here](../03-cli.md#COMPOSER_AUTH).
 
 # Authentication methods
@@ -217,6 +221,8 @@ composer config [--global] --editor --auth
 > **Note:** For the gitlab authentication to work on private gitlab instances, the
 > [`gitlab-domains`](../06-config.md#gitlab-domains) section should also contain the url.
 
+When creating a gitlab token manually, make sure it has either the ```read_api``` or ```api``` scope.
+
 ### Command line gitlab-token
 
 ```sh
@@ -264,7 +270,7 @@ composer config [--global] --editor --auth
 
 ## bitbucket-oauth
 
-Read more about how to set up oauth on bitbucket [here](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/).
+The BitBucket driver uses OAuth to access your private repositories via the BitBucket REST APIs, and you will need to create an OAuth consumer to use the driver, please refer to [Atlassian's Documentation](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/). You will need to fill the callback url with something to satisfy BitBucket, but the address does not need to go anywhere and is not used by Composer.
 
 ### Command line bitbucket-oauth