How to create a bi-directional updated wiki

Before getting started, I recommend you have some basic knowledge of repository, branch, fork, action, and workflow.

The following is the outline of this document:

• At the original repository
• At forked repository
• Reference

At the original repository

1. [Optional] New branch for wiki

   • If you want the wiki at a different branch, please create a new branch branch_for_wiki for the wiki.
   • Click View all branches to see all branches.

   

   • Click New branch to create a new branch.

   

2. Copy the bi-directional-wiki.yaml

   • Cpoy the bi-directional-wiki.yaml under .github/workflows.

   bi-directional-wiki.yaml

   name: Documentation
   
   on:
     push:
       branches:
         - branch_for_wiki
       paths:
         - "wiki_docs/**"
     repository_dispatch:
       types: [wiki_docs]
     gollum:
   
   env:
     GIT_AUTHOR_NAME: Actionbot
     GIT_AUTHOR_EMAIL: [email protected]
   
   jobs:
     job-sync-docs-to-wiki:
       runs-on: ubuntu-latest
       if: github.event_name != 'gollum'
       steps:
         - name: Checkout Repo
           uses: actions/checkout@v2
         - name: Sync docs to wiki
           uses: newrelic/wiki-sync-action@main
           with:
             source: wiki_docs
             destination: wiki
             token: ${{ secrets.TOKEN_FOR_WIKI }}
             gitAuthorName: ${{ env.GIT_AUTHOR_NAME }}
             gitAuthorEmail: ${{ env.GIT_AUTHOR_EMAIL }}
   
     job-sync-wiki-to-docs:
       runs-on: ubuntu-latest
       if: github.event_name == 'gollum'
       steps:
         - name: Checkout Repo
           uses: actions/checkout@v2
           with:
             token: ${{ secrets.TOKEN_FOR_WIKI }} # allows us to push back to repo
             ref: branch_for_wiki
         - name: Sync Wiki to Docs
           uses: newrelic/wiki-sync-action@main
           with:
             source: wiki
             destination: wiki_docs
             token: ${{ secrets.TOKEN_FOR_WIKI }}
             gitAuthorName: ${{ env.GIT_AUTHOR_NAME }}
             gitAuthorEmail: ${{ env.GIT_AUTHOR_EMAIL }}
             branch: branch_for_wiki
   

3. Create a token for the action bot

   • Setting of your account > Developer setting > Personal access tokens > Generate new token

   

4. Create a repository secret token

   • Go to Setting of the repository > Security > Secrets and variables > Actions > Repository secrets
   • Please check the repo and the workflow options.

   

   • Click New repository secrets, and then you will see the following. Please fill TOKEN_FOR_WIKI in the Name and your personal access token in Secret.

5. Update bi-directional-wiki.yaml

   • Modify the bi-directional-wiki.yaml to match the repo, if your token name, doc directory, and the branch name are not default.

6. Congratulations :tada:

   • Now, you may edit the wiki on the web or push the wiki content to the branch_for_wiki. The wiki will be updated for both sides.

At forked repository

1. Fork the repository

   • Fork the original repository.

   

2. Create first page

   • Click the Wiki page and create the first page

   

3. Create a token for the action bot

   • Setting of your account > Developer setting > Personal access tokens > Generate new token
   • Please check the repo and the workflow options.

   

   • Remember to save the token since it will only be shown once!

4. Create a repository secret token

   • Go to Setting of the repository > Security > Secrets and variables > Actions > Repository secrets

   

   • Click New repository secrets, and then you will see the following. Please fill TOKEN_FOR_WIKI in the Name and your personal access token in Secret.

5. Enable actions

   • Enable workflows to run in the forked repository.
   • Click Actions > click the green button.

6. Initialize wiki

   • If the branch_for_wiki is NOT forked, please add a new branch called branch_for_wiki and set the upstream/source properly. Once the branch_for_wiki is created, the wiki should also be updated.
   • If the branch_for_wiki is forked, please run the workflow manually. Click Action > Workflows > Documentation > Run workflow > choose Branch: branch_for_wiki > Click green Run workflow. Once the workflow is done, the wiki is also updated.

7. Congratulations :tada:

   • Now, you may edit the wiki on the web or push the wiki content to the branch_for_wiki. The wiki will be updated for both sides.

Reference

1. Bi-directional Wiki Sync Action
2. Create Pull Requests For Your GitHub Wiki