[docs] Better highlight GitLab and Bitbucket support

Author: jankeromnes

src/docs/context-urls.md

@@ -1,67 +1,89 @@
 # Context URLs
 
- * [GitHub Project Context](#github-project-context)
- * [GitHub File Context](#github-file-context)
- * [GitHub Issue Context](#github-issue-context)
- * [GitHub Pull Request Context](#github-pull-request-context)
+ * [Repository Context](#repository-context)
+ * [Branch Context](#branch-context)
+ * [Pull/Merge Request Context](#pull-merge-request-context)
+ * [Issue Context](#issue-context)
+ * [File Context](#file-context)
 
 Gitpod derives the workspace context from the URL of the repository page from which it was
-started. Different issues, pull requests, or branches will result in different workspaces, allowing
-developers to easily perform individual tasks in their own isolated environments.
+started. Different issues, pull/merge requests, or branches will result in different workspaces, allowing
+developers to easily perform different tasks in different isolated environments.
 
 Each workspace includes a full Linux container. From the IDE's terminal, the user can directly
 access all development tools of the Linux system and even install missing ones.
 
 In the following we describe the supported contexts and what they do:
 
-## GitHub Project Context
+## Repository Context
 
-Creating a Gitpod workspace from the project's base URL does not carry a lot of context.
-Gitpod will check out the `master` branch and open the `Readme.md` if it exists.
+When you create a Gitpod workspace from the project's base URL (i.e. the repository URL),
+Gitpod will clone this repository, check out the default branch, and open the `README.md` if it exists.
 
-An example for this context is:
+An example URL for the repository context is:
 
 ```
-https://github.com/arunoda/learnnextjs-demo
+gitpod.io/#https://gitlab.com/gitpod/spring-petclinic
 ```
 
-## GitHub File Context
+## Branch Context
 
-The file context is an extension to the project context, in that Gitpod will check out the
-corresponding branch and open the respective file in an editor.
+You can also create a Gitpod workspace for a specific branch in a repository. This is similar to the repository context, except that Gitpod will automatically check out the requested branch instead of the repository's default branch.
 
-An example for this context is:
+An example URL for the branch context is:
 
 ```
-https://github.com/arunoda/learnnextjs-demo/blob/getting-started/pages/index.js
+gitpod.io/#https://gitlab.com/gitpod/spring-petclinic/-/tree/my-branch
 ```
 
-When pointing to a directory, e.g.
+Note that this also works with specific commit SHAs:
+
 ```
-https://github.com/arunoda/learnnextjs-demo/tree/create-dynamic-pages/pages
+gitpod.io/#https://gitlab.com/gitpod/spring-petclinic/-/commit/426b99d57ce511022eb71a60bff8e0764806ddf5
 ```
-`Readme.md` will be opened if it exists there.
 
-## GitHub Issue Context
+## Pull/Merge Request Context
 
-When starting a workspace from a GitHub issue, a local branch named `GH-{issue-number}` will be
-created, based on the remote's default branch. In most cases that will be `origin/master`.
+Starting workspaces from a Pull Request or Merge Request will clone the respective branch, and show the file
+changes of the PR/MR in a view on the left. The first change is opened in the diff editor.
+Also the `Pull Request` view on the right is configured to reflect the PR/MR information.
+
+This context is meant for code reviews, or to take action on feedback you got from a reviewer.
+
+## Issue Context
+
+When starting a workspace from an issue, a local branch suffixed with `-{issue-number}` will be
+created, based on the repository's default branch. (In most cases that will be `origin/master`.)
 
 In addition, the commit message is preconfigured with:
 
 ```
 fixes #{organization}/{repo}#{issue-number}
 ```
 
-This will automatically close the GitHub issue once such a commit is merged into the default branch.
+This will automatically close the issue once such a commit is merged into the default branch.
 
 As soon as changes have been committed locally, the `Pull Request` view on the right can be used to
 push changes to a remote repository and create a pull request.
 
-## GitHub Pull Request Context
+## File Context
+
+The file context is an extension to the repository context, in that Gitpod will check out the
+corresponding branch and open the respective file in an editor.
+
+An example for this context is:
+
+```
+gitpod.io/#https://gitlab.com/gitpod/spring-petclinic/-/blob/master/src/main/java/org/springframework/samples/petclinic/owner/Pet.java
+```
+
+When pointing to a directory, e.g.
+```
+gitpod.io/#https://gitlab.com/gitpod/spring-petclinic/-/blob/master/src/main/java/org/springframework/samples/petclinic
+```
+`README.md` will be opened if it exists there.
 
-Starting workspaces from pull requests will clone the respective branch and open the file
-changes of the PR in a view on the left. The first change is opened in the diff editor.
-Also the `Pull Request` view on the right is configured to reflect the PR information.
+## See Also
 
-This context is meant for code reviews or to take action on feedback you got from a reviewer.
+- [Passing environment variables via the context URL](/docs/environment-variables/#passing-in-environment-variables)
+- [Triggering a prebuild using a special context URL](/docs/prebuilds/#manual-execution-of-prebuild)

src/docs/getting-started.md

@@ -1,19 +1,18 @@
 # Getting Started
 
-Gitpod delivers the IDE part for the web-based development flows of common code hosting platforms.
-The following example shows how to use Gitpod with a GitHub repository.
+Gitpod provides continuous dev environments for the development flows of common code hosting platforms.
+The following example shows how to use Gitpod with a source code repository.
 
-1. Point your browser to some GitHub repository, pull request, or issue, e.g.
-    <a href="https://github.com/arunoda/learnnextjs-demo" target="_blank">https://github.com/arunoda/learnnextjs-demo</a>
-2. Either prefix the URL in the address bar of your browser with `https://gitpod.io/#` (e.g.
-   https://gitpod.io/#https://github.com/arunoda/learnnextjs-demo) or push the _Gitpod_ button if you
-   have installed the [Gitpod extension](/docs/browser-extension/).
+1. Point your browser to a GitLab, GitHub or Bitbucket repository, Pull/Merge Request, or issue, e.g.
+    [https://gitlab.com/gitpod/spring-petclinic](https://gitlab.com/gitpod/spring-petclinic)
+2. Either prefix the URL in the address bar of your browser with `gitpod.io/#` (e.g.
+   https://gitpod.io/#https://gitlab.com/gitpod/spring-petclinic) or click the _Gitpod_ button if you've installed the [Gitpod browser extension](/docs/browser-extension/).
 
    ![prefix github URL](./images/prefix-screenshot.png)
 
-3. On first use you will have to authorize access to your GitHub account. This is necessary so you
+3. On first use you will have to authorize access to your GitLab, GitHub or Bitbucket account. This is necessary so you
    can access your data from within Gitpod.
-4. Gitpod will now launch a workspace container for you in the cloud, containing a full Linux system.
-   It will also clone the GitHub repository branch based on the GitHub page you were coming from.
+4. Gitpod will now launch a workspace container for you in the cloud, containing a full Linux environment.
+   It will also clone the repository, branch, or commit based on which code-hosting page you were coming from.
 
 Next up you should learn about [Gitpod's IDE](/docs/ide/).

src/docs/index.md

@@ -3,29 +3,31 @@
 [Gitpod](https://www.gitpod.io) is frictionless coding.
 
 Whether you just want to hack, have code to review or feel like trying something new on
-GitHub, Gitpod launches a ready-to-code dev environment with a single click.
+GitLab, GitHub, or Bitbucket, Gitpod launches a prebuilt dev environment with a single click.
 
-Because Gitpod is based on OSS tech like VS Code, Docker, and Kubernetes, it is familiar,
-comprehensive, extensible, and easy to use. With deep GitHub integration, tools for
-sharing, and a focus on usability, Gitpod contains your entire dev workflow in a
+Because Gitpod is based on open-source tech like VS Code, Docker, and Kubernetes, it is familiar,
+comprehensive, extensible, and easy to use. With deep code-hosting platform integrations, tools for
+sharing and collaborating, and a focus on usability, Gitpod contains your entire dev workflow in a
 browser tab.
 
 ![gitpod-prefix](./images/prefix-lense.png)
 
 Unlike traditional cloud and desktop IDEs, Gitpod understands the context and adjusts the
-IDE automatically. For example, if you create a Gitpod workspace from a Pull Request,
-Gitpod will open in code-review mode.
+IDE automatically. For example, if you create a Gitpod workspace from a Pull or Merge Request,
+Gitpod will open the IDE in code-review mode.
 
-Also, Gitpod workspaces are meant to be disposable. That is, you do not need to maintain anything.
-They are created when you need them, and you can forget about them when you are done. Simply go to
-GitHub and create a fresh workspace whenever you need one.
+Also, Gitpod workspaces are meant to be disposable. That is, you don't need to maintain a single workspace
+to prevent it from becoming outdated.
+Workspaces are created when you need them, and you can forget about them when you are done. Simply go to
+GitLab, GitHub, or Bitbucket and create a fresh workspace whenever you need one.
 
-The IDE is open-source and based on [Eclipse Theia](/docs/ide/). Theia is highly extensible and
+The IDE itself is open-source and based on [Eclipse Theia](/docs/ide/). Theia is highly extensible and
 builds upon mature technologies such as TypeScript, VS Code, Webpack, and Node.js.
 
 This site provides all the details on how to use Gitpod and Theia. If you have questions
 or want discuss something, please join the
 <a href="https://community.gitpod.io/" target="_blank">Gitpod community</a>.
+
 ## Architecture
 
 Gitpod.io runs in multiple Kubernetes clusters hosted on Google Cloud infrastructure in three different regions:
@@ -36,4 +38,4 @@ When starting a workspace, Gitpod will automatically pick the cluster that is cl
 start a Kubernetes pod in it. The requested git repository gets cloned and the branch you need is checked out.
 Furthermore, Gitpod runs any scripts that are configured for that git repository state.
 
-Learn more about how to configure your GitHub repository [here](/docs/configuration/).
+Learn more about how to configure your repository [here](/docs/configuration/).

src/docs/prebuilds.md

@@ -1,33 +1,62 @@
 # Prebuilds
 
-Whenever your code changes (e.g. someone pushes to GitHub), Gitpod can prebuild your workspace, i.e. run the commands in your `.gitpod.yml`.
-When you open a workspace on a branch/pull request for which a prebuild exists, this workspace will have all dependencies downloaded
-and your code will already be built.
+Whenever your code changes (e.g. when new commits are pushed to your repository), Gitpod can prebuild workspaces, i.e. run the init commands in your `.gitpod.yml` before you even start a workspace.
+
+Then, when you do create a new workspace on a branch, or Pull/Merge Request, for which a prebuild exists, this workspace will load much faster, because all dependencies will have been already downloaded ahead of time, and your code will be already compiled.
 
 ## Enable Prebuilt Workspaces
-To enable prebuilt workspaces follow these steps:
 
-1. Go to the <a href="https://github.com/apps/gitpod-io" target="_blank">gitpod-io GitHub app</a> and click "Configure"
-2. Choose the organizations/accounts you want to install the Gitpod integration for, and click _install_
-3. You will be forwarded to Gitpod where you need to confirm the installation
+### On GitHub
+
+To enable prebuilt workspaces for a GitHub repository, follow these steps:
+
+1. Go to the <a href="https://github.com/apps/gitpod-io" target="_blank">Gitpod GitHub app</a> and click `Configure`
+2. Choose the organization or account you wish to install the Gitpod app for, then click `Install`
+3. You will be forwarded to Gitpod where you can confirm the installation
+
+### On GitLab and Bitbucket
+
+To enable prebuilt workspaces for a GitLab or Bitbucket repository, follow these steps:
+
+1. Allow Gitpod to install repository webhooks, by granting `allow api calls` (GitLab) or `install webhooks` (Bitbucket) in [Access Control](https://gitpod.io/access-control/)
+2. Trigger a first prebuild manually, by prefixing the repository URL with `gitpod.io/#prebuild/` e.g. like so:
 
-By default Gitpod prebuilds workspaces for all changes on the default branch (i.e. `master`) and for pull requests coming from the same repository.
+```
+gitpod.io/#prebuild/https://gitlab.com/gitpod/spring-petclinic
+```
+
+This will [trigger a prebuild](#manual-execution-of-prebuild), and also install a webhook that will trigger new Gitpod prebuilds for every new push to your repository. See also [GitLab prebuilds](https://www.gitpod.io/blog/gitlab-support/#prebuilds).
 
-> **Note**: prebuilds are executed as the user who installed the GitHub app. This means that if you want to use
-> prebuilds on a private repository, the user who installed the GitHub app (e.g. you) need to give access to private
-> repositories.
+## Manual execution of prebuild
+
+Alternatively, it is also possible to manually trigger a new prebuild for any repository & commit by using the `gitpod.io/#prebuild/` URL prefix:
+
+```
+https://gitpod.io/#prebuild/https://github.com/ORG/REPO
+```
 
 ## Configure prebuilds
+
+By default Gitpod prebuilds workspaces for all changes on the default branch (e.g. `master`) and for Pull/Merge Requests coming from the same repository.
+
+> **Note**: prebuilds are executed as the user who enabled them. This means that if you want to use
+> prebuilds on a private repository, you must to give Gitpod access to private repositories.
+
 There are three parts to configuring prebuilds:
 1. the tasks that will be run during a prebuild,
-2. when a prebuild will be run, and
-3. how you will be notified by the `gitpod-io` GitHub app.
+2. when a prebuild should be triggered, and
+3. how you will be notified by the Gitpod GitHub app (GitHub only)
+
+All three parts are configured in your repository's [`.gitpod.yml` file](/docs/config-gitpod-file/).
 
-All three parts are configured in the `.gitpod.yml`.
-What tasks to be executed during the prebuilt is configured using [start tasks](/docs/config-start-tasks/).
-It is similar to regular workspace starts with the difference that the `command` phase is not executed and that there is a `prebuild` phase that you can use to execute additional long running tasks, e.g. run unit tests.
+What init tasks should be executed during the prebuild is configured using [start tasks](/docs/config-start-tasks/).
+It is similar to non-prebuilt workspace starts, except that the `command` phase is not executed during the prebuild (because it can potentially run forever, e.g. if you start a server). There is also a `prebuild` phase that you can use to execute additional long-running tasks during prebuilds, e.g. unit tests.
 
-The rest is configured using the `github` section.
+## Configure the GitHub app
+
+Once you have installed the [Gitpod GitHub app](https://github.com/apps/gitpod-io), you can configure its behavior in the `github` section of your repository's `.gitpod.yml`.
+
+> **Note:** The Gitpod GitHub app has no equivalent for GitLab or Bitbucket yet, so this entire section is GitHub-specific for now.
 
 See below for an example:
 ```YAML
@@ -59,12 +88,6 @@ You can enable prebuilds also for all branches and for pull requests from forks.
 ### GitHub integration
 Once the GitHub app is installed Gitpod can add helpful annotations to your pull requests.
 
-### Manual execution of prebuild
-Alternatively and independantly from configuration above it is possible to trigger the prebuild using
-```
-https://gitpod.io/#prebuild/https://github.com/ORG/REPO
-```
-
 #### Checks
 By default Gitpod registers itself as a check to pull requests - much like a continuous integration system would do.
 You can disable this behaviour in the `.gitpod.yml` file in your default/master branch: