Merge Andrew-Chen-Wang/github-wiki-action

.github/workflows/test.yml

@@ -1,36 +1,46 @@
 name: Test
 on:
  push:
- branches: [main]
+ branches: [master]
  paths:
- - 'src/**'
- -  action.yml
- -  '.github/wiki/**'
- - '.github/workflows/test.yml'
+ - src/**
+ - action.yml
+ - wiki/**
+ - .github/workflows/test.yml
  pull_request:
- branches: [main]
+ branches: [master]
  paths:
- - 'src/**'
- - action.yml
- - '.github/wiki/**'
- - '.github/workflows/test.yml'
-# We don't want cancel-in-progress because we want each test (if there are
-# multiple at a given time) to still attempt to push to the wiki. This should
-# not cause any hiccups on the wiki since any and all tests are publishing in
-# the same content.
-concurrency: test
+ - src/**
+ - action.yml
+ - wiki/**
+ - .github/workflows/test.yml
+concurrency:
+ group: test-${{ github.ref }}
+ cancel-in-progress: true
 permissions:
  contents: write
 jobs:
  test:
+ strategy:
+ matrix:
+ os: [ubuntu-latest, macos-latest, windows-latest]
+ runs-on: ${{ matrix.os }}
+ steps:
+ - uses: actions/checkout@v3
+ - name: ./:clone
+ uses: ./
+ with:
+ strategy: clone
+ dry-run: true
+ - name: ./:init
+ uses: ./
+ with:
+ strategy: init
+ dry-run: true
+ test-master:
+ if: github.ref_name == 'master'
+ needs: test
  runs-on: ubuntu-latest
  steps:
  - uses: actions/checkout@v3
- - name: Write Rev
- run: 'git log -1 --format="%H" > .github/wiki/Rev.md'
  - uses: ./
- with:
- # For now, you'll need to manually specify a GitHub token until we
- # solve #2. The x: prefix is a dummy username.
- token: x:${{ secrets.GITHUB_TOKEN }}
- dry-run: ${{ github.ref != 'main' }}

README.md

@@ -18,99 +18,174 @@
 ## Usage
 
 ![GitHub Actions](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub+Actions&color=2088FF&logo=GitHub+Actions&logoColor=FFFFFF&label=)
-![GitHub wiki](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub+wiki&color=181717&logo=GitHub&logoColor=FFFFFF&label=)
+![GitHub](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub&color=181717&logo=GitHub&logoColor=FFFFFF&label=)
 
-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:
+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]
+ paths:
+ - wiki/**
+ - .github/workflows/publish-wiki.yml
 concurrency:
- group: wiki
+ group: publish-wiki
  cancel-in-progress: true
 permissions:
  contents: write
 jobs:
- wiki:
+ publish-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
+ - uses: spenserblack/actions-wiki@v1
 ```
 
-<img align="right" alt="Screenshot of 'Create the first page' button" src="https://i.imgur.com/ABKIS4h.png" />
+☝ 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.
 
-❗ 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.
+🔑 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'll need to remember to enable the `contents: write` permission! GitHub
-recently [changed the default permissions granted to jobs] for new repositories.
+<img align="right" alt="Screenshot of 'Create the first page' button" src="https://i.imgur.com/ABKIS4h.png" />
 
-### Publishing to a different repository
+⚠️ 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.
 
-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.
+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).
 
-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.
-
-```yml
-- 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 }}
-```
+💡 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.
 
 ### Options
 
+- **`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 include a
- domain prefix_ if you have a hosted GitHub instance that you want to push to.
- Default is `${{ github.repository }}` with the implicit `github.com` domain.
+ 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:
- `.github/wiki`.
+- **`path`:** The directory to use for your wiki contents. Default
+ `.github/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.
+ 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.
 
+#### `strategy:` option
+
+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.
+
+### Preprocessing
+
+You may wish to strip the `[link](page.md)` `.md` suffix from your links to make
+them viewable in GitHub source view (with the `.md`) _as well as_ in GitHub wiki
+(without the `.md`; pretty URLs!). You can use a preprocessing action like
+[Strip MarkDown extensions from links action] to remove those `.md` suffixes
+before using this action. Here's an example:
+
+```yml
+publish-wiki:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ - uses: impresscms-dev/strip-markdown-extensions-from-links-action@v1.0.0
+ with:
+ path: wiki
+ - uses: spenserblack/actions-wiki@v1
+```
+
+❤️ If you have an awesome preprocessor action that you want to add here, let us
+know! We'd love to add an example.
+
+### 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: spenserblack/actions-wiki@v1
+ with:
+ token: ${{ secrets.MEGA_PROJECT_GITHUB_TOKEN }}
+ repository: octocat/mega-project
+ path: .
+```
+
 ## Alternatives
 
 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-*`].
+which is a direct competitor to this project.
 
 📚 If you're interested in more discussion of alternatives, check out [#4].
 
@@ -132,12 +207,10 @@ To get a better handle on the contribution process, check out our handy
 [Andrew-Chen-Wang/github-wiki-action]: https://github.com/Andrew-Chen-Wang/github-wiki-action#readme
 [#4]: https://github.com/spenserblack/actions-wiki/issues/4
 [PAT]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
-[GitHub PAT]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
-[changed the default permissions granted to jobs]: https://github.blog/changelog/2023-02-02-github-actions-updating-the-default-github_token-permissions-to-read-only/
 [github actions marketplace]: https://github.com/marketplace?type=actions
-[generate a pat]: https://github.com/settings/tokens?type=beta
-[doesn't support `runs-on: windows-*`]: https://github.com/Andrew-Chen-Wang/github-wiki-action/discussions/28
 [contributing guide]: https://github.com/spenserblack/actions-wiki/blob/main/CONTRIBUTING.md
 [`test.yml`]: https://github.com/spenserblack/actions-wiki/blob/main/.github/workflows/test.yml
 [^1]: https://earthly.dev/blog/intercal-yaml-and-other-horrible-programming-languages/
+[supported markup languages]: https://github.com/github/markup#markups
+[Strip MarkDown extensions from links action]: https://github.com/marketplace/actions/strip-markdown-extensions-from-links-action
 <!-- prettier-ignore-end -->

action.yml

@@ -4,14 +4,29 @@ branding:
  icon: book
  color: blue
 inputs:
+ strategy:
+ description: >-
+ 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'.
+ required: true
+ default: clone
  repository:
  description: >-
  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 implicit github.com domain.
+ that's not the current repository. You can change the GitHub server with
+ the github-server-url input. Default is github.repository.
+ required: true
+ default: ${{ github.repository }}
+ github-server-url:
+ description: >-
+ An alternate https://github.com URL, usually for GitHub Enterprise
+ deployments under your own domain. Default is github.server_url (usually
+ https://github.com).
  required: true
- default: github.com/${{ github.repository }}
+ default: ${{ github.server_url }}
  token:
  description: >-
  github.token is the default. This token is used when cloning and pushing
@@ -25,11 +40,18 @@ inputs:
  default: .github/wiki
  commit-message:
  description: >-
- 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
+ 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.
  required: true
  default: Update wiki ${{ github.sha }}
+ ignore:
+ description: >-
+ 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.
+ required: true
+ default: ""
  dry-run:
  description: >-
  Whether or not to actually attempt to push changes back to the wiki
@@ -40,12 +62,14 @@ inputs:
 runs:
  using: composite
  steps:
- - id: index
- run: '"${GITHUB_ACTION_PATH%/}/src/index.sh"'
+ - run: '"${GITHUB_ACTION_PATH%/}/src/$INPUT_STRATEGY.sh"'
  shell: bash
  env:
+ INPUT_STRATEGY: ${{ inputs.strategy }}
  INPUT_REPOSITORY: ${{ inputs.repository }}
+ INPUT_GITHUB_SERVER_URL: ${{ inputs.github-server-url }}
  INPUT_TOKEN: ${{ inputs.token }}
  INPUT_PATH: ${{ inputs.path }}
  INPUT_COMMIT_MESSAGE: ${{ inputs.commit-message }}
+ INPUT_IGNORE: ${{ inputs.ignore }}
  INPUT_DRY_RUN: ${{ inputs.dry-run }}