Bidirectional Sync Feature/Combining PRs and Wiki UI Updates

[floydwilde]

I have a use case where a group using the wiki feature would like to have the best of both worlds: for longer, more significant changes, we would like to open a PR and go through a peer review process, while for smaller, less significant changes (such as fixing typos or making quick minor updates), we would still like to use the GitHub wiki UI.

There is another GitHub Action which has this feature:

• https://github.com/marketplace/actions/bi-directional-wiki-sync-action

It works well if you have it configured properly, but there is an obvious issue with the Actions script, where the action will not fail when Git is not configured properly, for instance if a variable is not set properly, there is a PR which has been open for about 6 months:

• fix: workflow should fail if git command fails newrelic/wiki-sync-action#8

There is a patch available to fix that, but NewRelic have stopped using this action for what they were using it for, as mentioned in this PR:

• Tabatha/update workflows newrelic/opensource-website#997

So, it doesn't look like they are going to continue to maintain that GitHub Action. I just wonder if users of this action would be interested in this feature, which would allow you to continue to use the GitHub Wiki UI, but also give you the option to create a PR for more significant changes?

I think this makes sense since the wiki editing feature is provided by Github, and you can use this event to trigger a workflow based on when someone updates the default branch of the wiki:

• https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#gollum

I am not certain how you would go about adding this feature to this GitHub Action, but would be happy to help or test it.

[jcbhmr]

I am of the opinion that this is best done in a separate action since the use case is so different? 🤔 Specifically: you'd somehow need to use this action both to push and to pull on completely different triggers which leads to some... interesting shared responsibilities. 🔀 You don't really want to use the same uses: Andrew-Chen-Wang/github-wiki-action@v4 for pulling and pushing in two separate workflow files do you? Or maybe you do. I don't really know. 😵

For instance, I use a pull-wiki.yml and a publish-wiki.yml since pulling the wiki and publishing the wiki are two fundamentally different triggers/cycles. One uses an every-day OR gollum event and the other uses the push event. The newrelic/wiki-sync-action action seems to put those into one workflow which gets a bit complex with if: ... statements everywhere.

Example live usage: 😎
https://github.com/jcbhmr/.github/blob/main/.github/workflows/publish-wiki.yml
https://github.com/jcbhmr/.github/blob/main/.github/workflows/pull-wiki.yml

There's also a bit of precedent here, though it's really @jcbhmr's push that got this into the docs instead of including this as a feature (i.e. it could be an included feature in the future 🤷‍♀️):

I think that such a pull-wiki-action would be absolutely fantastic to have exist! I think it would be a perfect fit to recommend to use in conjunction similar to the link preprocessing. I am just a bit unsure whether or not such a thing is worth including in this project. 🤔

My views do not represent those of @Andrew-Chen-Wang.

@Andrew-Chen-Wang What are your thoughts? This is kinda related to the "what should be in this action vs in other actions" question #26

[Andrew-Chen-Wang]

yea prob worth to include in this project but you can make three separate actions in one repo I think. If not, because GitHub wiki is so specific unlike a normal github repo, it also makes sense to bundle everything into a single action.

[jcbhmr]

Ok so I've somewhat lessened my opposition on this issue purely due to this project's name. This is "github-wiki-action" after all, so it makes sense to include everything, I guess. In not thrilled about tackling seemingly separate projects all in one thing, but if it fits the goal, i guess it fits the goal. 😕

Notably the challenge with this feature request is this:

on: push
- uses: Andrew-Chen-Wang/github-wiki-action@v5
  with:
    mode: push

on: gollum
- uses: Andrew-Chen-Wang/github-wiki-action@v5
  with:
    mode: pull

☝ you need two different workflow files or else you need something like this:

on:
  push:
  gollum:
- uses: Andrew-Chen-Wang/github-wiki-action@v5
  mode: ${{ event_name === "gollum" ? "pull" : "push" }}

However, it is possible to detect what the trigger was from inside the action using the ${{ github.* }} context https://docs.github.com/en/actions/learn-github-actions/contexts#github-context

# action.yml NOT a workflow file
- shell: bash
  run: echo "$GITHUB_EVENT_NAME"
  env:
    GITHUB_EVENT_NAME: ${{ github.event_name }}

so idk what the user-facing interface should be. @Andrew-Chen-Wang thoughts? @floydwilde thoughts?

---

as for:

but you can make three separate actions in one repo I think

You can... see https://github.com/netlify/actions

If we do make separate nested actions, then we won't be able to list them on the marketplace 😢 because the marketplace only allows publishing repos that have a root action.yml file, not subfolders.

imo I think the best course of action is to make it so that there's some kind of "mode" (maybe replacing the "strategy" option? or in addition to that?) for push/pull.

Also since we're on the topic, we might as well include https://github.com/impresscms-dev/strip-markdown-extensions-from-links-action and https://github.com/impresscms-dev/flattern-markdown-folder-structure-action 🤷‍♂️

[jcbhmr]

I know this is a long shot, but it this action moved to @wow-actions or @actionshub or @actions-ecosystem or @actions-cool or something as wow-actions/publish-wiki, then there'd be a great spot for a wow-actions/pull-wiki too! Remember, GitHub will automatically redirect stuff so it's a relatively safe move. Also this would make it easier for collaboration with @jcbhmr and potentially others (orgs have more permissions magic than personal repos)

[floydwilde]

Yes, I ended up going with two actions, one for pushing changes to the wiki repo, and one for syncing them back to a /wiki folder in the main repo. I considered it to be a sync since rsync is used similar to what I saw in the NewRelic action.

I haven't got my head around how the pull-action.yml works, maybe that is a better way. 🤔

I'm uncertain whether bundling everything in one action or having three different ones is better either.

If you do end up adding a pull or sync action, I could try using it and let you know how it goes.