RENOVATE_SCHEDULE loses to repo config; RENOVATE_FORCE wins

On GitLab Free, where there is no hosted Renovate app, I run Renovate as a scheduled container inside GitLab CI (Self-hosting Renovate on GitLab CI). When combining daily security runs with a weekly repository schedule window (Daily runs, weekly batches), running the bot on demand requires triggering a GitLab CI pipeline manually.

Setting RENOVATE_SCHEDULE in the pipeline has no effect because Renovate merges repository configuration (renovate.json5) over environment variables. Overriding repository settings from a GitLab CI job requires the bot-admin force configuration object.

Usage

# .gitlab-ci.yml: a manual job that bypasses the repo schedule for one run
renovate:run-on-demand:
  extends: .renovate_run_base
  variables:
    RENOVATE_FORCE: '{"schedule":["at any time"]}'
  rules:
    - when: manual
      allow_failure: true

Renovate parses object-valued environment variables with JSON5, requiring valid JSON/JSON5 syntax.

Renovate’s configuration precedence explains the behavior:

• Generic environment parsing: env.ts reads RENOVATE_<OPTION> for every option not explicitly marked env: false, delegating object values to coercions.ts.
• Repository merge precedence: In utils.ts, mergeChildConfig merges repository config over inherited environment options, concluding with return { ...config, ...config.force }. Only properties set inside force take precedence over repository-level config.

Notes

• Although the configuration options reference does not explicitly document an environment variable for schedule, Renovate still ingests RENOVATE_SCHEDULE. The setting fails to take effect only because repository configuration (renovate.json5) overrides inherited environment variables.
• force is restricted to bot administrators: accepted in self-hosted runner configuration or environment variables, and rejected inside repository renovate.json5. Pipeline CI variables are therefore the correct location for on-demand schedule overrides.
• Top-level force keys override only root configuration. Nested presets such as lockFileMaintenance.schedule or packageRules[].schedule remain governed by their own schedules unless explicitly specified inside the force payload.
• Apply force sparingly: properties declared in force unconditionally supersede repository-level rules across every branch processed by that run.

References

• Renovate force option. The sanctioned bot-admin override.
• Renovate env parser source. Generic RENOVATE_* handling.
• Renovate mergeChildConfig source. Repo config over env; force spread last.
• Daily runs, weekly batches. The companion setup post using this override.
• Self-hosting Renovate on GitLab CI. The container execution model on GitLab Free.