WIP fixes-for-upstream-pr-1807

.vale.ini

@@ -1,5 +1,5 @@
-# Vale configuration file, taken from https://errata-ai.github.io/vale/config/
-
+# Vale configuration file, taken from https://docs.errata.ai/vale/config
+#
 # The relative path to the folder containing linting rules (styles)
 # -----------------------------------------------------------------
 StylesPath = .vale/styles
@@ -13,7 +13,7 @@ Vocab = Che
 # unless you execute Vale with the --no-exit flag
 MinAlertLevel = suggestion
 IgnoredScopes = code, tt, img, url, a
-SkippedScopes = script, style, pre, figure
+SkippedScopes = script, style, pre, figure, code, tt
 
 
 # What file types should Vale test?

.vale/styles/CheDocs/CommonTerms.yml

@@ -4,10 +4,10 @@ message: Consider using '%s' instead of '%s'
 ignorecase: false
 level: warning
 swap:
-  '\sche': '{prod-short}'
-  '\sChe': '{prod-short}'
+  '\sche': "{prod-short}"
+  '\sChe': "{prod-short}"
   '\sContainer Registry': Red Hat Ecosystem Catalog
-  '\sContainer Catalog': Red Hat Ecosystem Catalog 
+  '\sContainer Catalog': Red Hat Ecosystem Catalog
   '\s[^n] binary': tool
   '\sconfig map': ConfigMap
   '\sconfig maps': ConfigMaps

.vale/styles/Vocab/Che/accept.txt

@@ -2,30 +2,26 @@
 adoc
 Antora
 API
-Asciidoc
+AsciiDoc
 AWS
-boolean
-Boolean
+Bitbucket
+boolean|Boolean
 breakpoint
 btn
 Btrfs
 CentOS
-CentOS
 Ceph
 Che-Theia
-Che-Theia
-Classloading|classloading
+classloading|Classloading
 ConfigMap
 ConfigMaps
 DaemonSet
-DaemonSet
 Developer Perspective
 devfile
 devfiles
 DNS
 Docker
 Dockerfile
-Dockerfile
 Dotnet
 Endevor
 endif

modules/administration-guide/nav.adoc

@@ -10,7 +10,6 @@
 ** xref:building-custom-registry-images.adoc[]
 ** xref:running-custom-registries.adoc[]
 
-
 * xref:retrieving-che-logs.adoc[]
 ** xref:configuring-server-logging.adoc[]
 ** xref:viewing-kubernetes-events.adoc[]
@@ -40,5 +39,5 @@
 ** xref:authenticating-users.adoc[]
 ** xref:authorizing-users.adoc[]
 ** xref:configuring-authorization.adoc[]
-** xref:removing-user-data.adoc[]
 ** xref:configuring-openshift-oauth.adoc[]
+** xref:removing-user-data.adoc[]

modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc

@@ -7,7 +7,7 @@
 
 :context: managing-identities-and-authorizations
 
-This section describes different aspects of managing identities and authorizations of {prod}
+This section describes different aspects of managing identities and authorizations of {prod}.
 
 * xref:authenticating-users.adoc[]
 * xref:authorizing-users.adoc[]

modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc

@@ -2,78 +2,46 @@
 //
 // Configuring Bitbucket server OAuth1
 
+pass:[<!-- vale IBM.Headings = NO -->]
 
 [id="proc_configuring-bitbucket-server-oauth1_{context}"]
-= Configuring Bitbucket server OAuth1
+= Configuring Bitbucket Server OAuth 1
 
-OAuth1 for Bitbucket server allows for automatic obtaining and renewing link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Personal access tokens]. These tokens {prod-short} used to resolve devfile in a factory flow or it  xref:end-user-guide:authentication-against-bitbucket-server-with-the-personal-access-token.adoc[can be used in place of passwords for Git over HTTPS].
+pass:[<!-- vale IBM.Headings = YES -->]
 
+This procedure describes how to activate OAuth 1 for Bitbucket Server to:
+
+* Use devfiles hosted on a Bitbucket Server.
+* xref:end-user-guide:authentication-against-bitbucket-server-with-the-personal-access-token.adoc[].
+
+It enables {prod-short} to obtain and renew link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Bitbucket Server Personal access tokens].
 
 .Prerequisites
 
 * The `{orch-cli}` tool is available.
-* Bitbucket server installed and reachable from {prod-short} server.
+* Bitbucket Server is available from {prod-short} server.
 
 .Procedure
 
