From 6a1228f6e509e3056181f8b0761bc5ea17e9a9f5 Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Tue, 23 May 2023 15:09:10 -0500 Subject: [PATCH 1/2] Merge https://github.com/Andrew-Chen-Wang/github-wiki-action/tree/9895b2d4f08caf4db609e9583d5298c666d046f3 --- .github/workflows/test.yml | 54 +++++++----- README.md | 174 ++++++++++++++++++++++++++----------- action.yml | 44 +++++++--- src/clone.sh | 115 ++++++++++++++++++++++++ src/git_exists.sh | 13 --- src/index.sh | 42 --------- src/init.sh | 82 +++++++++++++++++ 7 files changed, 386 insertions(+), 138 deletions(-) create mode 100644 src/clone.sh delete mode 100644 src/git_exists.sh delete mode 100755 src/index.sh create mode 100644 src/init.sh diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 43b6f7c..50d95b4 100644 --- a/.github/workflows/test.yml +++ b/.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' }} diff --git a/README.md b/README.md index b82e31b..7f8b24f 100644 --- a/README.md +++ b/README.md @@ -18,89 +18,165 @@ ## 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@ - 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 ``` -Screenshot of 'Create the first page' button +☝ 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. +Screenshot of 'Create the first page' button -### 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@ - 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 `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 @@ -108,9 +184,7 @@ 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 +206,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 diff --git a/action.yml b/action.yml index ef1c431..1b0d665 100644 --- a/action.yml +++ b/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 @@ -20,16 +35,23 @@ inputs: default: ${{ github.token }} path: description: >- - The directory to use for your wiki contents. Default .github/wiki. + The directory to use for your wiki contents. Default wiki. required: true - default: .github/wiki + default: 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 }} diff --git a/src/clone.sh b/src/clone.sh new file mode 100644 index 0000000..ae89188 --- /dev/null +++ b/src/clone.sh @@ -0,0 +1,115 @@ +#!/bin/bash + +# Remember, this enables fail-fast mode! We want this for scripts. If a command +# returns a non-zero exit code, this -e makes us exit then-and-there. +set -e +# When a job fails, you can re-run it with debug mode enabled. This is exposed +# to scripts via the ${{ runner.debug }} or $RUNNER_DEBUG variable. Here, we +# use the -z test to see if the $RUNNER_DEBUG exists. If so, we use the -x flag +# to print a '+ cmd arg1 arg2' of each command that's run in the script. This +# helps with debugging what commands and $VAR expansions are actually happening. +if [[ -z $RUNNER_DEBUG ]]; then + set -x +fi + +# We overwrite the $GITHUB_* environment variables with user-provided ones. +# GitHub Actions normally provides a bunch of $GITHUB_* env vars. These can +# be used in scripts to tailor them to the current GitHub thing (repo, issue, +# etc). Here, we want to use these same variables, but with our custom +# user-provided values instead. We overwrite the originals (in this process; +# we can't affect our parent process) with the user-provided (or default) +# values so that we can use the same $GITHUB_REPOSITORY semantics to refer to +# the current repo that the action is on (the default) or the user-provided +# repo that we want to use instead. We use the same var names to make it +# familiar. +export GITHUB_TOKEN="$INPUT_TOKEN" +export GITHUB_SERVER_URL="$INPUT_GITHUB_SERVER_URL" +export GITHUB_REPOSITORY="$INPUT_REPOSITORY" +# This is the default host that gh uses for clones and commands without a repo +# context (a .git folder). We use Bash string magic to get the github.com part +# from a full origin (no pathname) like https://github.com => github.com. The +# '#*//' operation removes '*//' from the start of the string. That's the +# 'https://' chunk. With that gone, we are left with 'github.company.com' or +# something similar. +export GH_HOST="${GITHUB_SERVER_URL#*//}" + +# We configure some special $GIT_* environment variables to make it so that +# we can have our special .git folder (you know, the one that holds all the +# critical repo information & history?) in a completely different location +# from our working tree! Normally, $GIT_DIR is automagically determined by +# walking up the folders from your $PWD until '.git/' is found. In this case, +# we want that in a temp folder. Then, we use $GIT_WORK_TREE to control what +# the base folder or "root" of the $GIT_DIR's repo should be. Normally, this +# would be the $PWD, but we want to set it to the $INPUT_PATH which is +# probably a subfolder of the project somwhere! +export GIT_DIR=$(mktemp -d) +export GIT_WORK_TREE="$INPUT_PATH" +# This is just good practice to clean up after yourself. It's not needed per-se. +# This is a one-off Actions runner that will delete every part of itself after +# completion. It's a good habit nonetheless. +trap 'rm -rf "$GIT_DIR"' SIGINT SIGTERM ERR EXIT + +# This setup-git is a command is what makes it so that we can be authorized to +# do normal 'git clone' and 'git push' operations without using the gh CLI. It +# auto-adds the credentials for the host in $GH_HOST and any additional --host +# options passed to it. We need this to make it so that our 'git push' at the +# end of this script works! +gh auth setup-git +# We also need to preemptively mark the $GIT_DIR as safe to use. Normally Git +# will protect you against doing insecure stuff in untrusted areas, and that's +# a good thing! In this case, though, we know that what we are doing in this +# temp folder is OK. +git config --global --add safe.directory "$GIT_DIR" + +# We clone the $GITHUB_REPOSITORY.wiki Git repo into a temp folder. This is +# a special Git repository that holds a flat file structure of markup files +# that are rendered on the Wiki tab in the GitHub web UI. We clone this repo +# into the aforementioned $GIT_DIR folder. We use the --bare option to make +# the underlying 'git clone' command that's run create just a .git folder +# without pulling out all the initial files (which is the default behaviour). +# So, we'll have a .git-like folder sitting in /tmp/id.1234 which we want to +# use as our .git folder that we commit to and use for the rest of the Git +# stuff. The $GIT_WORK_TREE is already set to use the $INPUT_PATH (likely a +# folder like 'wiki/'). +git clone "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.wiki.git" "$GIT_DIR" --bare +# This is a trick to make the git CLI think that there should be a worktree too! +# By default, --bare Git repos are pretty inert. We unset this and then use our +# previously configured $GIT_WORK_TREE. +git config --unset core.bare + +# We are using .gitignore syntax for the 'ignore' option. Here's where we put it +# to good use! We then immediately add everything verbosely to "apply" it. +echo "$INPUT_IGNORE" >>"$GIT_DIR/info/exclude" +git add -Av + +# This sets the default author & committer for the Git commit that we make. If +# you want to change this, you can! You can set the $GIT_AUTHOR_* and +# $GIT_COMMITTER_* env vars in your workflow and they should pass down to this +# 'git commit' operation. These values are from one of the popular Git commit +# actions: stefanzweifel/git-auto-commit-action [1] +# +# [1]: https://github.com/stefanzweifel/git-auto-commit-action/blob/master/action.yml#L35-L42 +git config user.name github-actions[bot] +git config user.email 41898282+github-actions[bot]@users.noreply.github.com +# Allowing an empty commit is way easier than detecting empty commits! This also +# makes semantic sense. If you run this action, it adds a commit to your wiki. +# How large that commit is comes down to your changes. 0 change = commit with 0. +# This works well with the default "Update wiki ${{ github.sha }}" message so +# that even if the commit is empty, the message has the SHA there. +git commit --allow-empty -m "$INPUT_COMMIT_MESSAGE" + +# If we are given 'dry-run: true', then we want to just print changes and stop +# without pushing. This is only used in testing right now. +if [[ $INPUT_DRY_RUN == true ]]; then + echo 'Dry run' + git remote show origin + git show + exit 0 +fi + +# This is the pushing operation! The origin remote looks something like: +# "https://github.com/octocat/awesome.wiki.git" with no token attached. That +# 'gh auth setup-git' is what makes the username & password automagically attach +# to that 'github.com' hostname! We aren't using -u or -f here since there +# shouldn't be a need. +git push origin master diff --git a/src/git_exists.sh b/src/git_exists.sh deleted file mode 100644 index 614373a..0000000 --- a/src/git_exists.sh +++ /dev/null @@ -1,13 +0,0 @@ -# shellcheck shell=bash - -git_exists() ( - set -e - - if git ls-remote -h "$1" &>/dev/null; then - echo "$1" - return 0 - else - echo "$(basename "$0"): $1 is not a Git repository" >&2 - return 1 - fi -) diff --git a/src/index.sh b/src/index.sh deleted file mode 100755 index 7f81cc0..0000000 --- a/src/index.sh +++ /dev/null @@ -1,42 +0,0 @@ -#!/bin/bash -set -e - -# shellcheck source=src/git_exists.sh -source "$(dirname "${BASH_SOURCE[0]}")/git_exists.sh" - -if ! git_exists "https://$GITHUB_ACTOR:$INPUT_TOKEN@$INPUT_REPOSITORY.wiki.git" &>/dev/null; then - echo "$(basename "$0"): https://$INPUT_REPOSITORY.wiki.git doesn't exist." >&2 - echo 'Did you remember to create the first wiki page manually?' >&2 - echo 'You can find more information on the readme. [1]' >&2 - echo - echo '[1]: https://github.com/spenserblack/actions-wiki#usage' - exit 1 -fi - -cd "$INPUT_PATH" - -git init -git config --local user.name github-actions -git config --local user.email github-actions@github.com -git remote add origin "https://$GITHUB_ACTOR:$INPUT_TOKEN@$INPUT_REPOSITORY.wiki.git" -git fetch origin -git reset origin/master - -# https://stackoverflow.com/a/2658301 -if [[ $(git status --porcelain 2> /dev/null | tail -n1) == "" ]]; then - echo 'No changes! Will not commit or push.' - rm -rf .git - exit 0 -fi - -git add --all -git commit -m "$INPUT_COMMIT_MESSAGE" - -if [[ $INPUT_DRY_RUN == true ]]; then - git remote show origin - git show -else - git push -u origin master -fi - -rm -rf ./.git diff --git a/src/init.sh b/src/init.sh new file mode 100644 index 0000000..0d2a7eb --- /dev/null +++ b/src/init.sh @@ -0,0 +1,82 @@ +#!/bin/bash + +# Remember, this enables fail-fast mode! We want this for scripts. If a command +# returns a non-zero exit code, this -e makes us exit then-and-there. +set -e +# When a job fails, you can re-run it with debug mode enabled. This is exposed +# to scripts via the ${{ runner.debug }} or $RUNNER_DEBUG variable. Here, we +# use the -z test to see if the $RUNNER_DEBUG exists. If so, we use the -x flag +# to print a '+ cmd arg1 arg2' of each command that's run in the script. This +# helps with debugging what commands and $VAR expansions are actually happening. +if [[ -z $RUNNER_DEBUG ]]; then + set -x +fi + +# We overwrite the $GITHUB_* environment variables with user-provided ones. +# GitHub Actions normally provides a bunch of $GITHUB_* env vars. These can +# be used in scripts to tailor them to the current GitHub thing (repo, issue, +# etc). Here, we want to use these same variables, but with our custom +# user-provided values instead. We overwrite the originals (in this process; +# we can't affect our parent process) with the user-provided (or default) +# values so that we can use the same $GITHUB_REPOSITORY semantics to refer to +# the current repo that the action is on (the default) or the user-provided +# repo that we want to use instead. We use the same var names to make it +# familiar. +export GITHUB_TOKEN="$INPUT_TOKEN" +export GITHUB_SERVER_URL="$INPUT_GITHUB_SERVER_URL" +export GITHUB_REPOSITORY="$INPUT_REPOSITORY" +# This is the default host that gh uses for clones and commands without a repo +# context (a .git folder). We use Bash string magic to get the github.com part +# from a full origin (no pathname) like https://github.com => github.com. The +# '#*//' operation removes '*//' from the start of the string. That's the +# 'https://' chunk. With that gone, we are left with 'github.company.com' or +# something similar. +export GH_HOST="${GITHUB_SERVER_URL#*//}" + +# We configure some special $GIT_* environment variables to make it so that +# we can have our special .git folder (you know, the one that holds all the +# critical repo information & history?) in a completely different location +# from our working tree! Normally, $GIT_DIR is automagically determined by +# walking up the folders from your $PWD until '.git/' is found. In this case, +# we want that in a temp folder. Then, we use $GIT_WORK_TREE to control what +# the base folder or "root" of the $GIT_DIR's repo should be. Normally, this +# would be the $PWD, but we want to set it to the $INPUT_PATH which is +# probably a subfolder of the project somwhere! +export GIT_DIR=$(mktemp -d) +export GIT_WORK_TREE="$INPUT_PATH" +# This is just good practice to clean up after yourself. It's not needed per-se. +# This is a one-off Actions runner that will delete every part of itself after +# completion. It's a good habit nonetheless. +trap 'rm -rf "$GIT_DIR"' SIGINT SIGTERM ERR EXIT + +# This setup-git is a command is what makes it so that we can be authorized to +# do normal 'git clone' and 'git push' operations without using the gh CLI. It +# auto-adds the credentials for the host in $GH_HOST and any additional --host +# options passed to it. We need this to make it so that our 'git push' at the +# end of this script works! +gh auth setup-git +# We also need to preemptively mark the $GIT_DIR as safe to use. Normally Git +# will protect you against doing insecure stuff in untrusted areas, and that's +# a good thing! In this case, though, we know that what we are doing in this +# temp folder is OK. +git config --global --add safe.directory "$GIT_DIR" + +git init -b master +git remote add origin "$GITHUB_SERVER_URL/$GITHUB_REPOSITORY.wiki.git" + +echo "$INPUT_IGNORE" >>"$GIT_DIR/info/exclude" +git add -Av + +git config user.name github-actions[bot] +git config user.email 41898282+github-actions[bot]@users.noreply.github.com + +git commit --allow-empty -m "$INPUT_COMMIT_MESSAGE" + +if [[ $INPUT_DRY_RUN == true ]]; then + echo 'Dry run' + git remote show origin + git show + exit 0 +fi + +git push -f origin master From 1181a523379aa9893d0a8d7e71f1382a506b273b Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Tue, 23 May 2023 15:15:18 -0500 Subject: [PATCH 2/2] Change default folder from wiki/ to .github/wiki/ --- README.md | 3 ++- action.yml | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7f8b24f..c6df816 100644 --- a/README.md +++ b/README.md @@ -90,7 +90,8 @@ is specific to GitHub wikis. - **`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/`. +- **`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, diff --git a/action.yml b/action.yml index 1b0d665..8b3ca6d 100644 --- a/action.yml +++ b/action.yml @@ -35,9 +35,9 @@ inputs: default: ${{ github.token }} path: description: >- - The directory to use for your wiki contents. Default wiki. + The directory to use for your wiki contents. Default .github/wiki. required: true - default: wiki + default: .github/wiki commit-message: description: >- The message to use when committing new content. Default is 'Update wiki