diff --git a/README.md b/README.md index e3869db..45b5ec8 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,14 @@ Github Page Overwriter ====================== -A Github Action that overwrites your Github Pages branch with the content of current workdir, thus deploy/publish without polluting your repo history. +This is a Github Action that overwrites your Github Pages branch with the content of current workdir, thus deploy/publish without polluting your repo history. + +* This is a [summary of what `Github Page Overwriter` is](#what-is-it) +* If you can't wait to get started, this is the [tutorial](#how-to-use-it) +* This is an in-depth description on + [how this `Github Page Overwriter` tool work (differently)](#how-does-it-work) +* If you are still skeptical, this is our answer to + ["why yet another Github Page publish action"](#but-why). What is it? @@ -11,10 +18,10 @@ Github Page Overwriter is: * the **simplest** possible Github Page publisher, because it requires no configuration * the **most lightweight** Github Page publisher - (therefore the **fastest** possible - typically around 2 seconds), because its implementation requires no runtime dependency other than git itself. * the **cleanest** possible Github Page publisher, - because it is designed to leave no extra commits in your repo history. + because it is designed to leave no extra commits in your repo history + (its deployment branch would be overwritten each time). How to use it? @@ -30,7 +37,7 @@ How to use it? push: branches: # NOTE: You may want to limit the trigger branch to be "main" or "master" etc. - - * + - '*' jobs: publish: @@ -121,3 +128,56 @@ thus won't become part of your repo's long term history. D---E---F---G---H main ``` + +But why? +-------- + +Why yet another new Github Pages deployment tool? What is its uniqueness? + +I did look around. But the following reasons made me start this `Github Pages Overwriter` project. + +1. The What (What it does, or does not do) + + I prefer a git tenet of never store build artifacts inside a repo + (at least not store as part of the permanent history). + Some existing github actions possibly also satisfy that, + but none of them explicitly promises such behavior in their contract (i.e. their doc). + + In this project, not only it is named “Github Page OVERWRITER” + which hints that the generated content would be ephemeral and overwritten in next deployment; + it also documented such commitment in its [“how does it work” section](#how-does-it-work). + + In order to examine whether an existing Github Pages deployment action satisfies the aforementioned tenet, + I’d need to look into their implementation. + But, many of them turn out to be implemented by one programming language or another, + running in some sort of container/runner. + I certainly do not know all existing languages, + so I cannot easily review any given 3rd-party github action. + This brings me to my next point. + + +2. The How (How it is implemented) + + To satisfy tenet in #1, one only needs to run several git commands in the right way, + without much external dependency. + Feel free to look into the “Github Page Overwritter” source code to see + how it only uses git command line tool to achieve that. + Personally, it took me less time to write a new action to do what I want, + then to sieve through existing actions to see whether one of them happens to suit my need. + +3. The Security. + + Any 3rd-party github action could potentially mess up with your central repo. + [Security concern on github action is a real thing](https://github.community/t/are-github-actions-safe-to-use/17895). + The only way to be sure, is to review their implementation. + This is another reason why “#2 how it is implemented” is important. + I feel more comfortable to trust an action that I can fully understand what it works. + So should you. + +4. The Simplicity. + + Based on #1 and #2, there is really not much to configure. + A simpler configuration means easier to get started. + + For example, Github Page Ovewriter does not require any github token to be configured. + diff --git a/action.yml b/action.yml index c16b075..177bd07 100644 --- a/action.yml +++ b/action.yml @@ -49,10 +49,10 @@ runs: # But that seems like an overkill. So, we'd use "if" in bash instead. run: > # https://yaml-multiline.info/ if [ "${{ inputs.source-directory }}" == "." ]; then - git push -f origin HEAD:${{ inputs.target-branch }} + git push -f origin HEAD:refs/heads/${{ inputs.target-branch }} else # Inspired from https://gist.github.com/cobyism/4730490#gistcomment-1374989 - git push -f origin `git subtree split -P ${{ inputs.source-directory }}`:${{ inputs.target-branch }} + git push -f origin `git subtree split -P ${{ inputs.source-directory }}`:refs/heads/${{ inputs.target-branch }} fi branding: