From 288728941b78c6f278d676f4a3a843eb3fb70c49 Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Sat, 15 Jul 2023 23:38:40 -0500 Subject: [PATCH 1/3] Use this repo's wiki as a deploy test --- .github/workflows/test-action.yml | 34 +-------- wiki/Home.md | 15 ---- wiki/How-it-works.md | 104 ------------------------- wiki/README.md | 3 + wiki/github.token.md | 121 ------------------------------ 5 files changed, 5 insertions(+), 272 deletions(-) delete mode 100644 wiki/Home.md delete mode 100644 wiki/How-it-works.md create mode 100644 wiki/README.md delete mode 100644 wiki/github.token.md diff --git a/.github/workflows/test-action.yml b/.github/workflows/test-action.yml index be501fa..aadafbb 100644 --- a/.github/workflows/test-action.yml +++ b/.github/workflows/test-action.yml @@ -17,39 +17,9 @@ on: - README.md - .github/** - "!.github/workflows/test-action.yml" -concurrency: - group: ${{ github.workflow }}-${{ github.ref_name }} - cancel-in-progress: true +concurrency: ${{ github.workflow }}-${{ github.ref_name }} jobs: - test-action-clone: - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - runs-on: ${{ matrix.os }} - steps: - - uses: actions/checkout@v3 - - name: strategy=clone - uses: ./ - with: - strategy: clone - dry-run: true - test-action-init: - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - runs-on: ${{ matrix.os }} - steps: - - uses: actions/checkout@v3 - - name: strategy=init - uses: ./ - with: - strategy: init - dry-run: true - test-action-master: - if: github.ref_name == 'master' - needs: [test-action-clone, test-action-init] + test-action: permissions: contents: write runs-on: ubuntu-latest diff --git a/wiki/Home.md b/wiki/Home.md deleted file mode 100644 index f3ead93..0000000 --- a/wiki/Home.md +++ /dev/null @@ -1,15 +0,0 @@ - - -👋 Hello! Welcome to our dual-purpose test wiki & dev wiki! If you're seeing -this in the Wiki tab, then the GitHub Action successfully pushed the -contents of the `wiki/` folder to the GitHub wiki. 🥳 - -To learn more about how this action works, check out the [How it works] page. -If you're more interested in using this action, head back to the [README] to get -started using it in your own repository! 🚀 - -[How it works]: How-it-works -[README]: https://github.com/Andrew-Chen-Wang/github-wiki-action#readme diff --git a/wiki/How-it-works.md b/wiki/How-it-works.md deleted file mode 100644 index f612bd8..0000000 --- a/wiki/How-it-works.md +++ /dev/null @@ -1,104 +0,0 @@ -**Quick Bash recap:** Remember that `if [[ -n $VAR ]]` means "if var is non-zero -length" and `if [[ -z $VAR ]]` means "if var is zero length". We use this to -check for the presence of variables too. - -At the top of the file, we first `set -e` like good programmers to make sure -that errors _do propogate_ instead of being swallowed. Then, we conditionally -`set -x` to debug log only if the current Job is in debug mode. - -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 -n 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. - -We use a convention of overwriting the existing `GITHUB_*` env vars with our own -equivalent settings that we recieved from the user in the `github-server-url:` -and `token:` inputs. This is just a convention so that we can continue to use -`$GITHUB_TOKEN`. - -```sh -# 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#*//}" -``` - -```sh -# 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 && GIT_DIR=$(mktemp -d) -export GIT_WORK_TREE="$INPUT_PATH" -``` - -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! - -```sh -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. - -## `clone.sh`-specific - -```sh -# 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 -``` - -```sh -# 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. - -```sh -# 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/wiki/README.md b/wiki/README.md new file mode 100644 index 0000000..8b766cb --- /dev/null +++ b/wiki/README.md @@ -0,0 +1,3 @@ +👋 Hello! If you're seeing this in the Wiki tab, then the GitHub +Action successfully pushed the contents of the `wiki/` folder to the GitHub +wiki. 🥳 diff --git a/wiki/github.token.md b/wiki/github.token.md deleted file mode 100644 index a56f90c..0000000 --- a/wiki/github.token.md +++ /dev/null @@ -1,121 +0,0 @@ - - -When you interact with GitHub stuff, you need to be authenticated. In a GitHub -Action, this means using the `${{ github.token }}`. - -The `${{ github.token }}` is a special access token that you can use to -authenticate on behalf of GitHub Actions. GitHub automatically creates -a `${{ github.token }}` secret for you to use in your workflow, and you can use -it to authenticate in a workflow run. - -The way this works is that when you enable GitHub Actions in a repository, -GitHub installs a GitHub App on your repository. -The `${{ github.token }}` secret is a GitHub App installation access token. You -can use the installation access token to authenticate on behalf of the GitHub -App installed on your repository. The token's permissions are limited to the -repository that contains your workflow. - -Before each job begins, GitHub fetches an installation access token for the -job. The `${{ github.token }}` expires when a job finishes or after a maximum of -24 hours. - -The token is also available as the `$GITHUB_TOKEN` env variable in most places -without needing to be explicitly passed around. - -## Best practices - -You can use the `${{ github.token }}` by using the standard syntax for -referencing secrets: `${{ secrets.GITHUB_TOKEN }}`. You can pass the token as an -input to an action, or use it to make an authenticated GitHub API request. If -you are using a custom PAT, you should also avoid hardcoding the token value in -your workflow file or scripts. Instead, use `${{ secrets.MY_PAT }}`. - -Modern GitHub Actions will also default to using the current workflow's -`${{ github.token }}` value if non is provided by the user. This implicit token -passing makes workflows drasticly simpler. As a good security practice, you -should always make sure that actions only have the minimum access they require -by limiting the permissions granted to the `${{ github.token }}`. - -## How it's generated - -The `${{ github.token }}` is not a personal access token. It is a GitHub App -installation access token that is automatically created by GitHub when you -enable GitHub Actions in a repository. - -You do not need to create or manage the token yourself. You also do not need to -renew or rotate the token, as GitHub does that for you before each job. - -## Permissions - -| Scope | Permissive | Restricted | Max fork perms | -| ------------------- | ---------- | ---------- | -------------- | -| actions | read/write | | read | -| checks | read/write | | read | -| contents | read/write | read | read | -| deployments | read/write | | read | -| id-token | | | read | -| issues | read/write | | read | -| metadata | read | read | read | -| packages | read/write | read | read | -| pages | read/write | | read | -| pull-requests | read/write | | read | -| repository-projects | read/write | | read | -| security-events | read/write | | read | -| statuses | read/write | | read | - -You can change any of these permissions using the `permissions:` option in your -workflow `.yml` files. - -```yaml -permissions: - issues: write - contents: read -``` - -## Authentication - -You can use the `${{ github.token }}` to authenticate on the command line when -cloning a repository. You can enter the token instead of your password when -performing Git operations over HTTPS. - -For example, on the command line you would enter the following: - -```sh -git clone https://github.com/username/repo.git -``` - -``` -Username: your_username -Password: your_token -``` - -You can also use the token as part of the URL, like this: - -```sh -git clone https://your_username:your_token@github.com/username/repo.git -``` - -However, this is less secure and not recommended, as the token may be exposed in -plain text or in your shell history. - -If you are not prompted for your username and password, your credentials may be -cached on your computer. You can update your credentials in the Keychain or -Credential Manager to replace your old password with the token. - -Alternatively, you can use a credential helper to cache your token with a Git -client. - -```sh -gh auth setup-git -``` - -You can use the runner builtin `gh` CLI to configure `git` to use GitHub CLI as -a credential helper for all authenticated hosts. Alternatively, you can use -the `--hostname` flag to specify a single host to be configured. - -📚 Further reading: [Git - gitcredentials Documentation] - -[Git - gitcredentials Documentation]: https://git-scm.com/docs/gitcredentials From 2e34df6b9691ad925cf1ffff7da0d2213ca10c2b Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Sat, 15 Jul 2023 23:39:13 -0500 Subject: [PATCH 2/3] Remove nav links --- README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/README.md b/README.md index a7eaa63..ea83fff 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,6 @@ SPDX-License-Identifier: Apache-2.0 ![](https://user-images.githubusercontent.com/61068799/231881220-2915f956-dbdb-4eee-8807-4eba9537523f.png) - -[Our wiki](https://github.com/Andrew-Chen-Wang/github-wiki-action/wiki) -| [Projects that use this](https://github.com/Andrew-Chen-Wang/github-wiki-action/network/dependents) -| [v4 release notes](https://github.com/Andrew-Chen-Wang/github-wiki-action/releases/tag/v4.0.0) - 📂 Keep your dev docs in sync with your code \ From 190d9e7f6b1759bceef81740102c97e1035fe942 Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Sat, 15 Jul 2023 23:40:24 -0500 Subject: [PATCH 3/3] fix concurrency --- .github/workflows/test-action.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test-action.yml b/.github/workflows/test-action.yml index aadafbb..ce0cee9 100644 --- a/.github/workflows/test-action.yml +++ b/.github/workflows/test-action.yml @@ -17,7 +17,7 @@ on: - README.md - .github/** - "!.github/workflows/test-action.yml" -concurrency: ${{ github.workflow }}-${{ github.ref_name }} +concurrency: ${{ github.workflow }} jobs: test-action: permissions: