Update the documentation and the push process (#135)

* doc: Update the documentation and the push process

README.md

@@ -13,7 +13,7 @@ With ease:
 
 ### Example Workflow file
 
-An example workflow to authenticate with GitHub Platform:
+An example workflow to authenticate with GitHub Platform and to push the changes to a specified reference, e.g. an already available branch:
 
 ```yaml
 jobs:
@@ -31,7 +31,7 @@ jobs:
       run: |
         git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
         git config --local user.name "github-actions[bot]"
-        git commit -m "Add changes" -a
+        git commit -a -m "Add changes"
     - name: Push changes
       uses: ad-m/github-push-action@master
       with:
@@ -39,6 +39,31 @@ jobs:
         branch: ${{ github.ref }}
 ```
 
+An example workflow to use the branch parameter to push the changes to a specified branch e.g. a Pull Request branch:
+
+```yaml
+name: Example
+on: [pull_request, pull_request_target]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.head_ref }}
+        fetch-depth: 0
+    - name: Commit files
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        git commit -a -m "Add changes"
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        branch: ${{ github.head_ref }}
+```
+
 An example workflow to use the force-with-lease parameter to force push to a repository:
 
 ```yaml
@@ -47,19 +72,45 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v3
-        with:
-          ref: ${{ github.head_ref }}
-          fetch-depth: 0
+      with:
+        ref: ${{ github.head_ref }}
+        fetch-depth: 0
     - name: Commit files
       run: |
         git config --local user.email "github-actions[bot]@users.noreply.github.com"
         git config --local user.name "github-actions[bot]"
-        git commit -m "Add changes" -a
+        git commit -a -m "Add changes"
     - name: Push changes
       uses: ad-m/github-push-action@master
       with:
         force_with_lease: true
 ```
+
+An example workflow to update/ overwrite an existing tag:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.head_ref }}
+        fetch-depth: 0
+    - name: Commit files
+      run: |
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git config --local user.name "github-actions[bot]"
+        git tag -d $GITHUB_REF_NAME
+        git tag $GITHUB_REF_NAME
+        git commit -a -m "Add changes"
+    - name: Push changes
+      uses: ad-m/github-push-action@master
+      with:
+        force: true
+        tags: true
+```
+
 An example workflow to authenticate with GitHub Platform via Deploy Keys or in general SSH:
 
 ```yaml
@@ -78,11 +129,11 @@ jobs:
       run: |
         git config --local user.email "41898282+github-actions[bot]@users.noreply.github.com"
         git config --local user.name "github-actions[bot]"
-        git commit -m "Add changes" -a
+        git commit -a -m "Add changes"
     - name: Push changes
       uses: ad-m/github-push-action@master
       with:
-      	ssh: true
+        ssh: true
         branch: ${{ github.ref }}
 ```
 
@@ -100,6 +151,26 @@ jobs:
 | directory        | string | '.' | Directory to change to before pushing.                                                                                                                                                                                                                                                                          |
 | repository       | string | '' | Repository name. <br /> Default or empty repository name represents <br /> current github repository. <br /> If you want to push to other repository, <br /> you should make a [personal access token](https://github.com/settings/tokens) <br /> and use it as the `github_token` input.                       |
 
+## Troubeshooting
+
+Please be aware, if your job fails and the corresponding output log looks like the following error, update your used version of the action to `ad-m/github-push-action@master` and check the used version of the `checkout` action (v2 is required):
+```log
+Push to branch ***************
+fatal: unsafe repository ('/github/workspace' is owned by someone else)
+To add an exception for this directory, call:
+
+	git config --global --add safe.directory /github/workspace
+```
+
+If you see the following error inside the output of the job, and you want to update an existing Tag:
+```log
+To https://github.com/Test/test_repository
+ ! [rejected]        0.0.9 -> 0.0.9 (stale info)
+error: failed to push some refs to 'https://github.com/Test/test_repository'
+```
+
+Please use the `force` instead the `force_with_lease` parameter. The update of the tag is with the `--force-with-lease` parameter not possible.
+
 ## License
 
 The Dockerfile and associated scripts and documentation in this project are released under the [MIT License](LICENSE).

start.sh

@@ -46,8 +46,10 @@ else
     remote_repo="${INPUT_GITHUB_URL_PROTOCOL}//${GITHUB_ACTOR}:${INPUT_GITHUB_TOKEN}@${INPUT_GITHUB_URL}/${REPOSITORY}.git"
 fi
 
-if ${INPUT_FORCE_WITH_LEASE}; then
-  git push $_ATOMIC_OPTION --follow-tags $_FORCE_OPTION $_TAGS;
-else
-  git push "${remote_repo}" HEAD:${INPUT_BRANCH} $_ATOMIC_OPTION --verbose --follow-tags $_FORCE_OPTION $_TAGS;
+git config --local --add safe.directory ${INPUT_DIRECTORY}
+
+if ! ${INPUT_FORCE_WITH_LEASE}; then
+  ADDITIONAL_PARAMETERS="${remote_repo} HEAD:${INPUT_BRANCH}"
 fi
+
+git push $ADDITIONAL_PARAMETERS $_ATOMIC_OPTION --follow-tags $_FORCE_OPTION $_TAGS;