From e02ededdeb8f0d2c80abec4fc0a0d3193d66429c Mon Sep 17 00:00:00 2001 From: Stefan Zweifel Date: Fri, 1 May 2020 12:56:23 +0200 Subject: [PATCH] Update README with instructions and limitations Closes #69 --- README.md | 48 +++++++++++++++++++++++++++++++----------------- 1 file changed, 31 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index eb8a7ca..f7be455 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,19 @@ -# git-auto-commit-action +# git-auto-commit Action -This GitHub Action automatically commits files which have been changed during a Workflow run and pushes the commit back to GitHub. +> The GitHub Action for commiting files for the 80% use case. + +This GitHub Action automatically commits files which have been changed during a Workflow run and pushes the commit back to GitHub. The default committer is "GitHub Actions " and the default author of the commit is "Your GitHub Username ". -If no changes are detected, the Action does nothing. - This Action has been inspired and adapted from the [auto-commit](https://github.com/cds-snc/github-actions/tree/master/auto-commit )-Action of the Canadian Digital Service and this [commit](https://github.com/elstudio/actions-js-build/blob/41d604d6e73d632e22eac40df8cc69b5added04b/commit/entrypoint.sh)-Action by Eric Johnson. -*This Action currently can't be used in conjunction with pull requests of forks. See [issue #25](https://github.com/stefanzweifel/git-auto-commit-action/issues/25) for more information.* - ## Usage -**Note:** This Action requires that you use `action/checkout@v2` or above to checkout your repository. +Please note that this Action requires you to use `action/checkout@v2` or later versions to checkout the repository. + +There are currently no restrictions on the events for which this Action can be used. +The default settings are optimized for the `push` and `pull_request`. For other events, we highly recommend adding the `branch`-option to your workflow. Explicitly telling the Action which branch should be used solves most of the common problems. Add the following step at the end of your job. @@ -22,7 +23,8 @@ Add the following step at the end of your job. commit_message: Apply automatic changes # Optional name of the branch the commit should be pushed to - # Required if Action is used in Workflow listening to the `pull_request` event + # Required if Action is used in Workflow listening to the `pull_request` event. + # Also required for almost all other events (eg. `schedule`) branch: ${{ github.head_ref }} # Optional git params @@ -39,7 +41,8 @@ Add the following step at the end of your job. commit_user_email: my-github-actions-bot@example.org commit_author: Author - # Optional tag message. Will create and push a new tag to the remote repository + # Optional tag message. + # Action will create and push a new tag to the remote repository and the defined branch tagging_message: 'v1.0.0' ``` @@ -50,14 +53,17 @@ If you don't pass a branch name, the Action will try to push the commit to a bra ## Example Usage -This Action will only work, if the job in your Workflow changes files. -The most common use case for this, is when you're running a Linter or Code-Style fixer on GitHub Actions. +The most common use case for this Action is to create a new build of your project on GitHub Actions and commit the compiled files back to the repository. +Another simple use case is to run a linter and commit the fixes back to the repository. -In this example I'm running `php-cs-fixer` in a PHP project. +In this example, we're running `php-cs-fixer` in a PHP project, let the linter fix possible code issues and commit the changed files back to the repository. -### Example on `pull_request` event +### Example: Listen to `pull_request` event -If you would like to use this Action in a Workflow which listens to the `pull_request` event, you must add the `ref`-input to the `actions/checkout@v2` step. It's also recommended to add the `branch`-input to the `git-auto-commit`-step. This way you tell the Action exactly where to push the commit. +When using the Action while listening to the `pull_request`-event, you must add the `ref`-input to the `actions/checkout@v2` step. +Otherwhise the repository is checked out in a detached state which causes issue with this Action. + +It's also recommended to add the `branch`-input to the `git-auto-commit`-step. This way you tell the Action exactly where to push the commit. ```yaml name: php-cs-fixer @@ -82,7 +88,7 @@ jobs: branch: ${{ github.head_ref }} ``` -### Example on `push` event +### Example: Listen to `push` event ```yaml name: php-cs-fixer @@ -115,7 +121,15 @@ You can use these outputs to trigger other Actions in your Workflow run based on ## Troubleshooting -### Can't push commit to repository +### Action does not push commit to repository +The cloned repository can be in different states depending on the event your Workflow is running on. +If you listen to antother event than `push` or `pull_requests` it is highly recommended to set the `branch`-input. + +This Action does not contain magic and can't easily determine, to which branch a commit should be pushed to. 🔮. +It's much easier if you just define the `branch`-value yourself. + + +### Action does not push commit to repository: Authentication Issue If your Workflow can't push the commit to the repository because of authentication issues, please update your Workflow configuration and usage of [`actions/checkout`](https://github.com/actions/checkout#usage). (Updating the `token` value with a Personal Access Token should fix your issues) ### Commit of this Action does not trigger a new Workflow run @@ -152,7 +166,7 @@ jobs: commit_message: Apply php-cs-fixer changes ``` -## Known Issues +## Known Issues & Limitations - GitHub currently prohibits Actions like this to push changes from a fork to the upstream repository. See [issue #25](https://github.com/stefanzweifel/git-auto-commit-action/issues/25) for more information.