From 953a23f1b563147541eec797570b68765f397d41 Mon Sep 17 00:00:00 2001 From: Justin Clareburt <122523970+justo-mend@users.noreply.github.com> Date: Fri, 20 Sep 2024 12:15:30 +0200 Subject: [PATCH] docs: Added documentation about inherited config for the Mend-hosted app (#31479) Co-authored-by: Rhys Arkins <rhys@arkins.net> --- docs/usage/config-overview.md | 54 ++-------------- docs/usage/mend-hosted/.pages | 1 + docs/usage/mend-hosted/hosted-apps-config.md | 68 ++++++++++++++++++++ 3 files changed, 73 insertions(+), 50 deletions(-) create mode 100644 docs/usage/mend-hosted/hosted-apps-config.md diff --git a/docs/usage/config-overview.md b/docs/usage/config-overview.md index 8ed23f918d..5b36075d9a 100644 --- a/docs/usage/config-overview.md +++ b/docs/usage/config-overview.md @@ -8,6 +8,10 @@ When Renovate runs on a repository, the final config used is derived from the: - Repository config - Resolved presets referenced in config +<!-- prettier-ignore --> +!!! note + If you're using a Mend-hosted app, refer to [additional documentation on config specific to the Mend-hosted Apps](mend-hosted/hosted-apps-config.md) section in addition to the below. + ## Types of config ### Default config @@ -247,56 +251,6 @@ By having your centralized preset part of each Repository config `extends`, it h - You still have the ability to change shared settings in a single location - Any user viewing the repo can see the preset being extended and trace it back to understand which config is applied -## Mend Renovate App Config - -The [Mend Renovate App](https://github.com/apps/renovate) is a popular way to use Renovate on GitHub.com so it's important that any of its non-default behavior is documented here. - -Importantly, logs for all Renovate jobs by the Mend Renovate App are available through the [Mend Developer Portal](https://developer.mend.io) so end users can view the logs to see which settings are applied. - -### Onboarding behavior - -#### Installing Renovate into all repositories leads to silent mode - -If an Organization installed Renovate with "All repositories" (instead of "Selected repositories"), then Renovate will default to "Silent" mode (`dryRun=lookup`). -We chose this behavior because: - -- Too often an account or org administrator selects the "All repositories" option and accidentally onboards hundreds of repositories, and -- By offering this option, it means that org administrators _can_ install Renovate into "All repositories" without worrying about the noise, and let individual repository admins decide if/when to start onboarding - -##### Why we call this silent mode - -- It's not just no PRs, it's also no Issues -- It's a common term across other Mend capabilities, such as OSS security and SAST security, where status checks also use silent/non-silent - -#### Get onboarding PRs from Renovate by getting out of silent mode - -If Renovate is installed, _and_ you can see a job log, but Renovate is _not_ onboarding your repository: look for `dryRun` in the logs to confirm you are in Silent mode. -To get a onboarding PR from Renovate, change to Interactive mode either at the Repository level or Organization level. - -#### Installing Renovate into selected repositories always leads to onboarding PRs - -Additionally, if an Organization is installed with "Selected repositories" then the app will change `onboardingNoDeps` to `"enabled"` so that an Onboarding PR is created even if no dependencies are detected. - -### Fork Processing - -If an Organization install Renovate with the "All repositories" option, then `forkProcessing` will remain as the default value `false`. -This means forked repositories are _not_ onboarded, Renovate essentially ignores them. -To change this behavior you need to manually push a `renovate.json` to the repository with `"forkProcessing": true`. - -If an Organization installs Renovate with "Selected repositories" then we assume the organization wants all of the selected repositories onboarded (even forked repositories), so `forkProcessing` is set to `true`. - -### Default presets - -The Mend Renovate app automatically adds the `mergeConfidence:all-badges` preset to the `extends` array. -If you don't want the Merge Confidence badges, then add the `mergeConfidence:all-badges` preset to the `ignorePresets` array. - -Additionally, the preset `config:recommended` is added to `onboardingConfig`. - -### Allowed Post-upgrade commands - -A limited set of approved `postUpgradeTasks` commands are allowed in the app. -They are not documented here as they may change over time - please consult the logs to see them. - ## Other The below contains edge cases which you should avoid if possible, and likely don't need to use. diff --git a/docs/usage/mend-hosted/.pages b/docs/usage/mend-hosted/.pages index 8994a56f0d..90b6607a9f 100644 --- a/docs/usage/mend-hosted/.pages +++ b/docs/usage/mend-hosted/.pages @@ -1,4 +1,5 @@ title: Mend-hosted Apps nav: + - 'Configuration': 'hosted-apps-config.md' - 'App Secrets': 'app-secrets.md' - 'Migrating Secrets': 'migrating-secrets.md' diff --git a/docs/usage/mend-hosted/hosted-apps-config.md b/docs/usage/mend-hosted/hosted-apps-config.md new file mode 100644 index 0000000000..77ba6c4816 --- /dev/null +++ b/docs/usage/mend-hosted/hosted-apps-config.md @@ -0,0 +1,68 @@ +# Mend-hosted Apps Configuration + +The Mend-hosted apps ([Renovate App on GitHub](https://github.com/apps/renovate) and [Mend App on Bitbucket](https://marketplace.atlassian.com/apps/1232072/mend)) are popular ways to use Renovate on the cloud. +This documentation page covers all non-default Renovate behavior of these Mend-hosted apps and is a supplement to the CLI documentation. + +Logs for all Renovate jobs by the Mend-hosted apps are available through the [Mend Developer Portal](https://developer.mend.io). +Accessing such logs can assist users to understand the config that has been applied. + +<!-- prettier-ignore --> +!!! note + For general configuration of the Renovate CLI, refer to the documentation in the main [Configuration/Overview](../config-overview.md) section. + +## Onboarding behavior + +### Installing Renovate into all repositories leads to silent mode + +If an Organization installed Renovate with "All repositories" (instead of "Selected repositories"), then Renovate will default to "Silent" mode (`dryRun=lookup`). +We chose this behavior because: + +- Too often an account or org administrator selects the "All repositories" option and accidentally onboards hundreds of repositories, and +- By offering this option, it means that org administrators _can_ install Renovate into "All repositories" without worrying about the noise, and let individual repository admins decide if/when to start onboarding + +#### Why we call this silent mode + +- It's not just no PRs, it's also no Issues +- It's a common term across other Mend capabilities, such as OSS security and SAST security, where status checks also use silent/non-silent + +### Get onboarding PRs from Renovate by getting out of silent mode + +If Renovate is installed, _and_ you can see a job log, but Renovate is _not_ onboarding your repository: look for `dryRun` in the logs to confirm you are in Silent mode. +To get a onboarding PR from Renovate, change to Interactive mode either at the Repository level or Organization level. + +### Installing Renovate into selected repositories always leads to onboarding PRs + +Additionally, if an Organization is installed with "Selected repositories" then the app will change `onboardingNoDeps` to `"enabled"` so that an Onboarding PR is created even if no dependencies are detected. + +## Fork Processing + +If an Organization install Renovate with the "All repositories" option, then `forkProcessing` will remain as the default value `false`. +This means forked repositories are _not_ onboarded, Renovate essentially ignores them. +To change this behavior you need to manually push a `renovate.json` to the repository with `"forkProcessing": true`. + +If an Organization installs Renovate with "Selected repositories" then we assume the organization wants all of the selected repositories onboarded (even forked repositories), so `forkProcessing` is set to `true`. + +## Inherited config + +The Mend Renovate app will automatically apply inherited config to all installed repositories in an organization when the following conditions are met: + +1. A repository called `renovate-config` exists in the same organization and has the Mend Renovate app installed. It is not necessary for this repository to be onboarded. +2. The file `org-inherited-config.json` is detected in the `renovate-config` repository. + +Unlike with self-hosted Renovate, the values of the `inheritConfigFileName` and the `inheritConfigRepoName` cannot be changed in Mend apps. + +To avoid wasted API calls, Mend apps will enable `inheritConfig` in an org only once a commit has been detected for the `inheritConfig` file. +Therefore, the `inheritConfig` file will not be detected if the Mend Renovate app is not installed on the `renovate-config` repository at the time of adding or changing the file. +If you have such a file but the Mend app has not enabled `inheritConfig` in your org, then try pushing a commit to that file and waiting a minute to see if it gets detected. + +## Default presets + +The Mend Renovate app automatically adds the `mergeConfidence:all-badges` preset to the `extends` array. +If you don't want the Merge Confidence badges, then add the `mergeConfidence:all-badges` preset to the `ignorePresets` array. + +Additionally, the preset `config:recommended` is added to `onboardingConfig`. + +## Allowed Post-upgrade commands + +A limited set of approved `postUpgradeTasks` commands are allowed in the app. +They are not documented here as they may change over time - please consult the logs to see them. -- GitLab