## File: README.md [](https://raw.githubusercontent.com/renovatebot/renovate/main/license) [](https://codecov.io/gh/renovatebot/renovate) [](https://renovatebot.com/) [](https://github.com/renovatebot/renovate/actions/workflows/build.yml) [](https://securityscorecards.dev/viewer/?uri=github.com/renovatebot/renovate) # What is the Mend Renovate CLI? Renovate is an automated dependency update tool. It helps to update dependencies in your code without needing to do it manually. When Renovate runs on your repo, it looks for references to dependencies (both public and private) and, if there are newer versions available, Renovate can create pull requests to update your versions automatically. ## Features - Delivers update PRs directly to your repo - Relevant package files are discovered automatically - Pull Requests automatically generated in your repo - Provides useful information to help you decide which updates to accept (age, adoption, pass rates, merge confidence) - Highly configurable and flexible to fit in with your needs and repository standards - Largest collection of languages and platforms (listed below) - Connects with private repositories and package registries ### Languages Renovate can provide updates for most popular languages, platforms, and registries including: npm, Java, Python, .NET, Scala, Ruby, Go, Docker and more. Supports over [90 different package managers](https://docs.renovatebot.com/modules/manager/). ### Platforms Renovate updates code repositories on the following platforms: GitHub, GitLab, Bitbucket, Azure DevOps, AWS Code Commit (experimental), Gitea, Forgejo, Gerrit (experimental), SCM-Manager (experimental) ## Ways to run Renovate The most effective way to run Renovate is to use an automated job scheduling system that regularly runs Renovate on all enabled repositories and responds with priority to user activity. Mend offers cloud-hosted and self-hosted solutions. See the options below. ### Mend Renovate Community (Cloud-Hosted) **Supports: GitHub.com, Bitbucket Cloud** Hosted by Mend.io. No setup is needed. Community plan available (Free) - GitHub Cloud: Install the [Renovate Cloud-Hosted App](https://github.com/apps/renovate) on your GitHub org, then select the repos to enable - Bitbucket Cloud: Add the [Mend App](https://marketplace.atlassian.com/apps/1232072/mend) to your Workspace, then add the Mend Renovate user to the projects you want to enable ### Mend Renovate Community (Self-hosted) **Supports: GitHub, GitLab, Bitbucket Data Center** Install and run your own Renovate server. Access internal packages. - [Mend Renovate Community Self-Hosted](https://github.com/mend/renovate-ce-ee/tree/main/docs) (Free) - [Mend Renovate Enterprise](https://www.mend.io/mend-renovate/) (Paid plan) ### Other ways to run Renovate If you can’t use a pre-built job scheduling system, or want to build your own, the following options are available: #### Run Renovate on your Pipeline Mend provides a _**GitHub Action**_ or a _**GitLab Runner**_ to help you run Renovate as a CI pipeline job. - GitHub Action: [renovatebot/github-action](https://github.com/renovatebot/github-action). - GitLab Runner: [Renovate Runner project](https://gitlab.com/renovate-bot/renovate-runner/) - AzureDevOps action: [Renovate Me extension](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me) _Note: This extension is created and maintained personally by a Renovate developer/user. Support requests for the extension will not be answered directly in the main Renovate repository._ - Custom pipeline: You can create a custom pipeline with a **yml** definition that triggers **npx renovate**. [More details on how to configure the pipeline](https://docs.renovatebot.com/modules/platform/azure/). #### Run Renovate CLI There are several ways to run the Renovate CLI directly. See docs: [Running Renovate](https://docs.renovatebot.com/getting-started/running/) for all options. **Supports: all platforms** For additional community-maintained options, see the [Community Tools](https://docs.renovatebot.com/community-tools/) page. ## Docs ### More about Renovate - Renovate basics - [Why use Renovate](https://docs.renovatebot.com/#why-use-renovate) - [What does it do? / How does it work?](https://docs.renovatebot.com/key-concepts/how-renovate-works/) - [Who is using it?](https://docs.renovatebot.com/#who-uses-renovate) - Supported platforms and languages - [Supported platforms](https://docs.renovatebot.com/#supported-platforms) - [Supported languages / package managers](https://docs.renovatebot.com/modules/manager/) - Advanced Renovate usage - [Accessing private packages](https://docs.renovatebot.com/getting-started/private-packages/) - [Merge Confidence data](https://docs.renovatebot.com/merge-confidence/) ### Renovate Docs - [Renovate Configuration](https://docs.renovatebot.com/configuration-options/) - [Mend Renovate Self-Hosted Docs](https://github.com/mend/renovate-ce-ee/tree/main/docs) ### Comparisons - [Different ways to run Renovate](https://www.mend.io/renovate/) - [Renovate vs Dependabot](https://docs.renovatebot.com/bot-comparison/) ## Get involved ### Issues and Discussions Please open a Discussion to get help, suggest a new feature, or to report a bug. We only want maintainers to open Issues. - [GitHub Discussions for Renovate](https://github.com/renovatebot/renovate/discussions) ### Contributing To contribute to Renovate, or run a local copy, please read the contributing guidelines. - [Guidelines for Contributing](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) - Items that need contribution: [good first issues](https://github.com/renovatebot/renovate/contribute) ### Contact and Social Media The Renovate project is proudly supported and actively maintained by Mend.io. - Contact [Mend.io](https://www.mend.io/) for commercial support questions. Follow us on: - Twitter: [x.com/mend_io](https://x.com/mend_io) - LinkedIn: [linkedin.com/company/mend-io](https://linkedin.com/company/mend-io) ## Security / Disclosure If you find any bug with Renovate that may be a security problem, please report it through the [GitHub Security Advisories process](https://github.com/renovatebot/renovate/security/advisories). This way we can evaluate the bug and hopefully fix it before it gets abused. Please give us enough time to investigate the bug before you report it anywhere else. If you would like to discuss a potential finding before raising the Advisory, then e-mail us at: [renovate-disclosure@mend.io](mailto:renovate-disclosure@mend.io). --- ## File: Readme.md [](https://raw.githubusercontent.com/renovatebot/renovate/main/license) [](https://codecov.io/gh/renovatebot/renovate) [](https://renovatebot.com/) [](https://github.com/renovatebot/renovate/actions/workflows/build.yml) [](https://securityscorecards.dev/viewer/?uri=github.com/renovatebot/renovate) # What is the Mend Renovate CLI? Renovate is an automated dependency update tool. It helps to update dependencies in your code without needing to do it manually. When Renovate runs on your repo, it looks for references to dependencies (both public and private) and, if there are newer versions available, Renovate can create pull requests to update your versions automatically. ## Features - Delivers update PRs directly to your repo - Relevant package files are discovered automatically - Pull Requests automatically generated in your repo - Provides useful information to help you decide which updates to accept (age, adoption, pass rates, merge confidence) - Highly configurable and flexible to fit in with your needs and repository standards - Largest collection of languages and platforms (listed below) - Connects with private repositories and package registries ### Languages Renovate can provide updates for most popular languages, platforms, and registries including: npm, Java, Python, .NET, Scala, Ruby, Go, Docker and more. Supports over [90 different package managers](https://docs.renovatebot.com/modules/manager/). ### Platforms Renovate updates code repositories on the following platforms: GitHub, GitLab, Bitbucket, Azure DevOps, AWS Code Commit (experimental), Gitea, Forgejo, Gerrit (experimental), SCM-Manager (experimental) ## Ways to run Renovate The most effective way to run Renovate is to use an automated job scheduling system that regularly runs Renovate on all enabled repositories and responds with priority to user activity. Mend offers cloud-hosted and self-hosted solutions. See the options below. ### Mend Renovate Community (Cloud-Hosted) **Supports: GitHub.com, Bitbucket Cloud** Hosted by Mend.io. No setup is needed. Community plan available (Free) - GitHub Cloud: Install the [Renovate Cloud-Hosted App](https://github.com/apps/renovate) on your GitHub org, then select the repos to enable - Bitbucket Cloud: Add the [Mend App](https://marketplace.atlassian.com/apps/1232072/mend) to your Workspace, then add the Mend Renovate user to the projects you want to enable ### Mend Renovate Community (Self-hosted) **Supports: GitHub, GitLab, Bitbucket Data Center** Install and run your own Renovate server. Access internal packages. - [Mend Renovate Community Self-Hosted](https://github.com/mend/renovate-ce-ee/tree/main/docs) (Free) - [Mend Renovate Enterprise](https://www.mend.io/mend-renovate/) (Paid plan) ### Other ways to run Renovate If you can’t use a pre-built job scheduling system, or want to build your own, the following options are available: #### Run Renovate on your Pipeline Mend provides a _**GitHub Action**_ or a _**GitLab Runner**_ to help you run Renovate as a CI pipeline job. - GitHub Action: [renovatebot/github-action](https://github.com/renovatebot/github-action). - GitLab Runner: [Renovate Runner project](https://gitlab.com/renovate-bot/renovate-runner/) - AzureDevOps action: [Renovate Me extension](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me) _Note: This extension is created and maintained personally by a Renovate developer/user. Support requests for the extension will not be answered directly in the main Renovate repository._ - Custom pipeline: You can create a custom pipeline with a **yml** definition that triggers **npx renovate**. [More details on how to configure the pipeline](https://docs.renovatebot.com/modules/platform/azure/). #### Run Renovate CLI There are several ways to run the Renovate CLI directly. See docs: [Running Renovate](https://docs.renovatebot.com/getting-started/running/) for all options. **Supports: all platforms** For additional community-maintained options, see the [Community Tools](https://docs.renovatebot.com/community-tools/) page. ## Docs ### More about Renovate - Renovate basics - [Why use Renovate](https://docs.renovatebot.com/#why-use-renovate) - [What does it do? / How does it work?](https://docs.renovatebot.com/key-concepts/how-renovate-works/) - [Who is using it?](https://docs.renovatebot.com/#who-uses-renovate) - Supported platforms and languages - [Supported platforms](https://docs.renovatebot.com/#supported-platforms) - [Supported languages / package managers](https://docs.renovatebot.com/modules/manager/) - Advanced Renovate usage - [Accessing private packages](https://docs.renovatebot.com/getting-started/private-packages/) - [Merge Confidence data](https://docs.renovatebot.com/merge-confidence/) ### Renovate Docs - [Renovate Configuration](https://docs.renovatebot.com/configuration-options/) - [Mend Renovate Self-Hosted Docs](https://github.com/mend/renovate-ce-ee/tree/main/docs) ### Comparisons - [Different ways to run Renovate](https://www.mend.io/renovate/) - [Renovate vs Dependabot](https://docs.renovatebot.com/bot-comparison/) ## Get involved ### Issues and Discussions Please open a Discussion to get help, suggest a new feature, or to report a bug. We only want maintainers to open Issues. - [GitHub Discussions for Renovate](https://github.com/renovatebot/renovate/discussions) ### Contributing To contribute to Renovate, or run a local copy, please read the contributing guidelines. - [Guidelines for Contributing](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) - Items that need contribution: [good first issues](https://github.com/renovatebot/renovate/contribute) ### Contact and Social Media The Renovate project is proudly supported and actively maintained by Mend.io. - Contact [Mend.io](https://www.mend.io/) for commercial support questions. Follow us on: - Twitter: [x.com/mend_io](https://x.com/mend_io) - LinkedIn: [linkedin.com/company/mend-io](https://linkedin.com/company/mend-io) ## Security / Disclosure If you find any bug with Renovate that may be a security problem, please report it through the [GitHub Security Advisories process](https://github.com/renovatebot/renovate/security/advisories). This way we can evaluate the bug and hopefully fix it before it gets abused. Please give us enough time to investigate the bug before you report it anywhere else. If you would like to discuss a potential finding before raising the Advisory, then e-mail us at: [renovate-disclosure@mend.io](mailto:renovate-disclosure@mend.io). --- ## File: readme.md [](https://raw.githubusercontent.com/renovatebot/renovate/main/license) [](https://codecov.io/gh/renovatebot/renovate) [](https://renovatebot.com/) [](https://github.com/renovatebot/renovate/actions/workflows/build.yml) [](https://securityscorecards.dev/viewer/?uri=github.com/renovatebot/renovate) # What is the Mend Renovate CLI? Renovate is an automated dependency update tool. It helps to update dependencies in your code without needing to do it manually. When Renovate runs on your repo, it looks for references to dependencies (both public and private) and, if there are newer versions available, Renovate can create pull requests to update your versions automatically. ## Features - Delivers update PRs directly to your repo - Relevant package files are discovered automatically - Pull Requests automatically generated in your repo - Provides useful information to help you decide which updates to accept (age, adoption, pass rates, merge confidence) - Highly configurable and flexible to fit in with your needs and repository standards - Largest collection of languages and platforms (listed below) - Connects with private repositories and package registries ### Languages Renovate can provide updates for most popular languages, platforms, and registries including: npm, Java, Python, .NET, Scala, Ruby, Go, Docker and more. Supports over [90 different package managers](https://docs.renovatebot.com/modules/manager/). ### Platforms Renovate updates code repositories on the following platforms: GitHub, GitLab, Bitbucket, Azure DevOps, AWS Code Commit (experimental), Gitea, Forgejo, Gerrit (experimental), SCM-Manager (experimental) ## Ways to run Renovate The most effective way to run Renovate is to use an automated job scheduling system that regularly runs Renovate on all enabled repositories and responds with priority to user activity. Mend offers cloud-hosted and self-hosted solutions. See the options below. ### Mend Renovate Community (Cloud-Hosted) **Supports: GitHub.com, Bitbucket Cloud** Hosted by Mend.io. No setup is needed. Community plan available (Free) - GitHub Cloud: Install the [Renovate Cloud-Hosted App](https://github.com/apps/renovate) on your GitHub org, then select the repos to enable - Bitbucket Cloud: Add the [Mend App](https://marketplace.atlassian.com/apps/1232072/mend) to your Workspace, then add the Mend Renovate user to the projects you want to enable ### Mend Renovate Community (Self-hosted) **Supports: GitHub, GitLab, Bitbucket Data Center** Install and run your own Renovate server. Access internal packages. - [Mend Renovate Community Self-Hosted](https://github.com/mend/renovate-ce-ee/tree/main/docs) (Free) - [Mend Renovate Enterprise](https://www.mend.io/mend-renovate/) (Paid plan) ### Other ways to run Renovate If you can’t use a pre-built job scheduling system, or want to build your own, the following options are available: #### Run Renovate on your Pipeline Mend provides a _**GitHub Action**_ or a _**GitLab Runner**_ to help you run Renovate as a CI pipeline job. - GitHub Action: [renovatebot/github-action](https://github.com/renovatebot/github-action). - GitLab Runner: [Renovate Runner project](https://gitlab.com/renovate-bot/renovate-runner/) - AzureDevOps action: [Renovate Me extension](https://marketplace.visualstudio.com/items?itemName=jyc.vsts-extensions-renovate-me) _Note: This extension is created and maintained personally by a Renovate developer/user. Support requests for the extension will not be answered directly in the main Renovate repository._ - Custom pipeline: You can create a custom pipeline with a **yml** definition that triggers **npx renovate**. [More details on how to configure the pipeline](https://docs.renovatebot.com/modules/platform/azure/). #### Run Renovate CLI There are several ways to run the Renovate CLI directly. See docs: [Running Renovate](https://docs.renovatebot.com/getting-started/running/) for all options. **Supports: all platforms** For additional community-maintained options, see the [Community Tools](https://docs.renovatebot.com/community-tools/) page. ## Docs ### More about Renovate - Renovate basics - [Why use Renovate](https://docs.renovatebot.com/#why-use-renovate) - [What does it do? / How does it work?](https://docs.renovatebot.com/key-concepts/how-renovate-works/) - [Who is using it?](https://docs.renovatebot.com/#who-uses-renovate) - Supported platforms and languages - [Supported platforms](https://docs.renovatebot.com/#supported-platforms) - [Supported languages / package managers](https://docs.renovatebot.com/modules/manager/) - Advanced Renovate usage - [Accessing private packages](https://docs.renovatebot.com/getting-started/private-packages/) - [Merge Confidence data](https://docs.renovatebot.com/merge-confidence/) ### Renovate Docs - [Renovate Configuration](https://docs.renovatebot.com/configuration-options/) - [Mend Renovate Self-Hosted Docs](https://github.com/mend/renovate-ce-ee/tree/main/docs) ### Comparisons - [Different ways to run Renovate](https://www.mend.io/renovate/) - [Renovate vs Dependabot](https://docs.renovatebot.com/bot-comparison/) ## Get involved ### Issues and Discussions Please open a Discussion to get help, suggest a new feature, or to report a bug. We only want maintainers to open Issues. - [GitHub Discussions for Renovate](https://github.com/renovatebot/renovate/discussions) ### Contributing To contribute to Renovate, or run a local copy, please read the contributing guidelines. - [Guidelines for Contributing](https://github.com/renovatebot/renovate/blob/main/.github/contributing.md) - Items that need contribution: [good first issues](https://github.com/renovatebot/renovate/contribute) ### Contact and Social Media The Renovate project is proudly supported and actively maintained by Mend.io. - Contact [Mend.io](https://www.mend.io/) for commercial support questions. Follow us on: - Twitter: [x.com/mend_io](https://x.com/mend_io) - LinkedIn: [linkedin.com/company/mend-io](https://linkedin.com/company/mend-io) ## Security / Disclosure If you find any bug with Renovate that may be a security problem, please report it through the [GitHub Security Advisories process](https://github.com/renovatebot/renovate/security/advisories). This way we can evaluate the bug and hopefully fix it before it gets abused. Please give us enough time to investigate the bug before you report it anywhere else. If you would like to discuss a potential finding before raising the Advisory, then e-mail us at: [renovate-disclosure@mend.io](mailto:renovate-disclosure@mend.io). --- ## File: docs/usage/examples/opentelemetry.md # OpenTelemetry Requirements: - docker-compose ## Prepare setup Create a `docker-compose.yaml` and `otel-collector-config.yml` file as seen below in a folder. ```yaml title="docker-compose.yaml" name: renovate-otel-demo services: # Jaeger for storing traces jaeger: image: jaegertracing/jaeger:2.21.0 ports: - '16686:16686' # Web UI - '4317' # OTLP gRPC - '4318' # OTLP HTTP # Prometheus for storing metrics prometheus: image: prom/prometheus:v3.15.0 ports: - '9090:9090' # Web UI - '4318' # OTLP HTTP command: - --web.enable-otlp-receiver # Mirror these flags from the Dockerfile, because `command` overwrites the default flags. # https://github.com/prometheus/prometheus/blob/5b5fee08af4c73230b2dae35964816f7b3c29351/Dockerfile#L23-L24 - --config.file=/etc/prometheus/prometheus.yml - --storage.tsdb.path=/prometheus otel-collector: # Using the Contrib version to access the spanmetrics connector. # If you don't need the spanmetrics connector, you can use the standard version image: otel/opentelemetry-collector-contrib:0.161.0 volumes: - ./otel-collector-config.yml:/etc/otelcol-contrib/config.yaml ports: - '4318:4318' # OTLP HTTP ( exposed to the host ) - '4317:4317' # OTLP gRPC ( exposed to the host ) depends_on: - jaeger - prometheus ``` ```yaml title="otel-collector-config.yml" receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 exporters: otlp/jaeger: endpoint: jaeger:4317 tls: insecure: true otlphttp/prometheus: endpoint: http://prometheus:9090/api/v1/otlp debug: # verbosity: normal connectors: spanmetrics: histogram: exponential: dimensions: - name: http.method default: GET - name: http.status_code - name: http.host dimensions_cache_size: 1000 aggregation_temporality: 'AGGREGATION_TEMPORALITY_CUMULATIVE' exemplars: enabled: true processors: batch: extensions: health_check: pprof: zpages: service: extensions: [pprof, zpages, health_check] pipelines: traces: receivers: [otlp] exporters: - otlp/jaeger # Send traces to connector for metrics calculation - spanmetrics # Enable debug exporter to see traces in the logs #- debug processors: [batch] metrics: receivers: - otlp # Receive metrics from Renovate. - spanmetrics # Receive metrics calculated by the spanmetrics connector. processors: [batch] exporters: - otlphttp/prometheus # Enable debug exporter to see metrics in the logs # - debug ``` Start setup using this command inside the folder containing the files created in the earlier steps: ``` docker-compose up ``` This command will start: - an [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector-contrib) - an instance of [Jaeger for traces](https://www.jaegertracing.io/) - and [Prometheus](https://prometheus.io/) Jaeger will be now reachable under [http://localhost:16686](http://localhost:16686). ## Run Renovate with OpenTelemetry To start Renovate with OpenTelemetry enabled run following command, after pointing to your `config.js` config file: ``` docker run \ --rm \ --network renovate-otel-demo_default \ -e OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \ -v "/path/to/your/config.js:/usr/src/app/config.js" \ renovate/renovate:latest ``` You should now see `trace_id` and `span_id` fields in the logs. ``` INFO: Repository finished (repository=org/example) "durationMs": 5574, "trace_id": "f9a4c33852333fc2a0fbdc163100c987", "span_id": "4ac1323eeaee ``` ### Traces Open now Jaeger under [http://localhost:16686](http://localhost:16686). You should now be able to pick `renovate` under in the field `service` field. Select `Find Traces` to search for all Renovate traces and then select one of the found traces to open the trace view. You should be able to see now the full trace view which shows more information about what is happening, such as HTTP requests, execution of commands or Git operations, and how long Renovate takes to process a given branch: ### Metrics Additional to the received traces some metrics are calculated. This is achieved using the [spanmetrics connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector). The previously implemented setup will produce following metrics, which pushed to [Prometheus](http://localhost:9090): ``` /* Detailed source-code truncated for AI context efficiency. */ ``` The [spanmetrics connector](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/spanmetricsconnector) creates two sets of metrics. #### Calls metric At first there are the `traces_span_metrics_calls_total` metrics. These metrics show how often _specific_ trace spans have been observed. For example: - `traces_span_metrics_calls_total{http_method="GET", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="repositories", status_code="STATUS_CODE_UNSET"} 2` signals that 2 repositories have been renovated. - `traces_span_metrics_calls_total{http_method="GET", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_INTERNAL", span_name="run", status_code="STATUS_CODE_UNSET"} 1` represents how often Renovate has been run. If we combine this using the PrometheusQueryLanguage ( PromQL ), we can calculate the average count of repositories each Renovate run handles. ``` traces_span_metrics_calls_total{span_name="repository",service_name="renovate"} / traces_span_metrics_calls_total{span_name="run",service_name="renovate"} ``` These metrics are generated for HTTP call spans too: ```yaml traces_span_metrics_calls_total{http_host="prometheus-community.github.io:443", http_method="GET", http_status_code="200", job="renovatebot.com/renovate", service_name="renovate", span_kind="SPAN_KIND_CLIENT", span_name="GET", status_code="STATUS_CODE_UNSET"} 5 ``` #### Latency buckets The second class of metrics exposed are the latency-focused buckets, that allow creating [heatmaps](https://grafana.com/docs/grafana/latest/basics/intro-histograms/#heatmaps). A request is added to a backed if the latency is bigger than the bucket value (`le`). `request_duration => le` As an example if we receive a request which need `1.533s` to complete get following metrics: ``` traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="0.1"} 0 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="1"} 0 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="2"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="6"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="10"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="100"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="250"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="9.223372036854775e+12"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="+Inf"} 1 traces_span_metrics_duration_milliseconds_sum{http_host="api.github.com:443"} 1.533 traces_span_metrics_duration_milliseconds_count{http_host="api.github.com:443"} 1 ``` Now we have another request which this time takes 10s to complete: ``` traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="0.1"} 0 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="1"} 0 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="2"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="6"} 1 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="10"} 2 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="100"} 2 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="250"} 2 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="9.223372036854775e+12"} 2 traces_span_metrics_duration_milliseconds_bucket{http_host="api.github.com:443",le="+Inf"} 2 traces_span_metrics_duration_milliseconds_sum{http_host="api.github.com:443"} 11.533 traces_span_metrics_duration_milliseconds_count{http_host="api.github.com:443"} 2 ``` More about the functionality can be found on the Prometheus page for [metric types](https://prometheus.io/docs/concepts/metric_types/#histogram). --- ## File: docs/usage/examples/self-hosting.md # Self-Hosting Examples !!! warning All self-hosted Renovate instances must operate under a trust relationship with the developers of the monitored repositories. Because of this, there are [security implications](../security-and-permissions.md#security-awareness-for-self-hosted-renovate-instances) when running a self-hosted Renovate instance, which you must consider carefully. !!! warning Most Open Source packages are hosted on github.com, including a number of tools that Renovate may pull at run-time. GitHub greatly rate limits unauthenticated API requests, so you need to configure credentials for `github.com` or your deployment will get rate limited quickly.   Read [Running Renovate, GitHub.com token for changelogs](../getting-started/running.md#githubcom-token-for-changelogs-and-tools) to learn more. ## Installing Renovate OSS CLI ### npmjs ```sh npm install renovate ``` Renovate does not embed `npm`, `pnpm` and `yarn` as its own dependencies. If you want to use these package managers to update your lockfiles, you must ensure that the correct versions are installed globally. ```sh npm install yarn pnpm ``` The same goes for any other third-party binary tool like `gradle` or `poetry` - you need to make sure it is installed and the correct version before running Renovate. ### Docker Renovate is available for Docker via an automated build at [`renovate/renovate` on Docker Hub](https://hub.docker.com/r/renovate/renovate/). It builds `latest` based on the `main` branch and all SemVer tags are published too. ```sh title="Example of valid tags" docker run --rm renovate/renovate docker run --rm renovate/renovate:44 docker run --rm renovate/renovate:44.133 docker run --rm renovate/renovate:44.133.0 ``` !!! warning Do not use the example tags listed above, as they will be out-of-date. Go to [the `renovate/renovate` tags on DockerHub](https://hub.docker.com/r/renovate/renovate/tags) to grab the latest tagged release from Renovate. If you want to configure Renovate using a `config.js` file then map it to `/usr/src/app/config.js` using Docker volumes. For example: ```sh docker run --rm -v "/path/to/your/config.js:/usr/src/app/config.js" renovate/renovate ``` ### Kubernetes Renovate's official Docker image is compatible with Kubernetes. The following is an example manifest of running Renovate against a GitHub Enterprise server. ```yaml title="Kubernetes manifest" apiVersion: batch/v1 kind: CronJob metadata: name: renovate spec: schedule: '@hourly' concurrencyPolicy: Forbid jobTemplate: spec: template: spec: containers: - name: renovate # Update this to the latest available and then enable Renovate on # the manifest image: renovate/renovate:44.133.0 args: - user/repo # Environment Variables env: - name: LOG_LEVEL value: debug envFrom: - secretRef: name: renovate-env restartPolicy: Never ``` And the `secret.yaml` that goes with it: ```yaml title="secret.yaml" apiVersion: v1 kind: Secret metadata: name: renovate-env type: Opaque stringData: RENOVATE_GITHUB_COM_TOKEN: 'any-personal-user-token-for-github-com-for-fetching-changelogs' # You can set RENOVATE_AUTODISCOVER to true to run Renovate on all repos you have push access to RENOVATE_AUTODISCOVER: 'false' RENOVATE_ENDPOINT: 'https://github.company.com/api/v3' RENOVATE_GIT_AUTHOR: 'Renovate ' RENOVATE_PLATFORM: 'github' RENOVATE_TOKEN: 'your-github-enterprise-renovate-user-token' ``` A `config.json` file can be added to the manifest using a `ConfigMap` as shown in the following example (using a "dry run" in github.com): ```yaml title="Adding a config.json file to the manifest with configMap" --- apiVersion: v1 kind: ConfigMap metadata: name: renovate-config data: config.json: |- { "repositories": ["orgname/repo","username/repo"], "dryRun" : "full" } --- apiVersion: batch/v1 kind: CronJob metadata: name: renovate-bot spec: schedule: '@hourly' concurrencyPolicy: Forbid jobTemplate: spec: template: spec: containers: - image: renovate/renovate:44.133.0 name: renovate-bot env: # For illustration purposes, please use secrets. - name: RENOVATE_PLATFORM value: 'github' - name: RENOVATE_TOKEN value: 'some-token' - name: RENOVATE_AUTODISCOVER value: 'false' - name: RENOVATE_BASE_DIR value: '/tmp/renovate/' - name: RENOVATE_CONFIG_FILE value: '/opt/renovate/config.json' - name: LOG_LEVEL value: debug volumeMounts: - name: config-volume mountPath: /opt/renovate/ - name: work-volume mountPath: /tmp/renovate/ restartPolicy: Never volumes: - name: config-volume configMap: name: renovate-config - name: work-volume emptyDir: {} ``` ### CircleCI !!! warning The CircleCI configuration examples are for version `2` of `daniel-shuy/renovate`, which is outdated. Do you know how to get `daniel-shuy/renovate` version `3` working? Then please open a pull request to update the docs and close [Renovate issue #13428](https://github.com/renovatebot/renovate/issues/13428). If you are using CircleCI, you can use the third-party [daniel-shuy/renovate](https://circleci.com/developer/orbs/orb/daniel-shuy/renovate) orb to run a self-hosted instance of Renovate on CircleCI. By default, the orb looks for the self-hosted configuration file in the project root, but you can specify another path to the configuration file with the `config_file_path` parameter. Secrets should be configured using environment variables (e.g. `RENOVATE_TOKEN`, `RENOVATE_GITHUB_COM_TOKEN`). [Configure environment variables in CircleCI Project Settings](https://circleci.com/docs/2.0/env-vars/#setting-an-environment-variable-in-a-project). To share environment variables across projects, use [CircleCI Contexts](https://circleci.com/docs/2.0/contexts/). ```yml title="This runs Renovate hourly, and looks for the self-hosted config file at renovate-config.js" version: '2.1' orbs: renovate: daniel-shuy/renovate@2.2.0 workflows: renovate: jobs: - renovate/self-hosted: config_file_path: renovate-config.js nightly: triggers: - schedule: cron: 0 * * * * filters: branches: only: - main ``` #### Renovate config file validation when using CircleCI ```yml title="Validate your config as part of your workflow" version: '2.1' orbs: renovate: daniel-shuy/renovate@2.2.0 workflows: lint: jobs: - renovate/validate-config ``` ### GitLab CI/CD pipeline For GitLab pipelines we recommend you use the [`renovate-runner` project on GitLab](https://gitlab.com/renovate-bot/renovate-runner). We created some pipeline templates to help you run Renovate on pipeline schedules. You can also find the configuration steps there. For self-hosted GitLab clone/import the [`renovate-runner` project on GitLab](https://gitlab.com/renovate-bot/renovate-runner) project to your instance. ## File/directory usage By default, Renovate stores all files in the `renovate/` subdirectory of the operating system's temporary directory, e.g. `/tmp/renovate/`. Repository data is copied or cloned into unique subdirectories under `repos/`, e.g. `/tmp/renovate/repos/github/owner1/repo-a/`. Renovate's cache, and the caches(s) for npm, Yarn, Composer, and so on, are stored in `/tmp/renovate/cache`. ### Overriding the default directory If you don't want to use the default `tmp/renovate` directory you can: - Set a value for `baseDir` in `config.js` - Use an environment variable `RENOVATE_BASE_DIR` - Use the CLI to pass a base directory: `--base-dir=` ### Overriding the default cache directory If you want to override the cache directory then set your own value for `cacheDir`. ## Usage The following example uses the Renovate CLI tool, which you can install by running `npm i renovate`. If running your own Renovate deployment, then you will need a user account that Renovate will run as. We recommend you create and use a dedicated account for the bot, e.g. name it `renovate-bot` if on your own instance. Create and save a PAT for this account. Create a Renovate config file, for example: ```js module.exports = { endpoint: 'https://self-hosted.gitlab/api/v4/', token: '**gitlab_token**', platform: 'gitlab', onboardingConfig: { extends: ['config:recommended'], }, repositories: ['username/repo', 'orgname/repo'], }; ``` Here change the `repositories` to something appropriate. Also replace `gitlab-token` value with the one created during the previous step. If you're running against GitHub Enterprise Server, then change the `gitlab` values in the example to the equivalent GitHub ones. You can save this file as anything you want and then use the `RENOVATE_CONFIG_FILE` environment variable to tell Renovate where to find it. Most people use `cron` to schedule when Renovate runs, usually on an hourly schedule. ```sh title="Example bash script that you can point cron to" #!/bin/bash export PATH="/home/user/.yarn/bin:/usr/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH" export RENOVATE_CONFIG_FILE="/home/user/renovate-config.js" export RENOVATE_TOKEN="**some-token**" # GitHub, GitLab, Azure DevOps export RENOVATE_GITHUB_COM_TOKEN="**github-token**" # Delete this if using github.com # Renovate renovate ``` Save the script file, and run the script manually. Only add the script to `cron` after you checked it works. !!! note The GitHub.com token as an environment variable is needed to fetch changelogs that are usually hosted on github.com. You don't need to add it if you are already running Renovate against github.com, but you do need to add it if you're using GitHub Enterprise Server, GitLab, Azure DevOps, or Bitbucket. ## Kubernetes for GitLab, using Git over SSH This section describes how to use a Git binary with SSH for GitLab, to avoid API shortcomings. You need to first create a SSH key, then add the public part to GitLab (see this [guide](https://docs.gitlab.com/ee/ssh/)). Then, you need to create the secret to add the SSH key, and the following config to your container: ``` host gitlab.com HostName gitlab.com StrictHostKeyChecking no IdentityFile ~/.ssh/id_rsa User git ``` To easily create the secret, you can do the following (see [docs](https://kubernetes.io/docs/concepts/configuration/secret/#use-case-pod-with-ssh-keys)). ```sh kubectl create secret generic ssh-key-secret --from-file=config=/path/to/config --from-file=id_rsa=/path/to/.ssh/id_rsa --from-file=id_rsa.pub=/path/to/.ssh/id_rsa.pub ``` It creates something like this: ```yml apiVersion: v1 data: config: aG9zdCBnaXRsYWIuY29tCiAgSG9zdE5hbWUgZ2l0bGFiLmNvbQogIFN0cmljdEhvc3RLZXlDaGVja2luZyBubwogIElkZW50aXR5RmlsZSB+Ly5zc2gvaWRfcnNhCiAgVXNlciBnaXQ= id_rsa: id_rsa.pub: kind: Secret metadata: name: ssh-key-secret namespace: ``` Then you need to add a Git author, and configure the mount volumes. The final configuration should look something like this: ```yml --- apiVersion: v1 kind: Namespace metadata: name: --- apiVersion: v1 kind: Secret metadata: name: renovate-env namespace: type: Opaque stringData: RENOVATE_GITHUB_COM_TOKEN: 'any-personal-user-token-for-github-com-for-fetching-changelogs' RENOVATE_AUTODISCOVER: 'false' RENOVATE_ENDPOINT: 'https://github.company.com/api/v3' RENOVATE_GIT_AUTHOR: 'Renovate ' RENOVATE_PLATFORM: 'github' RENOVATE_TOKEN: 'your-github-enterprise-renovate-user-token' --- apiVersion: v1 data: config: aG9zdCBnaXRsYWIuY29tCiAgSG9zdE5hbWUgZ2l0bGFiLmNvbQogIFN0cmljdEhvc3RLZXlDaGVja2luZyBubwogIElkZW50aXR5RmlsZSB+Ly5zc2gvaWRfcnNhCiAgVXNlciBnaXQ= id_rsa: id_rsa.pub: kind: Secret metadata: name: ssh-key-secret namespace: --- apiVersion: batch/v1beta1 kind: CronJob metadata: name: renovate namespace: spec: schedule: '@hourly' concurrencyPolicy: Forbid jobTemplate: spec: template: spec: volumes: - name: ssh-key-volume secret: secretName: ssh-key-secret containers: - name: renovate # Update this to the latest available and then enable Renovate on the manifest image: renovate/renovate:44.133.0 volumeMounts: - name: ssh-key-volume readOnly: true mountPath: '/home/ubuntu/.ssh' args: - # Environment Variables envFrom: - secretRef: name: renovate-env restartPolicy: Never ``` ## Logging If you're ingesting/parsing logs into another system then we recommend you set `LOG_LEVEL=debug` and `LOG_FORMAT=json` in your environment variables. Debug logging is usually needed for any debugging, while JSON format will mean that the output is parsable. ### About the log level numbers When you use `LOG_LEVEL=debug` and `LOG_FORMAT=json`, Renovate uses numbers in the `level` field. The logging level output is controlled by the Bunyan logging library. | Level | Meaning | | ----: | ------- | | 10 | trace | | 20 | debug | | 30 | info | | 40 | warn | | 50 | error | | 60 | fatal | ## Self-signed TLS/SSL certificates Renovate and invoked helper programs (like Git, or npm) use a secure TLS connection (e.g. HTTPS) to connect to remote source code and dependency hosts. If the remote hosts uses self-signed certificates or certificate authorities then Renovate must be told to trust them. ### Renovate Node.js app For the main Renovate Node.js application set the environment variable [`NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/self-signed-certificate.crt`](https://nodejs.org/api/cli.html#node_extra_ca_certsfile). The Renovate application now trusts the `self-signed-certificate.crt` file. This means Renovate can safely connect to systems using that certificate or certificates signed by this certificate authority. ### Helper programs like Git or npm Helper programs like Git and npm use the system trust store. For those programs to trust a self-signed certificate you must add it to the systems trust store. On Ubuntu/Debian and many Linux-based systems, this can be done by: 1. copying the self-signed certificate (e.g. `self-signed-certificate.crt`) to `/usr/local/share/ca-certificates/` 1. and running [`update-ca-certificates`](https://manpages.ubuntu.com/manpages/noble/man8/update-ca-certificates.8.html) to update the system trust store afterwards ### Renovate Docker image If you're using the official [Renovate Docker image](#docker) then we recommend you add the self-signed certificate and build your own modified Docker image. ```dockerfile title="Example of a Dockerfile that uses a self-signed certificate" FROM renovate/renovate # Changes to the certificate authority require root permissions USER root # Copy and install the self signed certificate COPY self-signed-certificate.crt /usr/local/share/ca-certificates/ RUN update-ca-certificates # Change back to the Ubuntu user USER 12021 # OpenSSL ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt ``` ## Proxy Environment Variable Configuration If your environment uses an HTTP proxy configured via environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`, and their lowercase variants), Renovate inherits these settings and prefers the lowercase variant. In some cases, you may need to adjust the `NO_PROXY` variable if Renovate encounters network or TLS errors when accessing internal or excluded domains. Renovate uses the [global-agent](https://github.com/gajus/global-agent) library to manage proxy connections. To exclude a domain and all its subdomains, you must use a wildcard — for example: ``` NO_PROXY=*.example.org ``` This configuration ensures that both `example.org` and `www.example.org` are accessed directly, bypassing the proxy for Renovate. If a tool that Renovate runs (such as git) still has proxy-related issues, note that different tools interpret NO_PROXY formats differently. See [GitLab’s detailed explanation](https://about.gitlab.com/blog/we-need-to-talk-no-proxy/#no_proxy-format) for guidance on tool-specific behavior. To debug the proxy configuration behavior you can set the environment variable `ROARR_LOG=true` to enable log printing to stdout. --- ## File: docs/usage/getting-started/installing-onboarding.md # Installing and onboarding Renovate into repositories ## About the security and privacy of installing Renovate Read the [Security and Permissions](../security-and-permissions.md) page to learn more about: - Renovate's security stance - What to do if you need to use certified software - The security/disclosure process - Permissions - Privacy ## Repository installation Renovate administrators can configure Renovate to either "autodiscover" installed repositories, or configure a fixed list of repository names to operate on. If the administrator has configured a fixed list of repositories then the only way to "install" Renovate on a extra repository is for it to be manually added for the next run or restart. Otherwise, the process for adding new repositories to a Renovate installation can vary: - Most commonly, you run Renovate as a dedicated account with global config option `autodiscover` set to `true`, meaning that it will run on every repository which it's been granted access to - If using a GitHub App (including the Mend Renovate App) then you can install the app into a user or organization account and select either "All repositories", or "Select repositories" and pick them manually ### Hosted GitHub.com App Follow these steps to install and enable the Mend Renovate App: First, navigate to [https://github.com/apps/renovate](https://github.com/apps/renovate) and select the Install button: { loading=lazy } The only choice you need to make is whether to run Renovate on all repositories or on selected repositories: { loading=lazy } Renovate will ignore any repositories that don't have known package files, as well as any forks, so you can enable Renovate for all your repositories with no problems. That said, most people run Renovate on selected repositories. Unfortunately GitHub doesn't offer a "select all except X, Y, Z" option, so you must select each repository where you want Renovate to run. Once you're done selecting repositories for Renovate to run on, select the green Install button at the bottom of the page and Renovate will be enabled for those repositories and start the onboarding process. !!! note If you are using the Mend Renovate App then it has a custom behavior for forked repositories. If you choose "All repositories" when installing then forked repositories will be skipped by default, while if you choose "Select repositories" then they will be processed by Renovate even if they're a fork. ### Hosted GitLab.com App Mend relaunched its hosted Renovate app for GitLab.com in July 2026, using a more secure architecture than the original version. You can set it up [by following these instructions](https://docs.mend.io/integrations/latest/install-mend-developer-platform-for-gitlab-com) when logging into [the Mend Developer Platform](https://developer.mend.io). We currently only support installing the app on a Group on GitLab.com. We do have plans to support User installations, but we do not have any planned timelines. ### Self-hosting on Windows We recommend you set [`core.autocrlf = input`](https://git-scm.com/docs/gitattributes#_text) in your Git config. You can do this by running this Git command: ```bash git config --global core.autocrlf input ``` This prevents the carriage return `\r\n` which may confuse Renovate. You can also set the line endings in your repository by adding `* text=auto eol=lf` to your `.gitattributes` file. ## Repository onboarding Once you have enabled Renovate on a repository, you will get a "Configure Renovate" Pull Request looking something like this: { loading=lazy } !!! note If you self-host Renovate, and want to add the rebase/retry checkbox to Renovate's onboarding PRs: enable the [`onboardingRebaseCheckbox` config option](../self-hosted-configuration.md#onboardingrebasecheckbox) first. ### No risk onboarding Conveniently, Renovate will not make any changes to your repository or raise any further Pull Requests until after you _merge_ the onboarding Pull Request. If there is anything about the Pull Request that you don't like or understand, take your time to read the [documentation](../index.md) or ask questions on the [discussions forum on GitHub](https://github.com/renovatebot/renovate/discussions) and merge the PR only once you're satisfied with the result. You can edit your Renovate configuration **within the `renovate/configure` branch** and Renovate will keep updating the description in the PR to match, so you can work on the config until you're satisfied with the results. If you wish to opt-out of having Renovate run for your repo, simply close the onboarding Pull Request without merging it. This action is reversible - you can re-request an onboarding PR by renaming the (closed) onboarding PR, or you can commit a Renovate configuration file to your default branch to manually onboard. ### Check for warnings If you have any Warnings or Errors listed, see if you need or want to make any changes to fix them. Warnings and errors should be fixed on the base branch (e.g. `main`) so that Renovate can recreate its Configure Renovate PR on its next cycle. ### Configuration location The "Configure Renovate" PR will include a `renovate.json` file in the root directory, with suggested default settings. If you don't want a `renovate.json` file in your repository you can use one of the following files instead: - `renovate.json5` - `.github/renovate.json` - `.github/renovate.json5` - `.gitlab/renovate.json` - `.gitlab/renovate.json5` - `.renovaterc` - `.renovaterc.json` - `.renovaterc.json5` - `package.json` (deprecated) Or in a custom file present within the [`configFileNames`](../self-hosted-configuration.md#configfilenames). Renovate first checks all the files in the `configFileNames` array before checking from the above file list. #### package.json !!! warning This approach has been deprecated and will be removed in a future release. You can add the same settings to a `"renovate"` section in your `package.json` file instead. The `package.json` file must be located at the root of your repository. This is handy if you are already using a `package.json` file anyway, e.g. when you're working on a JavaScript project. The configuration in your `package.json` will apply to the whole project (this includes other, nested `package.json` files). ### Customized defaults Renovate provides a `renovate.json` file, with default settings that will work for most cases. Sometimes Renovate detects that an override to these defaults is needed, and will add this override automatically, such as: - Automatically enabling Angular-style semantic commits if your repository uses them - Determining whether to use dependency range pinning depending on the detected project type (app vs library) ### Common overrides Please check the docs on this website for an exhaustive Configuration Reference. To help you get started, here are some of the most commonly changed (overridden) configuration settings: - **rangeStrategy**: By default (with zero config) it's `"replace"` but the `"config:recommended"` preset overrides it to `"auto"`. Some prefer `"bump"`. - **labels**: Labels to assign to Pull Requests - **assignees**: GitHub user(s) to assign the Pull Requests to Renovate will update your PR description each time it finds changes. ### Merge Once you're done checking and configuring in your Configure Renovate PR, it's time to merge it to enable the real Pull Requests to begin. ## Repository re-configuration There will be times when you need to change your Renovate config. There are two recommended approaches: - Reconfigure via PR - Nuke the config and re-onboard ### Reconfigure via PR If you want to make config edits directly, follow these steps: 1. Create a new branch named `renovate/reconfigure` 1. Edit your Renovate configuration file 1. Create a pull request from the `renovate/reconfigure` branch 1. Run renovate on your repository(if self-hosted), or wait for the hosted app to process the changes 1. Renovate will comment on your PR, outlining the expected changes from your modified configuration 1. You can continue to edit the configuration file in the same PR, and Renovate will update its comment accordingly 1. If you only want to validate your configuration changes, check out: [Validate your config](../config-validation.md) ### Nuke config and re-onboard Perhaps you really liked the interactive onboarding PR and want to use it again. You can follow the steps below to nuke the config and get a new PR. Any existing Renovate PRs will be closed after you've completed these steps. 1. Find your original `Configure Renovate` PR 1. Rename the original PR to something else, e.g. `Configure Renovate - old` 1. Remove the current Renovate configuration file (e.g. `renovate.json`) from your mainline branch Following these steps will trick Renovate into thinking that your repository was _never_ onboarded, and will trigger a new "Configure Renovate" PR. If you're using the Mend Renovate App and you don't get a new onboarding PR within a few hours, then please create a Discussions post to request staff trigger it manually. --- ## File: docs/usage/getting-started/private-packages.md # Private package support It's a very common requirement to be able to support private module/dependency lookups. This page describes Renovate's approach to authentication. First, a quick note on terminology: - The terms `module`, `package` and `dependency` can mostly be used interchangeably below - The terms `credentials`, `secrets` and `authentication` are also used interchangeably ## When does Renovate need credentials? By default, the only credentials Renovate has are those for the "platform", i.e. GitHub, GitLab, etc. If the token used has sufficient permissions, this will enable Renovate to lookup dependencies located in alternative repositories on the same host or any hosted on any embedded package registry on the same host. It's also quite common to need to look up packages on other protected hosts, including npmjs, Docker Hub, or private registries like Nexus or Artifactory. Any time you need Renovate to access such registries with credentials then you will need to provision them as part of your config. There are four times in Renovate's behavior when it may need credentials: - Resolving private config presets - Looking up dependency versions - Looking up changelogs - Passing to package managers when updating lock files or checksums !!! note If you self-host Renovate, and have a self-hosted registry which _doesn't_ require authentication to access, then such modules/packages are not considered "private" to Renovate. ## Private Config Presets Renovate supports config presets, including those which are private. Although npm presets were the first type supported, they are now deprecated and it is recommend that all users migrate to git-hosted "local" presets instead. However if you do still use them, private modules should work if you configure `hostRules` (recommended) or `npmrc` including token credentials in your global self-hosted config. It is strongly recommended not to use private modules on a private registry and a warning will be logged if that is found. Credentials stored on disk (e.g. in `~/.npmrc`) are no longer supported. The recommended way of using local presets is to configure them using "local" presets, e.g. `"extends": ["local>myorg/renovate-config"]`, and ensure that the platform token has access to that repo. It's not recommended that you use a private repository to host your config while then extending it from a public repository. If your preset doesn't have secrets then you should make it public, while if it does have secrets then it's better to split your preset between a public one which all repos extend, and a private one with secrets which only other private repos extend. In summary, the recommended approach to private presets is: - Host the presets on the same server/platform as other repositories - Make sure you install Renovate into the preset repository so that it has credentials to access it from other private repos - Use `local>....` syntax to refer to private presets ## Dependency Version Lookups Whenever Renovate detects that a project uses a particular dependency, it tries to look up that dependency to see if any new versions exist. If such a package is private, then Renovate must be configured with the relevant credentials. Renovate does not use any package managers for this step and performs all HTTP(S) lookups itself, including insertion of authentication headers. Configuring Renovate with credentials requires `hostRules`. Each host rule consists of a `hostType` value and/or a way to match against hosts using `matchHost`. `hostType` is not particularly important at this step unless you have different credentials for the same host, but it is sometimes useful in later steps so is good to include if you can. It can be either a "platform" name (e.g. `github`, `azure`, etc) or a "datasource" name (e.g. `npm`, `maven`, `github-tags`, etc). If you want to apply credentials only for a nested path within a host then write `matchHost` as a base URL like `https://registry.company.com/nested/path/`. If the same credentials apply to all paths on a host and not on any subdomains of it then configure `matchHost` with a protocol like `https://registry.company.com`. Finally, to apply credentials to all hosts within the domain, use a `matchHost` value with no `https://` prefix, e.g. `company.com` or `registry.company.com`, both of which would apply to a host like `beta.registry.company.com`. In addition to the above options to match against a host, you need to add the credentials. Typically they are either `token`, or `username` + `password`. Other credential terms are not supported yet. ```json title="Example host rules" { "hostRules": [ { "matchHost": "registry.npmjs.org", "token": "abc123" }, { "matchHost": "https://registry.company.com/pypi-simple/", "username": "engineering", "password": "abc123" } ] } ``` Renovate applies these `hostRules` to every HTTP(s) request which is sent, so they are largely independent of any platform or datasource logic. With `hostRules` in place, private package lookups should all work. ### GitHub (and Enterprise) repo scoped credentials If you need to use different credentials for a specific GitHub repo, then you can configure `hostRules` like one of the following: ```json { "hostRules": [ { "matchHost": "https://api.github.com/repos/org/repo", "token": "abc123" }, { "matchHost": "https://github.domain.com/api/v3/repos/org/repo", "token": "abc123" } ] } ``` Renovate will use those credentials for all requests to `org/repo`. #### Example for gomod Here's an example for `gomod` with private `github.com` repos. Assume this config is used on the `github.com/some-other-org` repo: ```json {configType=global} { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "dependencyDashboard": true, "hostRules": [ { "matchHost": "https://gitlab.com", "token": "glpat-token_for_different_git_platform", "hostType": "gitlab" }, { "matchHost": "https://github.com/some-org", "token": "ghp_token_for_different_org", "hostType": "go" }, { "matchHost": "https://api.github.com/repos/some-org", "token": "ghp_token_for_different_org", "hostType": "github" } ], "customEnvVariables": { "GOPRIVATE": "github.com/some-org,github.com/some-other-org,gitlab.com/some-org", "GONOSUMDB": "github.com/some-org,github.com/some-other-org,gitlab.com/some-org", "GONOPROXY": "github.com/some-org,github.com/some-other-org,gitlab.com/some-org" }, "postUpdateOptions": ["gomodTidy"] } ``` If you use private Go modules hosted on GitLab, read [private Go modules hosted on GitLab](../golang.md#private-go-modules-hosted-on-gitlab) to learn how to authenticate the module resolution requests. ## Looking up changelogs When Renovate creates Pull Requests, its default behavior is to locate and embed release notes/changelogs of packages. These release notes are fetched from the source repository of packages and not from the registries themselves, so if they are private then they will require different credentials. When it comes to open source, most packages host their source on `github.com` in public repositories. GitHub greatly rate limits unauthenticated API requests, so you need to configure credentials for `github.com` or your deployment will get rate limited quickly. It can be confusing for people who host their own source code privately to be asked to configure a `github.com` token but without it changelogs for most open source packages will be blocked. Currently the preferred way to configure `github.com` credentials for self-hosted Renovate is: - Create a read-only Personal Access Token (PAT) for a `github.com` account. This can be any GitHub account, but we recommend you create an "empty" account for this purpose. - Add the PAT to Renovate using the environment variable `RENOVATE_GITHUB_COM_TOKEN` !!! note `GITHUB_COM_TOKEN` is still parsed and takes precedence over `RENOVATE_GITHUB_COM_TOKEN`, but is considered deprecated and will be removed in a future major update. ## Package Manager Credentials for Artifact Updating In Renovate terminology, "artifacts" includes lock files, checksum files, and vendored dependencies. One way of understanding artifacts is: "everything else that needs to be updated when the dependency version changes". Not all package managers supported by Renovate require artifact updating, because not all use lock or checksum files. But when such files need updating, Renovate does so by using the package managers themselves instead of trying to "reverse engineer" each package manager's file formats and behavior. Importantly, such package managers are run via shell commands and do not understand Renovate's `hostRules` objects, so Renovate needs to reformat the credentials into formats (such as environment variables or configuration files) which the package manager understands. Because of this need to convert `hostRules` credentials into a format which package managers understand, sometimes artifact updating can fail due to missing credentials. Sometimes this can be resolved by changing Renovate configuration, but other times it may be due to a feature gap. The following details the most common/popular manager artifacts updating and how credentials are passed: ### bundler `hostRules` with `hostType=rubygems` are converted into environment variables which Bundler supports. ### composer Any `hostRules` token for `github.com` or `gitlab.com` are found and written out to `COMPOSER_AUTH` in env for Composer to parse. Any `hostRules` with `hostType=packagist` are also included. For dependencies on `github.com` without a Packagist server: use a Personal Access Token for `hostRule` with `hostType=git-tags`, do not use an application token. Avoid adding a `hostRule` with `hostType=github` because: - it overrides the default Renovate application token for everything else - it causes unwanted side effects The repository in `composer.json` should have the `vcs` type with a `https` URL. For example: ```json { "repositories": [ { "type": "vcs", "url": "https://github.com/organization/private-repository" } ] } ``` ### gomod If a `github.com` token is found in `hostRules`, then it is written out to local [GIT_CONFIG_](https://git-scm.com/docs/git-config#Documentation/git-config.txt-GITCONFIGCOUNT) variables prior to running `go` commands. The environment variables used are: `GIT_CONFIG_KEY_0=url.https://${token}@github.com/.insteadOf GIT_CONFIG_VALUE_0=https://github.com/ GIT_CONFIG_COUNT=1`. ### helm Maybe you're running your own ChartMuseum server to host your private Helm Charts. This is how you connect to a private Helm repository: ```js title="Connecting to a private Helm repository" module.exports = { hostRules: [ { matchHost: 'your.host.io', hostType: 'helm', username: '', password: process.env.SELF_HOSTED_HELM_CHARTS_PASSWORD, }, ], }; ``` If you need to configure per-repository credentials then you can also configure the above within a repository's Renovate config (e.g. `renovate.json`). ### npm The recommended approaches in order of preference are: 1. **Self-hosted hostRules**: Configure a hostRules entry in your self-hosted `config.js` with the `hostType`, `matchHost` and `token` specified 1. **The Mend Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config 1. **The Mend Renovate App with a private registry**: Add an plaintext `npmrc` plus an encrypted `npmToken` in config These approaches are described in full below. #### Add hostRule to self-hosted config Define `hostRules` like this: ```js module.exports = { hostRules: [ { hostType: 'npm', matchHost: 'registry.npmjs.org', token: process.env.NPMJS_TOKEN, }, { hostType: 'npm', matchHost: 'https://pkgs.dev.azure.com/{organization}/{project}/_packaging/{feed}/npm/registry/', username: 'VssSessionToken', password: process.env.AZURE_NPM_TOKEN, }, { // https://www.jfrog.com/confluence/display/JFROG/npm+Registry // Will be passed as `//artifactory.my-company.com/artifactory/api/npm/npm:_auth=` to `.npmrc` hostType: 'npm', matchHost: 'https://artifactory.my-company.com/artifactory/api/npm/npm/', token: process.env.ARTIFACTORY_NPM_TOKEN, authType: 'Basic', }, ], }; ``` !!! tip Remember to put a trailing slash at the end of your `matchHost` URL. #### Add npmrc string to Renovate config You can add an `.npmrc` authentication line to your Renovate config under the field `npmrc`. e.g. a `renovate.json` might look like this: ```json { "npmrc": "//some.registry.com/:_authToken=abcdefghi-1234-jklmno-aac6-12345567889" } ``` If configured like this, Renovate will use this to authenticate with npm and will ignore any `.npmrc` files(s) it finds checked into the repository. If you wish for the values in your `config.npmrc` to be _merged_ (prepended) with any values found in repos then also set `config.npmrcMerge=true`. This merge approach is similar to how `npm` itself behaves if `.npmrc` is found in both the user home directory as well as a project. #### Add npmToken to Renovate config If you are using the main npmjs registry then you can configure only the `npmToken` instead: ```json { "npmToken": "abcdefghi-1234-jklmno-aac6-12345567889" } ``` #### Add an encrypted npm token to Renovate config If you don't want all users of the repository to see the plaintext token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. Go to , paste in your npm token, select "Encrypt", then copy the encrypted result. Paste the encrypted result inside an `encrypted` object like this: ```json { "encrypted": { "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" } } ``` If you have no `.npmrc` file then Renovate creates one for you, pointing to the default npmjs registry. If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. ```json { "encrypted": { "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" }, "npmrc": "registry=https://my.custom.registry/npm\n//my.custom.registry/npm:_authToken=${NPM_TOKEN}" } ``` Renovate will then use the following logic: 1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry 1. If an `npmrc` string is present and has a `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token 1. If an `npmrc` string is present but doesn't have a `${NPM_TOKEN}` then the file will have `_authToken=` appended to it #### Encrypted entire .npmrc file into config Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at . You will then get an encrypted string that you can substitute into your `renovate.json` instead. The end-result looks like this: ```json { "encrypted": { "npmrc": "WOTWu+jliBtXYz3CU2eI7dDyMIvSJKS2N5PEHZmLB3XKT3vLaaYTGCU6m92Q9FgdaM/q2wLYun2JrTP4GPaW8eGZ3iiG1cm7lgOR5xPnkCzz0DUmSf6Cc/6geeVeSFdJ0zqlEAhdNMyJ4pUW6iQxC3WJKgM/ADvFtme077Acvc0fhCXv0XvbNSbtUwHF/gD6OJ0r2qlIzUMGJk/eI254xo5SwWVctc1iZS9LW+L0/CKjqhWh4SbyglP3lKE5shg3q7mzWDZepa/nJmAnNmXdoVO2aPPeQCG3BKqCtCfvLUUU/0LvnJ2SbQ1obyzL7vhh2OF/VsATS5cxbHvoX/hxWQ==" } } ``` #### Automatically authenticate for npm package stored in private GitHub npm repository ```json { "hostRules": [ { "matchHost": "https://npm.pkg.github.com/", "hostType": "npm", "encrypted": { "token": "" } } ], "npmrc": "@organizationName:registry=https://npm.pkg.github.com/" } ``` #### Yarn 2+ Renovate doesn't support reading `npmRegistries` and `npmScopes` from `.yarnrc.yml`, so `hostRules` (or `npmToken`) and `npmrc` should be configured like above. Renovate updates `npmRegistries` in `.yarnrc.yml` with resolved `hostRules` before running Yarn. For Renovate to overwrite existing `npmRegistries` entry, the key should match the `matchHost` minus the protocol (`http:` or `https:`) plus the trailing slash. For example, the Renovate configuration: ```json { "hostRules": [ { "matchHost": "https://npm.pkg.github.com/", "hostType": "npm", "encrypted": { "token": "" } } ] } ``` will update `.yarnrc.yml` as following: If no registry currently set ```yaml npmRegistries: //npm.pkg.github.com/: npmAuthToken: ``` If current registry key has protocol set: ```yaml npmRegistries: https://npm.pkg.github.com: npmAuthToken: ``` #### pnpm Renovate reads private registries declared in `pnpm-workspace.yaml` (supported by pnpm v11+): the top-level `registry` key and the `registries` map, including its `default` key and scoped keys like `@my-org`. ```yaml registry: https://registry.npmjs.org/ registries: default: https://registry.npmjs.org/ '@my-org': https://private.example.com/ ``` These registries are applied to dependencies in member `package.json` files as well as to `catalog`/`catalogs` and `overrides` entries in the workspace file itself. Registries set this way take precedence over `registry=`/`@scope:registry=` lines in `.npmrc`. Renovate does not read `namedRegistries`. Authentication is still read from `.npmrc`/`hostRules` (pnpm does not store auth in `pnpm-workspace.yaml`), so configure tokens as described above. Registry values that contain a `${...}` placeholder are ignored, matching pnpm's own behavior since v11.5.3. ### maven GitLab package registry can be authorized using `Authorization: Bearer `. In GitLab Pipelines authorization can be achieved using following config: ```js hostRules: [ { hostType: 'maven', matchHost: 'https://gitlab.host.com/api/v4', token: process.env.CI_JOB_TOKEN, }, ]; ``` ### nuget For each known NuGet registry, Renovate searches for `hostRules` with `hostType=nuget` and matching host. For those found, a command like the following is run: `dotnet nuget add source ${registryInfo.feedUrl} --configfile ${nugetConfigFile} --username ${username} --password ${password} --store-password-in-clear-text`. ```js hostRules: [ { matchHost: 'https://pkgs.dev.azure.com//', hostType: 'nuget', username: 'user', // doesn't matter for azure password: '', }, ]; ``` ### pip If a `requirements.txt` file has an index-url then Renovate follows that link, instead of following any link set in the `registryUrls` array. To override the URL found in `requirements.txt`, you must create a custom `packageRules` setting. This is because `packageRules` are applied _after_ package file extraction. For example: ```json { "packageRules": [ { "matchManagers": ["pip_requirements"], "registryUrls": ["https://docker.mycompany.domain"] } ] } ``` ### pipenv If a `Pipfile` contains a `source` with `USERNAME` or `PASSWORD` environment variables and there is a `hostRules` entry with a matching host plus `username` and `password` fields, then these variables would be passed to `pipenv lock`. For example: ```ini [[source]] url = "https://$USERNAME:${PASSWORD}@mypypi.example.com/simple" verify_ssl = true name = "pypi" ``` ### pip-compile The pip-compile manager can extract these directives from the input file given to Renovate: - `--index-url` - `--extra-index-url` Renovate matches those URLs with credentials from matching `hostRules` blocks in the Renovate configuration. Then Renovate passes the information to `pip-compile` via environment variables. !!! warning "Put directives in the .in file, avoid the lockfile" You must put the `--[extra-]index-url` directive(s) in the `.in` file, for `pip-compile` to use during Renovate jobs. Do _not_ put the directive(s) in the lockfile, as this is _not_ supported. ```title="requirements.in" --extra-index-url https://pypi.my.domain/simple private-package==1.2.3 ``` ```json { "pip-compile": { "managerFilePatterns": ["requirements.txt"] }, "hostRules": [ { "matchHost": "pypi.my.domain", "username": "myuser", "password": "mypassword" } ] } ``` #### Packages that Renovate needs Renovate relies on `pip`'s integration with the Python [keyring](https://pypi.org/project/keyring/) package along with the [keyrings.envvars](https://pypi.org/project/keyrings.envvars/) backend for this. ##### Self-hosting Renovate This section only applies to users who self-host Renovate. If you self-host and use Containerbase, or our Docker sidecar container, then Renovate can already access the packages it needs. But if you are self-hosting Renovate and: - _not_ running Renovate in a Containerbase environment - or, _not_ using the Docker sidecar container Then you must install the Python keyring package and the keyrings.envvars package into your self-hosted environment. ### poetry For every Poetry source, a `hostRules` search is done and then any found credentials are added to env like `POETRY_HTTP_BASIC_X_USERNAME` and `POETRY_HTTP_BASIC_X_PASSWORD`, where `X` represents the normalized name of the source in `pyproject.toml`. ```js module.exports = { hostRules: [ { matchHost: 'pypi.example.com', hostType: 'pypi', username: process.env.PYPI_USERNAME, password: process.env.PYPI_PASSWORD, }, ], }; ``` If you're self-hosting Renovate via the [GitLab Runner](../getting-started/running.md#gitlab-runner) and want to access packages from private GitLab registries, you can use the GitLab CI job token for authentication: ```js module.exports = { hostRules: [ { matchHost: 'gitlab.example.com', hostType: 'pypi', username: 'gitlab-ci-token', password: process.env.CI_JOB_TOKEN, }, ], }; ``` ## Automatic hostRules credentials for platform-hosted registries ### GitHub Packages For GitHub Packages, Renovate will automatically provision hostRules for both `ghcr.io` (containers) and `*.pkg.github.com` (maven, npm, nuget, rubygems) using the GitHub platform token. This means that any private packages hosted on GitHub will be automatically authenticated if they are accessible using the same token by Renovate. If you wish to _override_ this authentication by providing a different token, then your rule must be _at least as specific_ as the automatic rule that Renovate generates. For example: ```json { "hostRules": [ { "matchHost": "npm.pkg.github.com", "hostType": "npm", "token": "some-personal-access-token" } ] } ``` ## Encryption and the Mend Renovate App Many users use [the Mend Renovate App](https://github.com/apps/renovate), which is hosted by Mend. If you are a user of this app, and have private modules, then the following is applicable. ### Private presets with public repositories If you have a preset in a private repo but reference ("extend") it from a public repository then it won't work. This is because public repositories are provided with a token scoped to only that particular repository, and not for all repositories within the organization. This is a security measure so that if a the token is accidentally leaked publicly, the damage is limited to the public repository it leaked to and not to every repository within the organization. The solution to this is that you should break your presets into public and private ones, and reference only the public ones from public repositories. ### Encrypting secrets It is strongly recommended that you avoid committing secrets to repositories, including private ones, and this includes secrets needed by Renovate to access private modules. The preferred approach to secrets is that the administrator configures them as `hostRules` which are then applied to all repositories which Renovate accesses. !!! warning "Store secrets for your Mend-hosted app via the web UI" Mend no longer supports putting encrypted secrets in the Renovate config file on your repository. Going forward, all secrets must be stored in the App settings via the web UI. If you have encrypted secrets in your Renovate config, you must migrate them to the web UI. Read [Migrating Secrets from Repo Config to App Settings](../mend-hosted/migrating-secrets.md) to learn how. If you need to provide credentials to the Mend Renovate App, please do this: 1. Add each secret string in the Credentials section of Organisation or Repository settings in the web UI at [http://developer.mend.io](http://developer.mend.io). 2. Reference secrets inside your Renovate config files with notation: `{{ secrets.YOUR_SECRET }}`. ```json { "hostRules": [ { "matchHost": "github.com", "token": "{{ secrets.RENOVATE_GITHUB_COM_TOKEN }}" } ] } ``` For more details, see [Using Secrets with Mend Cloud Apps](../mend-hosted/credentials.md). ### Access to GitHub Actions Secrets The Mend Renovate App does not run using GitHub Actions, but such secrets would be a bad fit for the app anyway for the following reasons: - The app would be granted access to _all_ the repository/org secrets, not just the ones you want - If Renovate wants access to such secrets, it would need to ask for them from every user, not just the ones who want to use this approach (GitHub does not support the concept of optional permissions for Apps, so people do not have the option to decline) ## Admin config vs User/Repository config for Self-hosted users "Admin config" refers to the config which the Renovate administrator provides at startup, e.g. using environment variables, CLI parameters, or the `config.js` configuration file. User/Repository config refers to the in-repository config file which defaults to `renovate.json` but has a large number of alternative filenames supported. If there is a need to supply custom rules for certain repository, it can still be done using the `config.js` file and the `repositories` array. If per-repository config must be done within the repository, it is still recommended against committing secrets directly (including e.g. `.npmrc` files with tokens) and instead encrypting them with a custom public key first. For instructions on this, see the above section on encrypting secrets for the Mend Renovate App but instead: - Save a copy of the HTML file locally, or host it locally - Generate a public/private key pair for the app using the instructions in [privateKey](../self-hosted-configuration.md#privatekey) - Replace the existing public key in the HTML with the public key you generated in the step prior - Use the resulting HTML encrypt page to encrypt secrets for your app before adding them to user/repository config - Configure the app to run with `privateKey` set to the private key you generated above !!! note Encrypted values can't be used in the "Admin config". ### hostRules configuration using environment variables Self-hosted users can enable the option [`detectHostRulesFromEnv`](../self-hosted-configuration.md#detecthostrulesfromenv) to configure the most common types of `hostRules` via environment variables. --- ## File: docs/usage/getting-started/running.md # Running Renovate As end user, you can choose from these ways to run Renovate: - You use the Mend Renovate App - You self-administer/host your own Renovate instance - Someone else is hosting Renovate, and you install/configure it for the repositories you choose If you're using the Mend Renovate App, or if someone else is hosting Renovate for you, skip ahead to the [installing & onboarding](./installing-onboarding.md) page. ## Self-Hosting Renovate When self-hosting Renovate you're the "administrator" of that deployment, this means you: - provide the infrastructure that Renovate runs on, - provision Renovate's global config, - make sure Renovate runs regularly, - make sure Renovate itself is updated If you're self-hosting Renovate on Windows, read [Self-hosting on Windows](./installing-onboarding.md#self-hosting-on-windows) to prevent line endings from confusing Renovate. If you're running Renovate Community Edition or Renovate Enterprise Edition, refer to the documentation on the [`mend/renovate-ce-ee` GitHub repository](https://github.com/mend/renovate-ce-ee). ### Available distributions #### npm package (CLI) Renovate's Open Source CLI is built and distributed as the npm package `renovate`. You can run this package in any Node.js environment - even via `npx` - and it will process all the repositories it is configured with, before exiting. When installing Renovate via npm you are responsible for installing any third-party tools or languages like Ruby, Python, Composer, Bundler, Poetry, etc. The `renovate` npm package is compatible with all of Renovate's supported platforms. #### Docker images Renovate is also distributed as Docker images on Docker Hub (`renovate/renovate`) and GitHub container registry (`ghcr.io/renovatebot/renovate`). These Docker images work on all the hosting platforms that Renovate supports. Both `linux/amd64` and `linux/arm64` architectures are supported, but you may still find some bugs in the `arm64` image. You can't run the Docker images in a Windows or macOS container. In general, you can run Renovate natively on Windows as long as you have all tools it will need (e.g. `npm`, `pipenv`, etc.) preinstalled before you run Renovate. There are two Docker image flavors: - The default image, which installs required tools at runtime (default for `latest` tag), - The `-full` image, which comes with latest or very recent versions of every tool pre-installed ##### The default image (formerly `slim`) The default image only comes with the Node.js environment. Renovate will then install any needed tools when it runs. Read the `binarySource=install` documentation for more details. We recommend this default image for most users. Renovate supports a persistent cache for downloaded tools, so that it only needs to unpack the tools on later runs. Use the [`containerbaseDir` config option](../self-hosted-configuration.md#containerbasedir) to control where Renovate stores its containerbase cache. !!! warning The usage of `binarySource=docker` is deprecated, and [will be removed in the future](https://github.com/renovatebot/renovate/issues/40747). If you want, you can map the Docker socket into the container so that Renovate can dynamically invoke "sidecar" images when needed. You'll need to set `binarySource=docker` for this to work. Read the [`binarySource` config option docs](../self-hosted-configuration.md#binarysource) for more information. ##### The full image The `-full` image comes with most package managers that Renovate supports, but not _all_ package managers. Update your Docker images regularly to keep the pre-installed tools up-to-date. The full image is for users who don't want to download or install things at runtime. This image has some downsides, because it: - Comes pre-installed with _one_ version of each language/manager - usually the latest - Weighs several gigabytes #### GitHub Action Renovate's npm tool is also provided as a GitHub Action on [`renovatebot/github-action`](https://github.com/renovatebot/github-action). Details on how to use it can be found in the repository. #### GitLab Runner The Renovate team provide a ["Renovate Runner"](https://gitlab.com/renovate-bot/renovate-runner/) project to make it easier to run Renovate as a CI pipeline job. This supports both `gitlab.com` and self-hosted GitLab. Details for how it works can be found in the project. #### Mend Renovate Self-Hosted (Community Edition / Enterprise Edition) Mend Renovate Self-Hosted Community Edition (sometimes "Renovate CE"/"CE") and Enterprise Edition (sometimes "Renovate EE"/"EE") are closed-source offerings of Renovate for self-hosted users. It is built similarly to the default "full" Renovate image described above, but with these differences: - It is a stateful app and does not exit after processing all repositories - It is installed as an App on GitHub, and behaves similarly on GitLab - for example responding to webhooks - It includes a priority job queue which prioritizes events like merged PRs over scheduled jobs - It is released every 2 weeks in a slightly slower and more stable cadence than Renovate OSS, which releases on every commit - It's licensed using an end-user license agreement (EULA) and not the Affero General Public License (AGPL-3.0-only) Plus, the Enterprise Edition has: - Horizontal scaling to run multiple 'worker' containers - Dedicated support from Mend.io - Premium features, including Smart Merge Control Mend Renovate Self-Hosted CE and EE have support for GitHub.com, GitHub Enterprise Server, GitLab.com, GitLab Self-Managed, and Bitbucket Data Center. Go to the Mend.io website to learn more about [Renovate Enterprise Edition](https://www.mend.io/renovate-enterprise/). To learn how to configure Renovate CE or Renovate EE, read the documentation on the public GitHub repository [`mend/renovate-ce-ee`](https://github.com/mend/renovate-ce-ee). #### Mend Remediate [Mend Remediate](https://docs.mend.io/integrations/latest/mend-remediate-and-renovate) is part of Mend's [Classic Repository Integrations](https://docs.mend.io/integrations/latest/mend-classic-repository-integrations) product which is for Mend commercial customers, with full enterprise support. It is integrated with Mend's vulnerability detection capabilities and additionally supports the capability of "horizontal" scalability - the ability to configure many Renovate "worker" containers which share a common job queue in order to not conflict with each other. Mend Remediate supports GitHub Enterprise Server, GitLab self-hosted, and Bitbucket Server. #### Forking Renovate app "Forking Renovate" is the sister app to the Mend Renovate App. The difference is that Forking Renovate does not need `write` permissions to create branches within the repo, and instead submits PRs from its own fork. Because of how it works, it functions on public repositories only and additionally cannot support `automerge` capabilities. [Install Forking Renovate from GitHub App store](https://github.com/apps/forking-renovate). ##### Benefits Forking Renovate needs only `read` level access to the code of any repository it runs on. ##### Drawbacks If you use Forking Renovate, you'll miss out on these features of the regular Renovate app: - Automerge - The `baseBranchPatterns` config option ### Hosting Renovate After deciding on a Renovate distribution, you need to decide where and how to run it. For the GitHub Action and GitLab Runner approaches, they will naturally run on their respective CI infrastructure. For the npm package approach or Docker images, you will need some form of VM or container infrastructure to run Renovate on. In all the above cases you must make sure that some form of cron-like capability exists to schedule when Renovate runs. We recommend that you run Renovate hourly, if possible. Mend Renovate On-Premises and Mend Remediate both run as long-lived containers, so they do not need any cron-like concept as it is built-in. ### Global config Renovate's server-side/admin config is referred to as its "global" config, and can be set by using either: - a config file, or - an additional config file, or - environment variables, or - CLI parameters By default Renovate checks if a file named `config.js` is present. Any other (`*.js`, `*.ts`, `*.json`, `*.json5`, `*.yaml` or `*.yml`) file is supported, when you reference it with the `RENOVATE_CONFIG_FILE` environment variable (for example: `RENOVATE_CONFIG_FILE=config.yaml`). Renovate checks for the additional config file only if the `RENOVATE_ADDITIONAL_CONFIG_FILE` is set. Behaviour wise this config is similar to the file config, except that it has higher priority than the default config file. Some config is global-only, meaning that either it is only applicable to the administrator or it can only be controlled by the administrator and not repository users. Those are documented in [Self-hosted Configuration](../self-hosted-configuration.md). Your global config can include both global as well as non-global configuration options, while user/repo config can only include non-global options. We recommend that you keep as much of the non-global config as possible in repository config files. This way the Renovate end users can see as much of the configuration as possible. If you are configuring Renovate using environment variables, there are two possibilities: - Upper-cased, camel-cased, `RENOVATE_`-prefixed single config options like `RENOVATE_TOKEN=abc123` or `RENOVATE_GIT_AUTHOR=a@b.com` - Set `RENOVATE_CONFIG` to a [stringified](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) version of the full JSON config, for example: `RENOVATE_CONFIG='{"token":"abc123","gitAuthor":"a@b.com"}'` If you combine both of the above then any single config option in the environment variable will override what's in `RENOVATE_CONFIG`. !!! note It's also possible to change the default prefix from `RENOVATE_` using `ENV_PREFIX`. For example: `ENV_PREFIX=RNV_ RNV_TOKEN=abc123 renovate`. #### Using `config.js` If you use a `config.js`, it will be expected to export a configuration via `module.exports`. The value can be either a plain JavaScript object like in this example where `config.js` exports a plain object: ```javascript module.exports = { token: 'abcdefg', }; ``` `config.js` may also export a `Promise` of such an object, or a function that will return either a plain JavaScript object or a `Promise` of such an object. This allows one to include the results of asynchronous operations in the exported value. An example of a `config.js` that exports an `async` function (which is a function that returns a `Promise`) can be seen in a comment for [#10011: Allow autodiscover filtering for repo topic](https://github.com/renovatebot/renovate/issues/10011#issuecomment-992568583) and more examples can be seen in [`file.spec.ts`](https://github.com/renovatebot/renovate/blob/main/lib/workers/global/config/parse/file.spec.ts). #### Using TypeScript config files Renovate supports TypeScript config files (`.ts`, `.mts`, `.cts`) via Node.js's built-in type stripping. Set the `RENOVATE_CONFIG_FILE` environment variable to point to your TypeScript config file: ```bash RENOVATE_CONFIG_FILE=config.ts renovate ``` An example `config.ts`: ```typescript import type { AllConfig } from 'renovate/dist/config/types'; const config: AllConfig = { platform: 'github', token: process.env.RENOVATE_TOKEN, repositories: ['my-org/my-repo'], }; export default config; ``` TypeScript config files follow the same rules as JavaScript config files: they can export a plain object, a `Promise`, or a function. The `.mts` extension is always treated as an ES module, and `.cts` is always treated as CommonJS. ### Authentication Regardless of platform, you need to select a user account for `renovate` to assume the identity of, and generate a Personal Access Token. We recommend you use `@renovate-bot` as username if you're on a self-hosted server where you can set all usernames. We also recommend you configure `config.gitAuthor` with the same identity as your Renovate user, for example: `"gitAuthor": "Renovate "`. !!! warning We recommend you use a single, dedicated username for your Renovate. Never share the Renovate username with your other bots, as this can cause flip-flopping. #### Docs Read the platform-specific docs to learn how to setup authentication on your platform: - [Azure DevOps](../modules/platform/azure/index.md) - [Bitbucket Cloud](../modules/platform/bitbucket/index.md) - [Bitbucket Server](../modules/platform/bitbucket-server/index.md) - [Forgejo](../modules/platform/forgejo/index.md) - [Gitea](../modules/platform/gitea/index.md) - [github.com and GitHub Enterprise Server](../modules/platform/github/index.md) - [GitLab](../modules/platform/gitlab/index.md) - [SCM-Manager](../modules/platform/scm-manager/index.md) ### GitHub.com token for changelogs (and tools) If you are running on any platform except github.com, you should also set the environment variable `RENOVATE_GITHUB_COM_TOKEN` and put the Personal Access Token for github.com in it. This account can be _any_ account on GitHub, and needs only `read-only` access. It's used when fetching changelogs for repositories, as well as some Renovate-specific tools at runtime, in order to increase the hourly API limit. It's also OK to configure the same as a host rule instead, if you prefer that. !!! note If you're using Renovate in a project where dependencies are loaded from github.com (such as Go modules hosted on GitHub), we highly recommend that you add a `github.com` PAT (classic). Otherwise you will exceed the rate limit for the github.com API, which will lead to Renovate closing and reopening PRs because it could not get reliable info on updated dependencies. ### Self-hosting examples For more examples on running Renovate self-hosted, read our [Self-hosted examples](../examples/self-hosting.md) page. ### Community tools There are also some [community-maintained tools](../community-tools.md) which may help running Renovate. --- ## File: docs/usage/getting-started/use-cases.md # Use Cases This page describes common use cases for Renovate. ## Development dependency updates The original use case, and the most popular one, is for developers to automate dependency updating in their software projects. ### Updating of package files We use the term "package file" to describe files which reference dependencies. Package files are managed by a "package manager". Example package files include: - `package.json`, managed by npm or Yarn - `Gemfile`, managed by Bundler - `go.mod`, managed by `go` modules #### How Renovate updates a package file Renovate: 1. Scans your repositories to find package files and their dependencies 1. Checks if any newer versions exist 1. Raises Pull Requests for available updates The Pull Requests patch the package files directly, and include changelogs for the newer versions (if they are available). By default: - You'll get separate Pull Requests for each dependency - Major updates are kept separate from non-major updates ### Package managers with lock files Many package managers support "lock files", which "freeze" the entire dependency tree including transitive dependencies. npm, Yarn, Bundler, Composer, Poetry, Pipenv, and Cargo all support or use lock files. If you use a lock file then changes to your package file must come with a compatible change to the lock file. Renovate can patch/update package files directly, but can't "reverse engineer" lock files. This is why Renovate lets the package manager do the lock file update. A simplified example: 1. The repository has a `package.json` and `package-lock.json` with version `1.0.0` of a dependency 1. Renovate sees that version `1.1.0` is available 1. Renovate patches the `package.json` to change the dependency's version from `1.0.0` to `1.1.0` 1. Renovate runs `npm install` to let `npm` update the `package-lock.json` 1. Renovate commits the `package.json` and `package-lock.json` 1. Renovate creates the PR ### Custom dependency extraction Renovate supports 90+ types of package files. By default, Renovate finds most dependencies, but there are exceptions. This can be because: - The package manager/file format is not supported, or - The file format is not a standard or is proprietary If your dependencies are not found by default, you can use our `custom` manager to set your own custom patterns to extract dependencies. You configure the custom manager by telling it: - Which file pattern(s) to match - How to find the dependency name and version from within the file - Which datasource (e.g. Docker registry, npm registry, etc) to use to look up new versions The end result is that Renovate can keep dependencies in custom file formats up-to-date as long as the dependency datasource is known to Renovate. ## DevOps tooling Renovate is increasingly used for purposes which are traditionally described as DevOps instead of Developer. ### DevOps / Infrastructure as Code updates It's common for repositories to have DevOps-related files like CI/CD configs, or "Infrastructure as Code" (IaC) files. Examples of IaC files are Docker, Kubernetes or Terraform files. Renovate handles IaC files as "package managers" and "package files" and can find and update them. #### Docker-compatible images Docker-compatible images are a key building block of modern software. These images are commonly found in CI/CD pipeline configs or referenced in IaC files. Renovate finds these IaC files and then searches Docker registries to see if there are newer tags or digests. #### Tag-based updating An example of tag-based updating are `node` images from Docker Hub. The `node` images use these tag formats: - `14.17.4` - `14.17.4-alpine3.11` Renovate understands both formats and raises updates like these: - From `14.17.4` to `14.17.5` - From `14.17.4-alpine3.11` to `14.17.5-alpine3.11` #### Docker digests You can check and update versions like `14.17.4` yourself. But looking up image digests like `341976f40d963a425d627a349a9b0034e1eafffbf4c82a173c1465ee403878d9` and updating them yourself doesn't scale. So let Renovate update your Docker digests. You can even configure Renovate to "pin" your Docker digests. When you're using tag+digest based images, you'll have immutable builds. ### Internal package updates Your company typically has dozens of repositories, if not hundreds or thousands. These repositories often rely on other repositories and may have upstream or downstream internal dependencies. In such cases, it is best practice to: - Update downstream links as soon as possible, and - Keep internal version use as consistent as possible You can use Renovate to follow this best practice. Renovate finds and updates internal dependencies just like external or Open Source dependencies. #### Automerge internal dependencies Renovate's automerge feature is really useful for internal dependencies where you can say "if it passes tests let's merge it". To learn more about "automerge" read the [key concepts, automerge](../key-concepts/automerge.md) documentation. #### Example of automerging internal dependencies We use these Renovate features to automerge an internal dependency: - [Git submodule support](../modules/manager/git-submodules/index.md) - [`automerge`](../configuration-options.md#automerge) set to `true` - [`automergeType`](../configuration-options.md#automergetype) set to `branch` ##### Background information We split our work over two repositories: 1. The [`renovatebot/renovate`](https://github.com/renovatebot/renovate) repository, which has the Renovate code, and most of the Markdown documentation files 1. The [`renovatebot/renovatebot.github.io`](https://github.com/renovatebot/renovatebot.github.io) repository, which has a submodule link to the `renovatebot/renovate` repository ##### Update process 1. We edit our documentation files on the main Renovate repository `renovatebot/renovate` 1. Renovate sees the change(s) to the `renovatebot/renovate` Git submodule, and creates an update branch on the _documentation build_ repository 1. If the tests pass Renovate automerges the update branch into the `main` branch. 1. A GitHub Actions workflow runs on `main` to build the documentation site and push the build live on our GitHub Pages domain ##### Benefits The way we've set things up means we avoid: - reviewing PRs - manually merging PRs In fact we don't even get the update PR anymore! ## Advanced configuration The capabilities listed below are commonly needed for all the above use cases. ### Batched updates Renovate defaults to separating each dependency update into its own PR. But you may want to batch or "group" updates together. For example, group all patch updates into one PR or even all non-major updates together (patches and minor updates). You can configure batched updates by setting a [`groupName`](../configuration-options.md#groupname) as part of `packageRules`. To learn more about batched updates, see [Package grouping](../noise-reduction.md#package-grouping). ### Scheduled updates You may want to limit the times when Renovate is allowed to raise updates. This reduces "noise" during your working hours, and reduces the chance of CI contention. You can tell Renovate to "not bother you" during times when you're using the CI resources, or want to focus on your work. You can set the time ranges during which Renovate creates updates in the `schedule` field. ### On-demand updates via Dependency Dashboard You can use Renovate's "Dependency Dashboard" on platforms which support dynamic Markdown checkboxes: - Forgejo - Gitea - GitHub - GitLab When you enable the Dependency Dashboard, Renovate creates a "Dependency Dashboard" issue. This issue lists all updates which are pending, in progress, or were previously closed ignored. If you want to get an update ahead of schedule, or want to retry a previously closed update: select the update's checkbox in the Dependency Dashboard. ### Dependency Dashboard Approval If you enable the Dependency Dashboard you can opt-in to a different workflow for some, or even all of your packages. We call this the "Dependency Dashboard Approval" workflow. Here's how it works: - You tell Renovate which package updates need "Dashboard Approval" by setting a custom `packageRule` - Renovate only raises updates for packages that need "Dashboard Approval" after you select the corresponding checkbox on the dashboard #### Benefits of using Dependency Dashboard Approval - By not raising PRs automatically, it allows you to request updates on-demand when you're ready, and - It offers you an alternative to permanently ignoring/disabling certain types of updates, like major updates When you use the Dependency Dashboard Approval workflow you have full visibility and control over your updates. ### Configuration presets You may run Renovate on many, or even all your repositories. This also means that you might want a similar config for all of your repositories. You can use configuration "presets" to avoid duplicating your configuration across your repositories. Configuration presets are JSON configuration files which are committed to repositories and then referenced from others. Renovate includes over 100 built-in presets, like the default recommended `config:recommended` preset. The typical workflow for a company is: - Create a dedicated repository to store the company's default Renovate settings - Set that repository as the default `extends` value when onboarding new repositories This means that repositories get the centralized config by default, and any changes made to the centralized config repository are propagated to other repositories immediately. ## How others use Renovate You can learn a lot by seeing how others use Renovate. Check out the [Swissquote user story](../user-stories/swissquote.md). --- ## File: docs/usage/key-concepts/automerge.md --- title: Automerge configuration and troubleshooting --- # Introduction You can choose to automate some dependency updates by letting Renovate automerge its PR. Renovate will wait for the required tests to pass before it automerges. ## Renovate automerges take time Renovate automerges take time, so Renovate can't automerge a PR the second it passes your required tests. Before you start troubleshooting, wait! Give Renovate about two hours, so Renovate can run in a state where your tests have passed, and the PR branch is up-to-date with the base branch. If you or others keep committing to the default branch then Renovate cannot find a suitable gap to automerge into! After Renovate automerges a branch, Renovate must calculate the "Git state" again, for all remaining branches. Merging one branch may result in another branch's updates being changed, or even removed as no longer needed. Renovate requires automerging branches to be up-to-date with their target branch, _before_ automerging. As merging more than one branch in a row does not work _reliably_, Renovate will only automerge one branch/PR, per target branch, per run. Then you'll have to wait for the next time Renovate runs. ## Recommendations from the Renovate maintainers In general, we recommend you enable automerge for any dependency update where you would select "merge" anyway. Keep automerge _disabled_ for updates where you want to read the changelogs or code before the merge. Automerge often works well for `devDependencies`. It can work for production `dependencies` too, but your project should have good test coverage. For example, if you have Jest or Mocha as a development dependency, and it has an upgrade with passing tests... automerge them! If you have a linter like ESLint or TSLint and its update passes... automerge them! If you have an API with 100% test coverage and Express is updated... automerge it! { loading=lazy } ## Configuration examples ### Automerge lock file maintenance The lowest risk type of update to automerge is probably `lockFileMaintenance`. When Renovate performs lock file maintenance, it leaves the project dependency definitions unchanged, but refreshes the lock file completely. This means Renovate installs the latest versions, that match the package file constraints. ```json title="Example of automerging lock file maintenance" { "lockFileMaintenance": { "enabled": true, "automerge": true } } ``` ### Automerge lint tool updates Automerging lint tool updates can be a real time-saver. Often a new lint tool version pass the updated tests, without any code changes on your end. If the tests pass you may as well automerge the PR. In cases where you need to make changes to your code, the Renovate PR will fail the linter check. You can then make the necessary code changes directly in the Renovate branch for that PR, confirm the tests pass with your changes, and manually merge the PR. ```json title="Example of automerging lint and Prettier development packages" { "packageRules": [ { "matchDepTypes": ["devDependencies"], "matchPackageNames": ["lint", "prettier"], "automerge": true } ] } ``` ### Automerge non-major updates Non-major updates in SemVer ecosystems shouldn't have breaking changes (if they follow the spec), so many users enable automerge for these too: ```json title="Example of automerging non-major updates in SemVer ecosystem" { "packageRules": [ { "matchUpdateTypes": ["minor", "patch"], "matchCurrentVersion": "!/^0/", "automerge": true } ] } ``` The `matchCurrentVersion` setting above is a rule to exclude any dependencies which are pre-1.0.0 because those can make breaking changes at _any_ time according to the SemVer spec. ### Automerge monorepo PRs Say you want to automerge `patch` and `minor` updates for packages in the `group:ionic-nativeMonorepo` preset: ```json title="Example of automerging patch and minor updates in a group from a preset" { "packageRules": [ { "extends": ["monorepo:ionic-native"], "matchUpdateTypes": ["patch", "minor"], "automerge": true } ] } ``` ### Faster merges with platform-native automerge By default, Renovate uses platform-native automerge to speed up automerging. If you don't want Renovate to use the platform-native automerge, then set `platformAutomerge` to `false`. ```json title="Example of disabling platform-native automerge" { "lockFileMaintenance": { "enabled": true, "automerge": true, "automergeType": "pr", "platformAutomerge": false } } ``` For more information read [`platformAutomerge`](../configuration-options.md#platformautomerge). ### GitHub Merge Queue Renovate supports GitHub's Merge Queue. Read the [GitHub Docs, managing a merge queue](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) first. The steps to enable GitHub's Merge Queue differ based on whether you use GitHub Actions or another CI provider. With `platformAutomerge` enabled (which is the default), GitHub's auto-merge takes care of adding the PR to the merge queue. This requires the "Allow auto-merge" checkbox in the repository settings to be enabled, as described in the steps below. Merge queues also work with `platformAutomerge=false`: Renovate first attempts to merge the PR directly, which succeeds when Renovate is on the merge queue's bypass list. If that merge is refused and the base branch has a merge queue, configured via classic branch protection or repository rulesets, Renovate adds the PR to the merge queue itself once all checks have passed. In that case the "Allow auto-merge" checkbox is not needed. PRs that are already waiting in the merge queue are left untouched on later runs. We recommend enabling the "Automatically delete head branches" repository setting, so branches get cleaned up after the merge queue merges the PR. !!! warning Branch automerge (`automergeType=branch`) only works if the base branch has a merge queue when Renovate is on the merge queue's bypass list, because pushing directly to the base branch is not possible otherwise. Renovate logs a warning and creates a PR instead if the merge queue rejects the push. Configure `automergeType=pr` in such repositories, or add Renovate to the bypass list. !!! tip "GitHub Merge Queue overview page" GitHub has a page that shows all the PRs in the Merge Queue. The page link follows this pattern: `https://github.com/organization-name/repository-name/queue/base-branch-name`. For example, here's [Renovate's main repository's Merge Queue overview](https://github.com/renovatebot/renovate/queue/main). #### If you use GitHub Actions If you use GitHub Actions as your CI provider, follow these steps: Add the `on.merge_group` event to your GitHub Action `.yaml` files, for example: ```yaml on: pull_request: merge_group: ``` On `github.com`, go to your repository's "homepage", click on Settings, scroll down to the Pull Requests section and [enable the "Allow auto-merge" checkbox](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository#managing-auto-merge). Then go to your repository's branch protection rules for your base branch (usually `main`) and enable the "Require merge queue" setting. Confirm you've set the correct "required checks" for your base branch. Finally, allow Renovate to automerge by setting `automerge=true` in your Renovate config file, for example: ```json { "packageRules": [ { "description": "Automerge non-major updates", "matchUpdateTypes": ["minor", "patch"], "automerge": true } ] } ``` #### If you don't use GitHub Actions If you _don't_ use GitHub Actions as your CI provider, follow these steps: Update your CI provider's configuration so it also runs tests on the temporary `gh-readonly-queue/{base_branch}` branches, read your CI providers's documentation to learn how to do this. On `github.com`, go to your repository's "homepage", click on Settings, scroll down to the Pull Requests section and [enable the "Allow auto-merge" checkbox](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository#managing-auto-merge). Go to your repository's branch protection rules for your base branch (usually `main`) and enable the "Require merge queue" setting. Confirm you've set the correct "required checks" for your base branch. Finally, allow Renovate to automerge by setting `automerge=true` in your Renovate config file (see earlier example). ### GitLab Merge Trains Renovate supports GitLab's [merge trains](https://docs.gitlab.com/ci/pipelines/merge_trains/). Renovate detects whether merge trains are enabled on the project and then: - With `platformAutomerge` enabled (the default), Renovate asks GitLab to add the MR to the merge train once its pipeline succeeds. This requires GitLab 17.11 or later. - With `platformAutomerge=false`, Renovate adds the MR to the merge train itself once all checks have passed, instead of merging it directly. - `rebaseWhen=auto` resolves to `conflicted` instead of `behind-base-branch`, because the merge train already tests MRs against the head of the target branch. !!! warning Branch automerge (`automergeType=branch`) only works with merge trains if Renovate is allowed to push to the protected target branch. If the push is rejected, Renovate logs a warning and creates a MR instead. Configure `automergeType=pr` in such projects, or allow Renovate to push to the target branch. ## Automerging and scheduling Automerging is particularly beneficial if you have configured a schedule, because Renovate on its own may be able to automerge the majority of your updates. And this is especially so if your repository needs rebasing, like when you use lock files. Let's say you have dependencies `abc` and `xyz` with upgrades, and you use a `yarn.lock` file. - At the start of the schedule, `Renovate` will create branches for `abc` and `xyz` upgrades, including `yarn.lock` updates - After `abc` passes tests, `Renovate` will automerge it into the base branch - The `xyz` branch has a `yarn.lock` conflict now - Renovate will immediately check all other branches and rebase them - The change to `xyz` branch will trigger another round of CI tests - After the updated `xyz` branch passes, Renovate will automerge it too This is a lot better than you waking up to two PRs and then having to deal with conflicts yourself after you merge the first one. ## Branch vs PR automerging Even if you automerge PRs, you are likely to still get notification noise - one when the PR is created and another when it is merged. For this reason we recommend you consider setting `automergeType=branch` which will mean: - Renovate first creates a branch and no PR - If tests pass, Renovate pushes a commit directly to the base branch without PR - If tests fail, Renovate raises a PR for you to review Add the `renovate/**` branch to your testing workflow files, or Renovate will not work properly with the `automergeType=branch` setting. The result is that passing updates are essentially "silent" - the only sign of them are the commits Renovate pushes to your base branch. If you have enabled branch protection which prevents Renovate from automerging directly to the base branch, then this won't work and you should stick with the default PR-based automerging instead. ## Assignees and Reviewers When automerge is enabled on a PR, Renovate will _not_ add assignees or reviewers at PR creation time, in order to decrease notifications noise a little. If tests subsequently _fail_, making automerge not possible, then Renovate will add the configured assignees and/or reviewers. Note: Renovate won't add assignees and reviewers to a PR with failing checks if the PR already has assignees or reviewers present. If there are accounts you wish to ignore (i.e. add assignees and reviewers regardless) then add them to `ignoreReviewers` to specify those which should be filtered out in such consideration. If you want Renovate to _always_ add assigness and reviewers to a PR regardless of automerge configuration, activate the [`assignAutomerge` option](../configuration-options.md#assignautomerge). ## Frequent problems and how to resolve them ### Automerge not enabled correctly in config Sometimes, the reason Renovate is not automerging a PR is because of a configuration mistake. You can confirm that Renovate knows you want it to automerge by checking if the PR body includes the text "Automerge: Enabled". If you see "Automerge: Disabled by config" it means you need to make a config change for automerge to work. ### Absence of tests By default, Renovate will not automerge until it sees passing status checks / check runs for the branch. If you have no tests but still want Renovate to automerge, you need to add `"ignoreTests": true` to your configuration. !!! tip We strongly recommend you have tests in any project where you are regularly updating dependencies. ### Committer restrictions If you have protected your base branch with a list of allowed committers, and Renovate is not on that list, then naturally automerge can't work. ### Pull Requests Required If you have configured your project to require Pull Requests before merging, it means that branch automerging is not possible, even if Renovate has rights to commit to the base branch. ### Required Pull Request reviews If you have mandatory Pull Request reviews then it means Renovate can't automerge its own PR until such a review has happened. If you're on `github.com` or GitHub Enterprise Server (`>=3.4`) you can let Renovate bypass the mandatory Pull Request reviews using the "[Allow specified actors to bypass required pull requests](https://github.blog/changelog/2021-11-19-allow-bypassing-required-pull-requests/)" option in your branch protection rules. Alternatively, if you use the Mend Renovate App, you can also install the helper apps [renovate-approve](https://github.com/apps/renovate-approve) and [renovate-approve-2](https://github.com/apps/renovate-approve-2) and they will mark all automerging Pull Requests by Renovate as approved. These approval helper apps are only available for GitHub. On Azure/Gerrit/Gitlab, you can activate the [`autoApprove` option](../configuration-options.md#autoapprove). ### Codeowners Depending on the platform, having a `CODEOWNERS` file could block automerging, because it means a code owner must review the PR. ### Overriding global automerge You might have setup a global configuration in a `.github` repository, that has a `renovate.json` file that turns on automerge for certain dependencies. It does not matter where you've put the global config, the important point in this example is that you're extending from a global config that's somewhere else. For this example we'll assume you put your config in a repository on GitHub, called `.github`. Repositories in the organization all extend from this global configuration, and so they "inherit" the automerge settings as well. To turn off automerge for all dependencies of a selected repository, you need to make a config that overrides all `packageRules` in the repository's `renovate.json` file, like this: ```json { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["local>org-name/.github:renovate-config"], "packageRules": [ { "matchPackageNames": ["*"], "automerge": false } ] } ``` --- ## File: docs/usage/key-concepts/dashboard.md --- title: Dependency Dashboard --- # Introduction Renovate has a Dependency Dashboard that shows an overview of the state of your repositories' dependencies. When the Dependency Dashboard is enabled, Renovate will create a new issue in the repository. This issue has a "dashboard" where you can get an overview of the status of all updates. Having the Dependency Dashboard also enables the concept of an "approval" workflow for new upgrades, either for selected dependencies (recommended) or even for all. ## Supported platforms The Dependency Dashboard requires that the host platforms supports the concept of issues with dynamic Markdown checkboxes. Read [our FAQ, Renovate core features not supported on all platforms](../faq.md#renovate-core-features-not-supported-on-all-platforms) to see if your platform can use the Dependency Dashboard feature. ## How to enable the dashboard To turn on the Dashboard manually, add the `:dependencyDashboard` preset to your `extends` array in the Renovate configuration file: ```json { "extends": ["schedule:automergeDaily", ":dependencyDashboard"] } ``` Or set `dependencyDashboard` to `true`: ```json { "dependencyDashboard": true } ``` ## How to disable the dashboard To disable the Dependency Dashboard, add the preset `:disableDependencyDashboard` or set `dependencyDashboard` to `false`. ```json { "extends": ["config:recommended", ":disableDependencyDashboard"] } ``` ## Use cases This section explains some common use cases where having the Dependency Dashboard can help. ### Warnings for deprecated dependencies If Renovate finds: - packages flagged as deprecated on their registry, or - packages that have a community-sourced replacement PR available Then Renovate adds a prominent warning about these packages near the top of the Dependency Dashboard. Here is an example of how this can look: > The following dependencies are deprecated: | Datasource | Name | Replacement? | | ---------- | ------------------- | --------------------------------------------------------------------------------- | | npm | `airbnb-prop-types` | | | npm | `left-pad` | | #### Abandonment detection Renovate includes the `abandonments:recommended` preset (automatically included in `config:best-practices`) to help identify potentially abandoned packages. This preset: - Sets a default [`abandonmentThreshold`](../configuration-options.md#abandonmentthreshold) of `1 year` for all packages - Includes community-sourced overrides for packages that appear abandoned but are still maintained - Prevents updates to truly abandoned packages while allowing updates to packages with irregular release schedules **Usage:** ```json { "extends": ["abandonments:recommended"] } ``` You can contribute additional overrides by updating the [`abandonments.json`](https://github.com/renovatebot/renovate/blob/main/lib/data/abandonments.json) file. ### Visibility into rejected/deferred updates Renovate's Dependency Dashboard shows an overview of all updates that are still "to do". If you close an update PR from Renovate without merging, the Dashboard will list this update in the Closed/Ignored section. If you later change your mind about the update, you can get a new PR by selecting the corresponding checkbox on the dashboard. ### Dependency Dashboard Approval workflow Sometimes you want Renovate to wait for your approval before creating an update PR. You can customize this "wait for approval" behavior however you like best. At a high level the options are: - Require approval for _all_ updates - Require approval for a type of updates (`major` for example) - Require approval for specific packages You can mix and match these options as well. #### Require approval for all updates We do not recommend that you require approval for _all_ updates. When you require prior approval, you need to check the dashboard issue regularly to check for important updates. You'll probably forget to check often enough, and out of sight means out of mind! Maybe you find Renovate too noisy, and want to opt-out of getting automatic updates whenever they're ready. In this case, you can tell Renovate to wait for your approval before making any pull requests. This means that you have full control over when you get updates. But vulnerability remediation PRs will still get created immediately without requiring approval. To require manual approval for _all updates_, add the `:dependencyDashboardApproval` presets to the `extends` array in your Renovate configuration file: ```json { "extends": ["config:recommended", ":dependencyDashboardApproval"] } ``` #### Require approval for major updates Major updates often have breaking changes which require manual changes in your code before they can be merged. So maybe you only want to get major updates when you have sufficient time to check them carefully. Dependency Dashboard Approval is far superior to disabling major updates because at least you can fully see what's pending on the dashboard, instead of updates being totally invisible. If you want to require approval for major updates, set `dependencyDashboardApproval` to `true` within a `major` object: ```json { "major": { "dependencyDashboardApproval": true } } ``` #### Require approval for specific packages Sometimes you only want to update specific packages when you say so. Maybe a package doesn't follow Semantic Versioning, and has breaking changes on every new release, so you want to update on your terms. Or maybe you have a package that updates too rapidly for you to keep up with, and you want to update once in a while manually. If you want to approve specific packages, set `dependencyDashboardApproval` to `true` within a `packageRules` entry where you have defined a specific package or pattern. ```json { "packageRules": [ { "matchPackageNames": ["@somescope/**"], "dependencyDashboardApproval": true } ] } ``` --- ## File: docs/usage/key-concepts/how-renovate-works.md --- title: How Renovate works --- # Introduction Renovate usually performs these steps: - Cloning the repository - Scanning package files to extract dependencies - Looking up registries to check for updates - Applying any grouping rules defined - Pushing branches and raising Pull Requests Because Renovate must support a lot of dependency naming and versioning conventions, it has modules for each known convention. You can contribute your own modules, if you want. ## Modules Renovate's modules are: - [datasource](../modules/datasource/index.md) - [manager](../modules/manager/index.md) - [platform](../modules/platform/index.md) - [versioning](../modules/versioning/index.md) Renovate uses these modules in order: 1. The platform module interacts with the source control platform and clones the repository 1. The manager module looks for files based on their name and extracts the dependencies (each dependency has a datasource) 1. The datasource module looks up versions of the dependency 1. The versioning module validates and sorts the returned versions For example: 1. The `gitlabci` manager finds a dependency: `python:3.10-alpine` which has the `docker` datasource 2. The `docker` datasource looks for versions and finds: `[python:3.9,python:3.9-alpine,python:3.10,python:3.10-alpine,python:3.11,python:3.11-alpine]` 3. The `docker` versioning returns `python:3.11-alpine`, because that version is compatible with `python:3.10-alpine` # Workflow Here's an overview of the workflow: ``` /* Detailed source-code truncated for AI context efficiency. */ ```