{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreiga2ordjtyn3n2qfjvmcscdepbrj5ejdiqmymxbuv5kk4tid2teay",
    "uri": "at://did:plc:wszrgoqdwy3i2dfeub2mt3wf/app.bsky.feed.post/3lbdb3auxm4u2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreibk7ilcb5quri2t525amggpz4athfmo466xujf7qb2bl5tiggd75m"
    },
    "mimeType": "image/jpeg",
    "size": 26144
  },
  "description": "How to set up a copy of Renovate's documentation, pinned to an older version, for your organisation.",
  "path": "/posts/2024/11/19/renovate-private-docs/",
  "publishedAt": "2024-11-19T15:37:46.000Z",
  "site": "https://www.jvt.me",
  "tags": [
    "blogumentation",
    "renovate",
    "the public docs site",
    "Renovate 43.29.1 (2026-02-20)",
    "Material for MkDocs",
    "write it up as a form of blogumentation",
    "Renovate docs site",
    "Renovate 37.129.0",
    "`0b3b56a` aka 37.128.4",
    "`fc85d65` aka 37.129.1",
    "@latest",
    "@users.noreply.github.com"
  ],
  "textContent": "**Update 2026-03-06** : this post was updated to reflect the current state of Renovate. The existing version of the post can be seen below.\n\nIf you're self-hosting Renovate, you're generally going to be out-of-date compared to the upstream project's releases.\n\nThis isn't just because it takes time to update, but because Renovate as a project is _constantly shipping_ 🚀🚀🚀\n\nI've found it's more noticeable when you're running Mend Renovate Community/Enterprise Edition, which purposefully pin to a more stable version of the OSS project, and then updates regularly, which means there's generally a bit more of a lag between updates.\n\n(You _could_ pull `@latest`, but why live life on the edge?)\n\nSo one thing you may encounter is that - depending on how far behind you are on updates - you're reading documentation on the public docs site that doesn't match your version of Renovate.\n\nAs part of Renovate 43.29.1 (2026-02-20), we now distribute the built documentation site (built using Material for MkDocs) as part of each GitHub Release, allowing for users pinning to older versions of documentation to more easily access that documentation.\n\nThis significantly reduces the process that it used to require (seen below), as now you \"\"just\"\" download the `mkdocs-site.tgz` attachment from a release, upload that i.e. into GitHub Pages and you're done!\n\nIf you want to tweak the announcement bar, you'll need to either post-process it, or build it from scratch.\n\nHowever, now the Renovate project builds the documentation from the main repo - not the previously used docs repo - it also makes it simpler.\n\n## Prior to Renovate 43.29.1\n\n**Update 2026-03-06** : this is the original state of the blog post, left intact for future readers who may still be using an older version of Renovate.\n\nIf you're self-hosting Renovate, you're generally going to be out-of-date compared to the upstream project's releases.\n\nThis isn't just because it takes time to update, but because Renovate as a project is _constantly shipping_ 🚀🚀🚀\n\nI've found it's more noticeable when you're running Mend Renovate Community/Enterprise Edition, which purposefully pin to a more stable version of the OSS project, and then updates regularly, which means there's generally a bit more of a lag between updates.\n\n(You _could_ pull `@latest`, but why live life on the edge?)\n\nSo one thing you may encounter is that - depending on how far behind you are on updates - you're reading documentation on the public docs site that doesn't match your version of Renovate.\n\nHitting this a few times recently, I decided to set up a (private) mirror of the Renovate docs for the organisation, so we had an internal mirror that would tie _directly_ to the version that we're using.\n\nYou may ask why a private repo / mirror of the docs? Well the first thing is to avoid impacting the OSS project's Search Engine Optimisation (SEO) by avoiding a set of duplicate content on the public Web.\n\nA second reason is that when attempting to fork the repo \"properly\" and enabling GitHub Pages we see the following error:\n\n(There's discussion on the Renovate Slack to see if that's intended)\n\nAs I set this up yesterday, and it required a little work, I thought I'd write it up as a form of blogumentation.\n\n### Determining the revision\n\nFirst you want to determine the version of Renovate you are running, and work out what commit in the Renovate docs site this corresponds to.\n\nBecause the docs site changes over time, we're not necessarily going to be able to take the current version of the docs site's build tooling and use it against an old version of the Renovate project's docs.\n\nAs a somewhat arbitrary version, let's say that we're using Renovate 37.129.0 internally.\n\nWe would need to find which commit SHA the Renovate docs site was at when it bumped to that version of Renovate's docs - or at least, as close as possible.\n\nThis is needed to make sure that the build tooling and all its dependencies are aligned with what worked at the time.\n\nIn this case, the docs site didn't _directly_ upgrade to Renovate 37.129.0, but bumped from `0b3b56a` aka 37.128.4 to `5210010` (a non-existent commit upstream) to `fc85d65` aka 37.129.1 (skipping 37.129.0).\n\nWe can see this when viewing `git log -- deps/renovate` in the docs site, and correlating these commit hashes with commits in the Renovate repo:\n\n\n    commit eafcade47a39a17333d09af0cd48b81a6349d36f\n    Author: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>\n    Date:   Fri Jan 12 08:20:57 2024 +0000\n\n        chore(docs): update deps/renovate digest to fc85d65\n\n    commit af85dd913198c1c70d45176bdb4e667fd72afb68\n    Author: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>\n    Date:   Fri Jan 12 02:00:11 2024 +0000\n\n        chore(docs): update deps/renovate digest to 5210010\n\n    commit 789f1965a4a228697f29364917e9bf930e08e658\n    Author: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>\n    Date:   Thu Jan 11 10:41:22 2024 +0000\n\n        chore(docs): update deps/renovate digest to 0b3b56a\n\n\nIf you had picked a version that aligned with a commit exactly, you'd select that commit directly i.e. if 37.129.1 is the version you wanted, you'd use the commit hash `fc85d65`.\n\nHowever, in this case, we should select commit `af85dd913198c1c70d45176bdb4e667fd72afb68`, as the earlier commit, which means the repo is likely closer in configuration.\n\n### Create our \"fork\"\n\nNext, we need to create our \"fork\" of the repo.\n\n(The usage of \"scare quotes\" around \"fork\" is because this isn't a fork according to GitHub, but it is a technical fork of the repository)\n\nI'd recommend creating this (private) repo first, via ClickOps or the `gh` CLI.\n\nThen:\n\n\n    # from above\n    export RENOVATE_DOCS_SHA=af85dd913198c1c70d45176bdb4e667fd72afb68\n    git clone https://github.com/renovatebot/renovatebot.github.io internal-renovate-docs\n    # make sure we're down to the version of the docs site we want\n    git reset --hard $RENOVATE_DOCS_SHA\n\n\nNext, you want to push this up to your new repo.\n\n### GitHub repo settings\n\nBefore we can call our docs complete, we need to need to make sure that the repository is correctly set up:\n\n  * Enable GitHub Actions\n    * From the `/actions` page by clicking `Enable Actions on this repository`\n  * Enable GitHub Pages\n    * From the `/settings/pages` page\n    * Set the `Source` to `Deploy from a branch`\n    * Set the `Branch` to `gh-pages`\n      * This likely won't be set until the first deploy has pushed the branch\n    * Set the `Folder` to `/ (root)`\n\n\n\n### Code changes\n\nAdditionally, there are a few changes that you need to make in the docs site's code:\n\n  * Delete the `src/CNAME`\n    * So GitHub Pages doesn't try deploying to the official site\n  * Disable Renovate managing updates (`renovate.json`)\n    * As we don't want to keep things up-to-date (because we're pinned to a version of Renovate)\n  * Updating the banner (`overrides/main.html`)\n    * I.e. to provide additional context for your users to indicate it's an internal mirror, or the Renovate version that the docs are pointing to\n  * Updating MKDocs configuration (`mkdocs.yml`, not really necessary)\n    * To update `repo_name`, `repo_url` and `site_url`, so embedded URLs i.e. to \"edit this page\" work\n\n\n\n### Push\n\nOnce you've completed these changes, you can now push the changes, and that should trigger a GitHub Actions build that will then trigger GitHub Pages.\n\nYou may need to go in and update the GitHub Pages settings to publish from the `gh-pages` branch at this point, now it's pushed.\n\nYou'll now have your own internal copy of the documentation that aligns with your Renovate version and you can update as-and-when you're ready to 🚀",
  "title": "Creating a private mirror of the Renovate docs",
  "updatedAt": "2026-03-06T13:49:11.000Z"
}