Get github-metadata gem working on Netlify

[timwis]

We use the github-metadata gem to provide a few things to Jekyll like the repository name (used by Netlify CMS config) and the 'Edit on GitHub' links. We may be able to get it working on Netlify; alternatively, we'll have to remove the dependency on the gem.

Detected issues:

• Editor UI saves changes to the wrong branch because site.github.source.branch resolves to gh-pages in editor/index.html
• Editor UI is missing the 'view live' links because absolute_url filter returns nil in editor/index.html
• editor/index.html sets local_backend to true because JEKYLL_ENV env var is not set to production. Setting it to production breaks the build because the github-metadata gem no longer falls back to the git remote origin to detect repository information, but instead expects the git repo passed to the PAGES_REPO_NWO env var in the format of owner/repo. Netlify's built-in env vars only include the full repo url.
• Setting JEKYLL_ENV to production makes the github-metadata gem set site.url to https://github.com/pages/<owner>/<repo> for some reason
• {{ github-edit-link }} tag uses default branch of upstream repo instead of whatever branch of the fork was deployed

Ideas so far:

• Set the env vars that the github-metadata gem needs via the build command, e.g. PAGES_REPO_NWO=$(sed . . . $REPOSITORY_URL) jekyll build
• Use a Netlify plugin to generate a _config_override.yml at build time file and change the build command in netlify.toml to jekyll build --config _config.yml,_config_override.yml
• Write a plugin that maps netlify env vars to github-metadata env vars, which should only run when building on Netlify

[timwis]

I've written a Netlify Build plugin (98a812b) to generate a _config_override.yml file, but issue 1 and 4 above still remain for some reason. I'll see if I can reproduce them locally by setting JEKYLL_ENV=production on my laptop's build.

[timwis]

Okay, I've dug in a lot deeper to the github-metadata gem, and I think I understand what's behind the two main issues:

• It's setting site.github.source.branch to the default branch of the upstream repository, not the fork. This probably isn't an issue in practice, but could be (whether for debugging, or if an admin wants to change the default branch of their repo, since they're not actually using github pages)
• It's setting baseurl according to the fact that the repository is a "user repository" rather than an "org repository". The plugin's designed to get the site working on github pages, and not for compatibility elsewhere. I've solved this one by explicitly declaring baseurl: "" in _config_override.yml

Very nearly there!

[timwis]

All right, I've reported the branch issue on the github-metadata repo, and implemented a workaround: the Netlify Build Plugin now saves the name of the branch being deployed to site.branch. When we configure the Editor UI in /editor/index.html, it now says branch: {{ site.branch | default: site.github.source.branch }}, using the value from the config if it's available, and defaulting back to whatever's generated by the github-metadata gem.

So, just to recap, we've essentially made the github-metadata gem "get out of the way" when deploying to Netlify. We do this by generating a supplemental _config.ci.yml file during the build process — but only in a Netlify build (via a Netlify build plugin). Jekyll loads this _config.ci.yml first, then loads the normal _config.yml, so an admin can override anything that's generated, if they prefer.

I think once we switch the GitHub Pages approach to using Actions, we should explore moving away from the github-metadata gem (because we can have the Action generate a _config.ci.yml file as well).