docs: gitlab app

docs/usage/gitlab-bot-security.md

@@ -0,0 +1,82 @@
+# GitLab Bot Security
+
+If running a "bot" service like Renovate on GitLab, it's important to be aware of how GitLab's security model works, particularly in relation to pipeline credentials.
+
+**Important**: If you have any doubts or concerns about this content that could affect other users, please abide by our [Security Policy](https://github.com/renovatebot/renovate/security/policy) and report them confidentially.
+
+## `CI_JOB_TOKEN` permissions
+
+The concept of `CI_JOB_TOKEN` permissions was [overhauled in GitLab release 8.12](https://docs.gitlab.com/ee/user/project/new_ci_build_permissions_model.html), after which jobs are now run with the permissions of the user account which _triggered_ the pipeline.
+For security reasons the token was limited to read-only permissions and a limited set of API endpoints, however it’s since been extended to allow [write access to the GitLab Package Registry](https://docs.gitlab.com/ee/api/README.html#gitlab-ci-job-token). Any pipeline triggered by a user account thus has permissions to read any repository which that account has access to as well as publish packages to them.
+
+With the current GitLab CI permissions model, everyone should avoid committing to any project which they don’t trust completely, because that project could otherwise maliciously steal repository data, publish fake releases, or perhaps spam releases.
+
+## Risks of hosting a Renovate GitLab app/bot/service
+
+The GitLab security model means that the risks of running a _public_ bot service on GitLab are too high, which is why the existing service has been suspended until an alternate security model is ready.
+
+It's also important to remember that when accounts are invited into projects or groups on GitLab, acceptance happens automatically (which was a useful feature to leverage for a shared service).
+
+If you are running your own self-hosted Renovate service, it is advisable to:
+
+- Run a shared service only within projects which have shared visibility/security within the users, or which have a low risk that a user would try to gain access to a private project they don't otherwise have access to
+- If running with `autodiscover`, also configure a value for `autodiscoverFilter` so that the bot can't be invited to projects or groups you don't intend
+
+## Security Solutions and Workarounds
+
+The following research notes may help you when assessing GitLab bot security risk.
+
+### Public Projects Only
+
+If a bot service is run on public projects only, then the risk of private project data being accessed by unauthorized users is zero.
+However, malicious users can still either spoof or spam packages to any other public project they themselves are not a member of, so that rules out this approach for a public hosted service.
+
+A public-visibility-only bot service should be low risk for most self-hosted GitLab instances, but there is still a small problem that you can't _prevent_ users from inviting the bot into private projects if they are not aware of the risks of doing so.
+
+### Project Access Tokens
+
+[Project Access Tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) are a recently added feature for GitLab.
+There are a couple of main downsides to their use for a shared bot service, mainly:
+
+- It is not yet possible to [provision them through the API](https://gitlab.com/gitlab-org/gitlab/-/issues/238991), so project maintainers would need to provision a project bot account and then save it to Renovate manually and per-project
+- Project Access Tokens are a paid-only feature for gitlab.com so would exclude a large percentage of the public service user base
+- At time of writing, there are still some issues with getting Project Access Tokens to trigger and authenticate CI
+- Any service using such tokens would get MRs from a user like `@project_123_bot` which is less intuitive than `@renovate-bot`
+
+However the big advantage of Project Access Tokens would be their limited scope so that users with write access to one project would not be able to read or write to other projects.
+
+### Group Access Tokens
+
+Group Access Tokens are still in planning stage, but may offer a more scalable way to manage a Renovate service.
+Tokens could be provisioned into Renovate per-group and permissions/visibility would need to be kept uniform throughout the group to ensure escalation of privileges is not possible.
+
+It should be noted though that many GitLab users _do not_ have uniform permissions/visibility throughout groups today, so this is a risk of Group Access Tokens in general.
+Even [https://gitlab.com/gitlab-org](https://gitlab.com/gitlab-org) is a good example of how common it is to mix project visibility within a same group.
+
+Similarly with Project Access Tokens, if they are a paid-only feature then it would exclude free users from using such a service.
+
+### Skipping CI
+
+The security problem described above is that if a user triggers a malicious pipeline then they can be exploited, so skipping CI altogether would seem to be a way to avoid that.
+If Renovate can _reliably_ force CI skipping for both (a) branch push, and (b) MR creation/updating then there should be no security exploit risk, but of course then there are no tests run instead.
+A possibility in future could be to combine this with a force push from a user or project token to trigger tests.
+
+The above solution/workaround will be actively researched in collaboration with GitLab.
+
+### OAuth
+
+An alternative to a bot service running with a bot PAT would be to have it run using user OAuth tokens.
+In this scenario, an OAuth app would be needed to allow users to "install" the bot into projects with members they trust not to exploit them, and then commits and Merge Requests would appear to be authored by the _user_, not any bot.
+Bot services are better if they are provisioned with a "bot identity" so that users can quickly distinguish bot activity from real user activity.
+
+## Recommended Migration
+
+Until the hosted app can be reactivated, we recommend users migrate to use self-hosted pipelines to run Renovate.
+Please see the [renovate-bot/renovate-runner README on GitLab](https://gitlab.com/renovate-bot/renovate-runner/-/blob/master/README.md) for instructions on how to set this up as easily as possible.
+
+We will simultaneously be working to find a feasible design for the app so that it can be reactivated securely in future, and welcome any ideas you may have.
+
+## Acknowledgments
+
+Thank you to Nejc Habjan for bringing this security challenge to our attention, and also to his colleagues at Siemens for assistance researching the risks.
+Thanks also to the GitLab security team for being responsive to our questions.

docs/usage/install-gitlab-app.md

@@ -3,124 +3,8 @@ title: GitLab App Installation
 description: How to install the Renovate GitLab App
 ---
 
-# GitLab App Installation
+# Hosted GitLab App
 
-### Overview
+The hosted Renovate App for GitLab is not currently available.
-
+It will be restored either as an OAuth app or once a viable security model for bots on GitLab.com is available.
-WhiteSource Renovate runs as the user [@renovate-bot](https://gitlab.com/renovate-bot) on [gitlab.com](https://gitlab.com).
+For more details on GitLab security for bots, please see the [GitLab Bot Security](./gitlab-bot-security.md) doc.
-To enable the hosted WhiteSource Renovate App on your GitLab.com project, you can do any of the following:
-
-- Add [@renovate-bot](https://gitlab.com/renovate-bot) as a Developer directly to each project, or
-- Add [@renovate-bot](https://gitlab.com/renovate-bot) to a team that has Developer access to the project
-- Install using the WhiteSource Renovate Dashboard's UI
-
-### Dashboard
-
-First, sign into the [Dashboard](https://app.renovatebot.com/dashboard) using GitLab OAuth.
-
-![Renovate Dashboard Sign In Screenshot](assets/images/dashboard-login.png)
-
-If it is your first time signing in, you will be asked to submit WhiteSource's registration form after logging in.
-
-The Dashboard sidebar will load a list of any already-installed repositories that you have access to, if there are any.
-
-Now click the "Settings" icon ![Renovate Dashboard Settings icon](assets/images/dashboard-settings.png) at the top of the side bar and it will soon load a list of all GitLab.com repositories that you have admin rights to.
-
-![Renovate Dashboard Install Screen](assets/images/dashboard-install.png)
-
-On this screen, toggle the switch to install Renovate into a repo. Doing so will:
-
-- Add [@renovate-bot](https://gitlab.com/renovate-bot) as a Developer to the project
-- Add a webhook to the project to send events to the Renovate webhook handler
-
-### Webhooks
-
-One of the best aspects of the hosted Renovate App compared to the CLI version is the responsiveness gained from supporting webhooks, such as:
-
-- Detecting commits to master and checking for any MR conflicts that need to be rebased
-- Allowing manual rebase requests from any MR
-
-If you have added [@renovate-bot](https://gitlab.com/renovate-bot) to a repository or team manually rather than through the Dashboard UI then you _won't_ yet have a webhook.
-To add webhooks for all missing projects, simply log into the Dashboard and load the Install/Uninstall screen using the instructions above.
-Whenever that screen is loaded, the Dashboard client will check every installed project for webhooks and install Renovate's webhook if necessary.
-
-### Pricing
-
-WhiteSource Renovate is free for both public and private repositories, so no payment is necessary.
-
-### Configuring a Token for GitHub.com-hosted Release Notes
-
-Renovate needs a Personal Access Token configured in order to be able to fetch release notes from github.com repositories.
-
-Although open source repositories are public, GitHub's API applies strict rate limiting to unauthenticated requests, so Renovate will not attempt to fetch unless it can detect a token.
-To fetch without a token would risk getting requests denied, which could in turn result in confusing inconsistencies in Pull or Merge Requests, including bodies which flip flop between release notes and none.
-
-#### Generate a Personal Access Token
-
-Any read-only, public-only Personal Access Token for github.com will work.
-
-While logged in, go to [https://github.com/settings/tokens/new](https://github.com/settings/tokens/new).
-Add a note like "renovate release notes" and then generate the token - no further permissions are required.
-
-#### Configuring the Token
-
-Visit [https://renovatebot.com/encrypt](https://renovatebot.com/encrypt), paste your token into "Raw value", and then click "Encrypt".
-Configure the resulting value into your renovate config or preset like this:
-
-```json
-{
-  "hostRules": [
-    {
-      "domainName": "github.com",
-      "encrypted": {
-        "token": "zmWY1ucZFj8wS0ap5ahQluho8aVJBVfyM9LTJ5fCV3Cl6Ys9ml+ZnsQMABKPPGbDoXhhy/REokuho8aVJBVfyM9LTJ5fCV3Cl6Ys9ml+ZnsQMABKPPGbDoXhhy/REokQRS7sFhwTPwpRC9+DyWUgYYO28/kCmw+/8wNupIY1C+rSVSGc4PxV7y2YYd/Ef1jTEVJR+LUrGYuzpJxPuo6ai2wbUCFtx0Z43lH24aDql9btupxYAWNP3RVR6bAp6rA9YGESeD6YTDVvn5czGpvUnIOryxEkigoDcEYmIXFm9Y6F4DLXpLOQ=="
-      }
-    }
-  ]
-}
-```
-
-Alternatively, the `:githubComToken(<token>)` preset achieves the same:
-
-```json
-{
-  "extends": [
-    ":githubComToken(zmWY1ucZFj8wS0ap5ahQluho8aVJBVfyM9LTJ5fCV3Cl6Ys9ml+ZnsQMABKPPGbDoXhhy/REokuho8aVJBVfyM9LTJ5fCV3Cl6Ys9ml+ZnsQMABKPPGbDoXhhy/REokQRS7sFhwTPwpRC9+DyWUgYYO28/kCmw+/8wNupIY1C+rSVSGc4PxV7y2YYd/Ef1jTEVJR+LUrGYuzpJxPuo6ai2wbUCFtx0Z43lH24aDql9btupxYAWNP3RVR6bAp6rA9YGESeD6YTDVvn5czGpvUnIOryxEkigoDcEYmIXFm9Y6F4DLXpLOQ==)"
-  ]
-}
-```
-
-### Details and Known Limitations
-
-##### Credentials storage
-
-The Renovate App does not need to store user OAuth2 tokens - all regular access to gitlab.com is done using the token of [@renovate-bot](https://gitlab.com/renovate-bot).
-User tokens are passed with API calls to Renovate's backend to verify identity but never logged or cached.
-
-##### Installing for all projects
-
-Unlike on GitHub, it is not possible to have the option to install Renovate on "all repositories now and in the future".
-To do this would require Renovate to store the user's token and this is not something we want to do.
-
-##### Detecting new projects
-
-Currently there is no detection mechanism in the backend scheduler to determine when Renovate has been added to a new project, so the onboarding MR won't appear instantly.
-Instead, the new project should be picked up during hourly scheduled runs.
-
-##### Auto merging pull requests
-
-If you have auto merging enabled in your config, Renovate needs permission to merge a branch into master.
-
-There's four ways to make it work:
-
-- Allow all developers to merge into master branch
-  ![Allow renovate-bot merge permission](assets/images/allow-developers-to-merge.png)
-
-- Change renovate-bot member permission from developer to **maintainer**
-  ![Allow renovate-bot merge permission](assets/images/change-renovate-bot-to-maintainer.png)
-
-- Allow **renovate-bot** to merge into master
-  ![Allow renovate-bot merge permission](assets/images/allow-renovate-bot-to-merge.png)
-
-- Change master branch from protected branch to **unprotected** branch
-  ![Allow renovate-bot merge permission](assets/images/unprotect-master-branch.png)

readme.md

@@ -36,17 +36,12 @@ Renovate was released in 2017 and already is widely used in the developer commun
 
 ## Using Renovate
 
-The easiest way to use Renovate if you are hosted on GitHub.com or GitLab.com is to install the hosted Renovate app.
+The easiest way to use Renovate if you are hosted on GitHub.com is to install the hosted Renovate app.
 On Azure DevOps you can install Renovate as an extension from the marketplace.
 
 For GitHub, go to [https://github.com/apps/renovate](https://github.com/apps/renovate) to install it now.
-A GitHub Marketplace plan is required only for private repositories.
 [More details on the GitHub App installation](https://docs.renovatebot.com/install-github-app/).
 
-For GitLab, log into [app.renovatebot.com/dashboard](https://app.renovatebot.com/dashboard) for a convenient way to add Renovate Bot to your project.
-Currently the GitLab app is free for both public and private repositories.
-[More details on the GitLab App installation](https://docs.renovatebot.com/install-gitlab-app/).
-
 For Azure DevOps, visit the Visual Studio Marketplace and install the [Renovate Me](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me) extension in your organisation.
 From there you can create a pipeline with the `RenovateMe` task.
 [More details on how to configure the pipeline](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me).
@@ -54,6 +49,8 @@ Note: This extension is created and maintained personally by a Renovate develope
 Alternatively, you can create custom pipeline with with a `yml` definition that will trigger `npx renovate`.
 [More details on how to configure the pipeline](https://docs.renovatebot.com/setup-azure-devops/).
 
+For Bitbucket Cloud, Bitbucket Server, Gitea and GitLab, use our self-hosting option.
+
 ## Configuration
 
 Visit https://docs.renovatebot.com/ for documentation, and in particular https://docs.renovatebot.com/configuration-options/ for a list of configuration options.