Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/andrew-chen-wang/github-wiki-action
📖 GitHub Action to sync a folder to the GitHub wiki
https://github.com/andrew-chen-wang/github-wiki-action
actions bash github-action github-actions github-wiki wiki
Last synced: about 2 months ago
JSON representation
📖 GitHub Action to sync a folder to the GitHub wiki
- Host: GitHub
- URL: https://github.com/andrew-chen-wang/github-wiki-action
- Owner: Andrew-Chen-Wang
- License: apache-2.0
- Created: 2020-06-16T18:10:45.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-07-17T01:15:19.000Z (over 1 year ago)
- Last Synced: 2024-10-22T03:43:37.764Z (2 months ago)
- Topics: actions, bash, github-action, github-actions, github-wiki, wiki
- Language: TypeScript
- Homepage:
- Size: 118 KB
- Stars: 67
- Watchers: 3
- Forks: 12
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Publish to GitHub wiki
📖 GitHub Action to sync a folder to the GitHub wiki
📂 Keep your dev docs in sync with your code \
💡 Inspired by [Decathlon/wiki-page-creator-action#11] \
🔁 Able to open PRs with docs updates \
✨ Use the fancy GitHub wiki reader UI for docs \
🌐 Works across repositories (with a [PAT]) \
💻 Supports `runs-on: windows-*`
## Usage
Add a GitHub Actions workflow file to your `.github/workflows/` folder similar
to the example shown below.
```yml
name: Publish wiki
on:
push:
branches: [main]
paths:
- wiki/**
- .github/workflows/publish-wiki.yml
concurrency:
group: publish-wiki
cancel-in-progress: true
permissions:
contents: write
jobs:
publish-wiki:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: Andrew-Chen-Wang/github-wiki-action@v4
```
☝ This workflow will mirror the `wiki/` folder in your GitHub repository to the
`user/repo.wiki.git` Git repo that houses the wiki documentation! You can use
any of the [supported markup languages] like MediaWiki, Markdown, or AsciiDoc.
🔑 In order to successfully push to the `.wiki.git` Git repository that backs
the wiki tab, we need the `contents: write` permission! Make sure you have
something like shown above either for your entire workflow, or just for one
particular job. This will give the auto-generated `${{ github.token }}` that we
use by default permission to push to the `.wiki.git` repo of the repository that
the action runs on.
⚠️ You must create a dummy page manually! This is what initially creates the
GitHub wiki Git-based storage backend that we then push to in this Action.
After creating your workflow file, now all you need is to put your Markdown
files in a `wiki/` folder (or whatever you set the `path` option to) and commit
them to your default branch to trigger the workflow (or whatever other trigger
you set up).
💡 Each page has an auto-generated title. It is derived from the filename by
replacing every `-` (dash) character with a space. Name your files accordingly.
The `Home.md` file will automatically become the homepage, not `README.md`. This
is specific to GitHub wikis.
### Inputs
- **`strategy`:** Select from `clone` or `init` to determine which method to use
to push changes to the GitHub wiki. `clone` will clone the `.wiki.git` repo
and add an additional commit. `init` will create a new repo with a single
commit and force push to the `.wiki.git`. `init` involves a force-push! The
default is `clone`.
- **`repository`:** The repository housing the wiki. Use this if you're
publishing to a wiki that's not the current repository. You can change the
GitHub server with the `github-server-url` input. Default is
`${{ github.repository }}`.
- **`github-server-url`:** An alternate `https://github.com` URL, usually for
GitHub Enterprise deployments under your own domain. Default is
`${{ github.server_url }}` (usually `https://github.com`).
- **`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 `wiki/`.
- **`commit-message`:** The message to use when committing new content. Default
is `Update wiki ${{ github.sha }}`. You probably don't need to change this,
since this only applies if you look really closely in your wiki.
- **`ignore`:** A multiline list of files that should be ignored when committing
and pushing to the remote wiki. Each line is a pattern like `.gitignore`. Make
sure these paths are relative to the path option! The default is none.
- **`dry-run`:** Whether or not to actually attempt to push changes back to the
wiki itself. If this is set to `true`, we instead print the remote URL and do
not push to the remote wiki. The default is `false`. This is useful for
testing.
- **`preprocess`:** If this option is true, we will preprocess the wiki to move
the `README.md` to `Home.md` as well as rewriting all `.md` links to be bare
links. This helps ensure that the Markdown works in source control as well as
the wiki. The default is true.
#### `strategy:` input
There are some specific usecases where using `strategy: init` might be better
than the default `strategy: clone`.
1. **Your wiki is enormous.** And I don't mean in terms of text. Text is nothing
compared with images. If your wiki has a lot of included images, then you
probably don't want to store the complete history of those large binary
files. Instead, you can use `strategy: init` to create a single commit each
time.
2. **You prefer the "deploy" semantics.** If you just like the feel of having
your GitHub wiki act more like GitHub Pages, that's great! You can `--force`
push using `strategy: init` on each wiki deployment and none of that pesky
history will be saved.
### Outputs
- **`wiki_url`:** The HTTP URL that points to the deployed repository's wiki
tab. This is essentially the concatenation of `${{ github.server_url }}`,
`${{ github.repository }}`, and the `/wiki` page.
### Cross-repo wikis
You _can_ use this action to deploy your octocat/mega-docs repository to the
octocat/mega-project repository's wiki tab! You just need to:
1. Create a custom GitHub Personal Access Token with the permissions to push to
the octocat/mega-project repository. That's the target repo where your wiki
pages will be pushed to the `.wiki.git`.
2. In the octocat/mega-docs repo (the source code for the wiki), you need to set
the `repository:` option to `repository: octocat/mega-project` to tell the
action to push there.
3. You need to set the `token:` option to the Personal Access Token that you
created with the ability to push to the wiki Git repo. You can use repository
secrets for this! Something like `token: ${{ secrets.MY_TOKEN }}` is good!
Here's an example of the octocat/mega-docs repo that will push the contents of
the root folder (`./`) to the octocat/mega-project repo's wiki tab!
```yml
on:
push:
branches: [main]
jobs:
publish-wiki:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: Andrew-Chen-Wang/github-wiki-action@v4
with:
token: ${{ secrets.MEGA_PROJECT_GITHUB_TOKEN }}
repository: octocat/mega-project
path: .
```
## Development
This GitHub Action uses a self-downloaded version of Deno. See `cliw` for the
`cli.ts` wrapper script that downloads the Deno binary and runs the TypeScript
code. The main script itself is ~100 lines of code, so it's not too bad.
ℹ Because the version of Deno is _pinned_, it's recommended to every-so-often
bump it to the latest version.
To test the action, open a PR! The `test-action.yml` workflow will run the code
with `dry-run: true` as well as a real run! Yes, this does get tedious swapping
between your IDE and the PR, but it's the easiest way to test the action.
[Decathlon/wiki-page-creator-action#11]: https://github.com/Decathlon/wiki-page-creator-action/issues/11
[supported markup languages]: https://github.com/github/markup#markups
[PAT]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token