docs: enhance explanation for EXTERNAL_REPOSITORY

* fix: avoid #29
* docs: update TOC
* docs: update tag to v2.4.0

.github/workflows/docker-image-ci.yml

@@ -1,12 +1,9 @@
 name: docker image ci
 
 on:
+  pull_request:
+    types: [opened, synchronize]
   push:
-    paths:
-    - '**'
-    - '!LICENSE'
-    - '!README.md'
-    - '!images'
 
 jobs:
   test:
@@ -14,6 +11,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@master
+      with:
+        fetch-depth: 1
 
     - name: build
       env:
@@ -26,6 +25,8 @@ jobs:
     runs-on: ubuntu-18.04
     steps:
     - uses: actions/checkout@master
+      with:
+        fetch-depth: 1
     - name: shellcheck
       run: shellcheck ./entrypoint.sh
 
@@ -33,6 +34,8 @@ jobs:
     runs-on: macOS-10.14
     steps:
     - uses: actions/checkout@master
+      with:
+        fetch-depth: 1
     - name: hadolint
       run: |
         brew install hadolint

README.md

@@ -28,6 +28,8 @@ Table of Contents
     - [⭐️ `PERSONAL_TOKEN`](#%EF%B8%8F-personal_token)
     - [⭐️ `GITHUB_TOKEN`](#%EF%B8%8F-github_token)
     - [⭐️ Suppressing empty commits](#%EF%B8%8F-suppressing-empty-commits)
+    - [⭐️ Keeping existing files](#%EF%B8%8F-keeping-existing-files)
+    - [⭐️ Deploy to external repository](#%EF%B8%8F-deploy-to-external-repository)
 - [Tips and FAQ](#tips-and-faq)
   - [How to add `CNAME`](#how-to-add-cname)
   - [Deployment completed but you cannot read](#deployment-completed-but-you-cannot-read)
@@ -96,17 +98,19 @@ jobs:
     runs-on: ubuntu-18.04
     steps:
     - uses: actions/checkout@master
+      # with:
+      #   submodules: true
 
     - name: Setup Hugo
-      uses: peaceiris/actions-hugo@v2.2.0
+      uses: peaceiris/actions-hugo@v2.2.1
       with:
-        hugo-version: '0.58.2'
+        hugo-version: '0.58.3'
 
     - name: Build
       run: hugo --gc --minify --cleanDestinationDir
 
     - name: Deploy
-      uses: peaceiris/actions-gh-pages@v2.3.1
+      uses: peaceiris/actions-gh-pages@v2.4.0
       env:
         ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
         PUBLISH_BRANCH: gh-pages
@@ -150,8 +154,8 @@ You can pull a public docker image from Docker Hub.
 By pulling docker images, you can reduce the overall execution time of your workflow. In addition, `latest` tag is provided.
 
 ```diff
-- uses: peaceiris/actions-gh-pages@v2.3.1
-+ uses: docker://peaceiris/gh-pages:v2.3.1
+- uses: peaceiris/actions-gh-pages@v2.4.0
++ uses: docker://peaceiris/gh-pages:v2.4.0
 ```
 
 - [peaceiris/gh-pages - Docker Hub](https://hub.docker.com/r/peaceiris/gh-pages)
@@ -187,8 +191,8 @@ By default, a commit will always be generated and pushed to the `PUBLISH_BRANCH`
 For example:
 
 ```yaml
-- name: deploy
-  uses: peaceiris/actions-gh-pages@v2.3.1
+- name: Deploy
+  uses: peaceiris/actions-gh-pages@v2.4.0
   env:
     ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
     PUBLISH_BRANCH: gh-pages
@@ -197,6 +201,44 @@ For example:
     emptyCommits: false
 ```
 
+#### ⭐️ Keeping existing files
+
+By default, existing files in the publish branch are removed before adding the ones from publish dir. If you want the action to add new files but leave existing ones untouched, set the optional parameter `keepFiles` to `true`.
+
+For example:
+
+```yaml
+- name: Deploy
+  uses: peaceiris/actions-gh-pages@v2.4.0
+  env:
+    ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+    PUBLISH_BRANCH: gh-pages
+    PUBLISH_DIR: ./public
+  with:
+    keepFiles: true
+```
+
+#### ⭐️ Deploy to external repository
+
+By default, your files are published to the repository which is running this action. If you want to publish to another repository on GitHub, set the environment variable `EXTERNAL_REPOSITORY` to `<username>/<external-repository>`.
+
+For example:
+
+```yaml
+- name: Deploy
+  uses: peaceiris/actions-gh-pages@v2.4.0
+  env:
+    ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
+    EXTERNAL_REPOSITORY: username/username.github.io
+    PUBLISH_BRANCH: master
+    PUBLISH_DIR: ./public
+```
+
+You can use `ACTIONS_DEPLOY_KEY` or `PERSONAL_TOKEN`. When you use `ACTIONS_DEPLOY_KEY`, set your private key to the repository which includes this action and set your public key to your external repository.
+
+Be careful, `GITHUB_TOKEN` has no permission to access to external repositories.
+
+
 
 ## Tips and FAQ
 
@@ -260,7 +302,7 @@ jobs:
         npm run build
 
     - name: deploy
-      uses: peaceiris/actions-gh-pages@v2.3.1
+      uses: peaceiris/actions-gh-pages@v2.4.0
       env:
         ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
         PUBLISH_BRANCH: gh-pages
@@ -308,7 +350,7 @@ jobs:
       run: npm run build
 
     - name: deploy
-      uses: peaceiris/actions-gh-pages@v2.3.1
+      uses: peaceiris/actions-gh-pages@v2.4.0
       env:
         ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
         PUBLISH_BRANCH: gh-pages
@@ -358,7 +400,7 @@ jobs:
       run: touch ./out/.nojekyll
 
     - name: deploy
-      uses: peaceiris/actions-gh-pages@v2.3.1
+      uses: peaceiris/actions-gh-pages@v2.4.0
       env:
         ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
         PUBLISH_BRANCH: gh-pages
@@ -405,7 +447,7 @@ jobs:
       run: npm run generate
 
     - name: deploy
-      uses: peaceiris/actions-gh-pages@v2.3.1
+      uses: peaceiris/actions-gh-pages@v2.4.0
       env:
         ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
         PUBLISH_BRANCH: gh-pages
@@ -453,7 +495,7 @@ jobs:
       run: mkdocs build
 
     - name: Deploy
-      uses: peaceiris/actions-gh-pages@v2.3.1
+      uses: peaceiris/actions-gh-pages@v2.4.0
       env:
         ACTIONS_DEPLOY_KEY: ${{ secrets.ACTIONS_DEPLOY_KEY }}
         PUBLISH_BRANCH: gh-pages

action.yml

@@ -12,3 +12,7 @@ inputs:
     description: 'If empty commits should be made to the publication branch'
     required: false
     default: 'true'
+  keepFiles:
+    description: 'If existing files in the publish branch should be not removed before deploying'
+    required: false
+    default: 'false'

entrypoint.sh

@@ -11,7 +11,19 @@ function print_info() {
     echo -e "\e[36mINFO: ${1}\e[m"
 }
 
+function skip() {
+    print_info "No changes detected, skipping deployment"
+    exit 0
+}
+
 # check values
+if [ -n "${EXTERNAL_REPOSITORY}" ]; then
+    PUBLISH_REPOSITORY=${EXTERNAL_REPOSITORY}
+else
+    PUBLISH_REPOSITORY=${GITHUB_REPOSITORY}
+fi
+print_info "Deploy to ${PUBLISH_REPOSITORY}"
+
 if [ -n "${ACTIONS_DEPLOY_KEY}" ]; then
 
     print_info "setup with ACTIONS_DEPLOY_KEY"
@@ -21,19 +33,25 @@ if [ -n "${ACTIONS_DEPLOY_KEY}" ]; then
     echo "${ACTIONS_DEPLOY_KEY}" > /root/.ssh/id_rsa
     chmod 400 /root/.ssh/id_rsa
 
-    remote_repo="git@github.com:${GITHUB_REPOSITORY}.git"
+    remote_repo="git@github.com:${PUBLISH_REPOSITORY}.git"
 
 elif [ -n "${PERSONAL_TOKEN}" ]; then
 
     print_info "setup with PERSONAL_TOKEN"
 
-    remote_repo="https://x-access-token:${PERSONAL_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+    remote_repo="https://x-access-token:${PERSONAL_TOKEN}@github.com/${PUBLISH_REPOSITORY}.git"
 
 elif [ -n "${GITHUB_TOKEN}" ]; then
 
     print_info "setup with GITHUB_TOKEN"
+    print_error "Do not use GITHUB_TOKEN, See #9"
 
-    remote_repo="https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+    if [ -n "${EXTERNAL_REPOSITORY}" ]; then
+        print_error "can not use GITHUB_TOKEN to deploy to a external repository"
+        exit 1
+    fi
+
+    remote_repo="https://x-access-token:${GITHUB_TOKEN}@github.com/${PUBLISH_REPOSITORY}.git"
 
 else
     print_error "not found ACTIONS_DEPLOY_KEY, PERSONAL_TOKEN, or GITHUB_TOKEN"
@@ -55,7 +73,13 @@ remote_branch="${PUBLISH_BRANCH}"
 local_dir="${HOME}/$(tr -cd 'a-f0-9' < /dev/urandom | head -c 32)"
 if git clone --depth=1 --single-branch --branch "${remote_branch}" "${remote_repo}" "${local_dir}"; then
     cd "${local_dir}"
-    git rm -r --ignore-unmatch '*'
+
+    if [[ ${INPUT_KEEPFILES} == "true" ]]; then
+        print_info "Keeping existing files: ${INPUT_KEEPFILES}"
+    else
+        git rm -r --ignore-unmatch '*'
+    fi
+
     find "${GITHUB_WORKSPACE}/${PUBLISH_DIR}" -maxdepth 1 | \
         tail -n +2 | \
         xargs -I % cp -rf % "${local_dir}/"
@@ -74,12 +98,10 @@ git add --all
 
 print_info "Allowing empty commits: ${INPUT_EMPTYCOMMITS}"
 COMMIT_MESSAGE="Automated deployment: $(date -u) ${GITHUB_SHA}"
-if [[ ${INPUT_EMPTYCOMMITS} == "true" ]]; then
-    git commit --allow-empty -m "${COMMIT_MESSAGE}"
+if [[ ${INPUT_EMPTYCOMMITS} == "false" ]]; then
+    git commit -m "${COMMIT_MESSAGE}" || skip
 else
-    git commit -m "${COMMIT_MESSAGE}" || \
-        print_info "No changes detected, skipping deployment" && \
-        exit 0
+    git commit --allow-empty -m "${COMMIT_MESSAGE}"
 fi
 
 git push origin "${remote_branch}"