tachybase/git-auto-commit-action
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README with instructions and limitations

Browse Source 
Closes #69
This commit is contained in:
Stefan Zweifel 2020-05-01 12:56:23 +02:00
parent 2f5e73df85
commit e02ededdeb
1 changed files with 31 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
README.md
View File

@ -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 <actions@github.com>" and the default author of the commit is "Your GitHub Username <github_username@users.noreply.github.com>".
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 <actions@github.com>
# 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.