git-auto-commit-action/README.md

git-auto-commit Action

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".

This Action has been inspired and adapted from the auto-commit-Action of the Canadian Digital Service and this commit-Action by Eric Johnson.

Usage

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.

- uses: stefanzweifel/git-auto-commit-action@v4.1.6
  with:
    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.
    # Also required for almost all other events (eg. `schedule`)
    branch: ${{ github.head_ref }}

    # Optional git params
    commit_options: '--no-verify --signoff'

    # Optional glob pattern of files which should be added to the commit
    file_pattern: src/*.js tests/*.js

    # Optional local file path to the repository
    repository: .

    # Optional commit user and author settings
    commit_user_name: My GitHub Actions Bot
    commit_user_email: my-github-actions-bot@example.org
    commit_author: Author <actions@github.com>

    # Optional tag message. 
    # Action will create and push a new tag to the remote repository and the defined branch
    tagging_message: 'v1.0.0'

The Action will only commit files back, if changes are available. The resulting commit will not trigger another GitHub Actions Workflow run!

We recommend to use this Action in Workflows, which listen to the pull_request event. You can then use the option branch: ${{ github.head_ref }} to set up the branch name correctly. If you don't pass a branch name, the Action will try to push the commit to a branch with the same name, as with which the repo has been checked out.

Example Usage

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, 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: Listen to pull_request event

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.

name: php-cs-fixer

on: pull_request

jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
      with:
        ref: ${{ github.head_ref }}

    - name: Run php-cs-fixer
      uses: docker://oskarstark/php-cs-fixer-ga

    - uses: stefanzweifel/git-auto-commit-action@v4.1.6
      with:
        commit_message: Apply php-cs-fixer changes
        branch: ${{ github.head_ref }}

Example: Listen to push event

name: php-cs-fixer

on: push

jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2

    - name: Run php-cs-fixer
      uses: docker://oskarstark/php-cs-fixer-ga

    - uses: stefanzweifel/git-auto-commit-action@v4.1.6
      with:
        commit_message: Apply php-cs-fixer changes

Inputs

Checkout action.yml for a full list of supported inputs.

Outputs

You can use these outputs to trigger other Actions in your Workflow run based on the result of git-auto-commit-action.

• changes_detected: Returns either "true" or "false" if the repository was dirty and files have changed.

Troubleshooting

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. (Updating the token value with a Personal Access Token should fix your issues)

Commit of this Action does not trigger a new Workflow run

As mentioned in the Usage section, the commit created by this Action will not trigger a new Workflow run automatically.

This is due to limitations set up by GitHub:

An action in a workflow run can't trigger a new workflow run. For example, if an action pushes code using the repository's GITHUB_TOKEN, a new workflow will not run even when the repository contains a workflow configured to run when push events occur. Source

You can change this by creating a new Personal Access Token (PAT), storing the token as a secret in your repository and then passing the new token to the actions/checkout Action.

Example Workflow

name: php-cs-fixer

on: push

jobs:
  php-cs-fixer:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
      with:
        token: ${{ secrets.PAT_TOKEN }}

    - name: Run php-cs-fixer
      uses: docker://oskarstark/php-cs-fixer-ga

    - uses: stefanzweifel/git-auto-commit-action@v4.1.6
      with:
        commit_message: Apply php-cs-fixer changes

Known Issues & Limitations

• GitHub currently prohibits Actions like this to push changes from a fork to the upstream repository. See issue #25 for more information.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.