-. Generate RSA key pair as described below or follow this guide: link:https://confluence.atlassian.com/jirakb/how-to-generate-public-key-to-application-link-3rd-party-applications-913214098.html[How to generate public key to application link 3rd party applications]
-+
-[subs="+quotes,+attributes"]
-----
-openssl genrsa -out private.pem 2048
-openssl rsa -in private.pem -pubout > public.pub
-openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in private.pem -out privatepkcs8.pem
-----
-. Generate consumer key and shared secret.
+. Generate a RSA key pair and a stripped down version of the public key: 
 +
 [subs="+quotes,+attributes"]
 ----
-openssl rand -base64 24 > bitbucket_server_consumer_key
-openssl rand -base64 24 > bitbucket_shared_secret
+openssl genrsa -out __<private.pem>__ 2048
+openssl rsa -in __<private.pem>__ -pubout > __<public.pub>__
+openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in __<private.pem>__ -out __<privatepkcs8.pem>__
+cat __<public.pub>__ | sed 's/-----BEGIN PUBLIC KEY-----//g' | sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n' > __<public-stripped.pub>__
 ----
-.  Configure an link:https://confluence.atlassian.com/adminjiraserver/using-applinks-to-link-to-other-applications-938846918.html[Application Link] in Bitbucket to allow {prod-short} communicate with your enterprise Bitbucket server.
-.. To create the Application Link:
-  In Bitbucket Server, go to **Administration** (select the cog in the top navigation bar)  > **Application Links**.
-+
-image::bitbucket/bitbucket_configure_application_links.png[link="../_images/bitbucket/bitbucket_configure_application_links.png"]
-..  Enter the application URL (see Application Link details page) and select **Create new link**.
-..  Select **Continue** on the warning message. This is not a problem.
-..  Complete the form:
-   - Application Name - Enter a name to help you identify this {prod-short} instance.
-   - Application Type - Leave as Generic Application.
-   - Service Provider Name - Enter the same name you used for Application Name.
-   - Consumer Key - Specify a consumer key. That is the content of `bitbucket_server_consumer_key` file.
-   - Shared secret - Specify shared secret. That is the content of `bitbucket_shared_secret` file.
-   - Request Token URL - `{your Bitbucket Server URL}/plugins/servlet/oauth/request-token`.
-   - Access token URL - `{your Bitbucket Server URL}/plugins/servlet/oauth/access-token`.
-   - Authorize URL - `{your Bitbucket Server URL}/plugins/servlet/oauth/access-token`.
-   - Create incoming link - Select this checkbox.
-+
-[NOTE]
-====
-Bitbucket is not going to communicate with {prod-short}. There is no outgoing integration.
-It doesn't really matter what value is set as in `Request Token URL`, `Access token URL`, or `Authorize URL`.
-====
-+
-image::bitbucket/bitbucket_link_applications.png[link="../_images/bitbucket/bitbucket_link_applications.png"]
-.. Select **Continue**.
-..  Complete the form:
-   - Consumer Key -  Specify a consumer key. That is the content of  `bitbucket_server_consumer_key` file.
-   - Consumer name - Enter the same name you used for Application Name.
-   - Public Key  - Provide the public key of your RSA key pair `public.pub`.
+
+. Generate a consumer key and a shared secret.
 +
-[NOTE]
-====
-Value of public key should not include first `----BEGIN PUBLIC KEY-----` or last `-----END PUBLIC KEY-----` lines.
 [subs="+quotes,+attributes"]
 ----
-cat public.pub | sed 's/-----BEGIN PUBLIC KEY-----//g' |  sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n'
+openssl rand -base64 24 > __<bitbucket_server_consumer_key>__
+openssl rand -base64 24 > __<bitbucket_shared_secret>__
 ----
-====
-+
-image::bitbucket/bitbucket_link_applications_step2.png[link="../_images/bitbucket/bitbucket_link_applications_step2.png"]
-. Configure Bitbucket Server integration on {prod-short}
-.. Create a Kubernetes Secret in {prod-short} namespace
+
+. Create a Kubernetes Secret in {prod-short} namespace containing the RSA key pair, the consumer key and the shared secret.
 +
 [subs="+quotes,+attributes"]
 ----
@@ -97,10 +65,11 @@ type: Opaque
 EOF
 ----
 <1> {prod-short} namespace. The default is {prod-namespace}
