📖 Deploy docs from your source tree to the GitHub wiki
🌐 Works across repositories (with a PAT)
📚 Pretty interface for Markdown docs
💻 Supports runs-on: windows-*
Getting started is easy! Just create a GitHub Actions workflow file that uses spenserblack/actions-wiki and you're good to go! 🚀 Here's a ready-made example to help you blast off:
name: Publish wiki
on:
push:
branches: [main]
paths: [wiki/**, .github/workflows/publish-wiki.yml]
concurrency:
group: wiki
cancel-in-progress: true
permissions:
contents: write
jobs:
wiki:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: spenserblack/actions-wiki@<version>
with:
# Whatever directory you choose will be mirrored to the GitHub
# .wiki.git. The default is .github/wiki.
path: wiki
❗ Make sure you turn on the GitHub wiki feature in your repo's settings menu.
You'll also need to manually create a dummy page to initialize the git repo
that powers the GitHub wiki. If you don't, when we push to your-repo.wiki.git
,
your workflow will fail because the wiki doesn't exist.
contents: write
permission! GitHub
recently changed the default permissions granted to jobs for new repositories.
If you're pushing to a wiki that's not the current repository you'll need to
get a GitHub PAT to push to it. The default ${{ secrets.GITHUB_TOKEN }}
won't cut it! You can generate a PAT in your GitHub Settings.
For example, if you created octocat/gigantic-mega-project-wiki to hold the wiki and you want to publish it to the GitHub wiki that belongs to another repository like octocat/gigantic-mega-project, you'd use a step like this in one of your GitHub Actions workflows.
- uses: spenserblack/actions-wiki@<version>
with:
path: .
# Notice that we use a github.com/ prefix here to support enterprise GitHub
# deployments on other domains.
repository: github.com/octocat/gigantic-mega-project
# Make sure this token has the appropriate push permissions!
token: ${{ secrets.GIGANTIC_MEGA_PROJECT_GITHUB_TOKEN }}
-
repository
: The repository housing the wiki. Use this if you're publishing to a wiki that's not the current repository. You can include a domain prefix if you have a hosted GitHub instance that you want to push to. Default is${{ github.repository }}
with the implicitgithub.com
domain. -
token
:${{ github.token }}
is the default. This token is used when cloning and pushing wiki changes. -
path
: The directory to use for your wiki contents. Default:.github/wiki
. -
commit-message
: The message to use when committing new content. Default isUpdate wiki ${{ github.sha }}
. You probably don't need to change this, since this only applies if you look really closely in your wiki. -
dry-run
: Whether or not to actually attempt to push changes back to the wiki itself. If this is set totrue
, we instead print the remote URL and do not push to the remote wiki. The default isfalse
. This is useful for testing.
There are quite a few GitHub wiki publishing actions on the GitHub Actions marketplace. There are, however, two that stick out. The
newrelic/wiki-sync-action is a good choice for if you need bidirectional
synchronization when someone edits the live wiki. This can be beneficial for
less-technical contributors. There's also Andrew-Chen-Wang/github-wiki-action
which is a direct competitor to this project. It offers more automatic features,
but has more complex configuration. It also doesn't support runs-on: windows-*
.
📚 If you're interested in more discussion of alternatives, check out #4.
This is a GitHub Action, so we inevitably use YAML. Make sure you quote the
right things! To test 🧪 the action, the current workflow is to open a PR and
then have the test.yml
workflow run a dry-run: true
iteration to
(hopefully) spot any flaws.
To get a better handle on the contribution process, check out our handy contributing guide. Happy coding! 👋