-<2> base64 encoded content of `privatepkcs8.pem` without first and last lines.
-<3> base64 encoded content of `bitbucket_server_consumer_key` file.
-<4> base64 encoded content of `bitbucket_shared_secret` file.
-.. Configure {prod-short} server environment variables:
+<2> base64 encoded content of the __<privatepkcs8.pem>__ file without first and last lines.
+<3> base64 encoded content of the `__<bitbucket_server_consumer_key>__` file.
+<4> base64 encoded content of the `__<bitbucket_shared_secret>__` file.
+
+. Configure the {prod-short} server environment variables:
 +
 [subs="+quotes,macros"]
 ----
@@ -110,9 +79,62 @@ spec:
      pass:[CHE_OAUTH1_BITBUCKET_CONSUMERKEYPATH]: '/home/user/eclipse-che/conf/oauth1/bitbucket/consumer.key'
      pass:[CHE_OAUTH1_BITBUCKET_SHAREDSECRETPATH]: '/home/user/eclipse-che/conf/oauth1/bitbucket/shared_secret'
      pass:[CHE_OAUTH1_BITBUCKET_PRIVATEKEYPATH]: '/home/user/eclipse-che/conf/oauth1/bitbucket/private.key'
-     pass:[CHE_OAUTH1_BITBUCKET_ENDPOINT]: 'https://{your Bitbucket Server URL}'
-     pass:[CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS]: 'https://{your Bitbucket Server URL}'
+     pass:[CHE_OAUTH1_BITBUCKET_ENDPOINT]: '__<Bitbucket Server URL>__'
+     pass:[CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS]: '__<Bitbucket Server URL>__'
 
 ----
-+
 
+. Configure an link:https://confluence.atlassian.com/adminjiraserver/using-applinks-to-link-to-other-applications-938846918.html[Application Link] in Bitbucket to enable the communication from {prod-short} to Bitbucket Server.
+
+.. In Bitbucket Server, click the cog in the top navigation bar to navigate to *Administration*  > *Application Links*.
+
+pass:[<!-- vale IBM.Usage = NO -->]
+
+.. Enter the application URL: `__<{prod-url-secure}/dashboard/>__` and click the btn:[Create new link] button.
+
+pass:[<!-- vale IBM.Usage = YES -->]
+
+pass:[<!-- vale IBM.PassiveVoice = NO -->]
+
+.. On the warning message stating "No response was received from the URL" click the btn:[Continue] button.
+
+pass:[<!-- vale IBM.PassiveVoice = YES -->]
+
+.. Fill-in the *Link Applications* form and click the btn:[Continue] button.
+
+Application Name::  `__<{prod-short}>__`
+
+Application Type:: Generic Application.
+
+Service Provider Name:: `__<{prod-short}>__`
+
+Consumer Key:: Paste the content of the `__<bitbucket_server_consumer_key>__` file.
+
+Shared secret:: Paste the content of the `__<bitbucket_shared_secret>__` file.
+
+Request Token URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/request-token`
+
+Access token URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/access-token`
+
+Authorize URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/access-token`
+
+Create incoming link:: Enabled.
+
+.. Fill-in the *Link Applications* form and click the btn:[Continue] button.
+
+Consumer Key::  Paste the content of the `__<bitbucket_server_consumer_key>__` file.
+
+Consumer name::  `__<{prod-short}>__`
+
+Public Key:: Paste the content of the `__<public-stripped.pub>__` file.
+
+
+
+.Additional resources
+
+* link:https://bitbucket.org/product/enterprise[Bitbucket Server overview]
+* link:https://bitbucket.org/product/download[Download Bitbucket Server]
+* link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Bitbucket Server Personal access tokens]
+* link:https://confluence.atlassian.com/jirakb/how-to-generate-public-key-to-application-link-3rd-party-applications-913214098.html[How to generate public key to application link 3rd party applications]
+* link:https://confluence.atlassian.com/adminjiraserver/using-applinks-to-link-to-other-applications-938846918.html[Using AppLinks to link to other applications] 
+* xref:end-user-guide:authentication-against-bitbucket-server-with-the-personal-access-token.adoc[].

modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc

@@ -1,10 +1,9 @@
 // configuring-bitbucket-authentication
 
 [id="configuring_bitbucket_authentication_{context}"]
-= Authentication on Bitbucket servers
+= Authenticating on Bitbucket servers
 
-{prod} users may use public or private repositories Bitbucket SCM (Source Code Management) system as a source of their projects. The standard
-factory flow using devfile at the root of the repository is available starting of 7.25 version of {prod}.
+{prod} users may use public or private repositories on Bitbucket SCM (Source Code Management) system as a source of their projects.
 
 The use of private repositories, requires some additional configuration described below.