autoupdate

autoupdate is a GitHub Action that auto-updates pull requests branches whenever changes land on their destination branch.

Usage

Create a file, in your repository, at .github/workflows/autoupdate.yaml with the following:

name: autoupdate
on:
  # This will trigger on all pushes to all branches.
  push: {}
  # Alternatively, you can only trigger if commits are pushed to certain branches, e.g.:
  # push:
  #   branches:
  #     - master
  #     - unstable
jobs:
  autoupdate:
    name: autoupdate
    runs-on: ubuntu-22.04
    steps:
      - uses: docker://chinthakagodawita/autoupdate-action:v1
        env:
          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'

This will trigger on all pushes and automatically update any pull requests, if changes are pushed to their destination branch.

For more information on customising event triggers, see Github's documentation.

The following events are supported:

• push
• pull_request
• workflow_run
• workflow_dispatch
• schedule

Configuration

The following configuration options are supported. To change any of these, simply specify it as an env value in your workflow file.

All configuration values, except GITHUB_TOKEN, are optional.

• GITHUB_TOKEN: autoupdate uses this token to perform its operations on your repository. This should generally be set to "${{ secrets.GITHUB_TOKEN }}".

  You may want to override this if you want the action to run as a different user than the default actions bot.

• DRY_RUN: Enables 'dry run' mode, possible values are "true" or "false" (default).

  In dry run mode, merge/update operations are logged to the console but not performed. This can be useful if you're testing this action or testing a particular configuration value.

• PR_FILTER: Controls how autoupdate chooses which pull requests to operate on. Possible values are:

  • "all" (default): No filter, autoupdate will monitor and update all pull requests.
  • "labelled": Only monitor PRs with a particular label (or set of labels). Requires the PR_LABELS option to be defined to. If PR_LABELS is not defined, autoupdate will not monitor any pull requests.
  • "protected": Only monitor PRs that are raised against protected branches.
  • "auto_merge": Only monitor PRs that have 'auto merge' enabled

• PR_LABELS: Controls which labels autoupdate will look for when monitoring PRs. Only used if PR_FILTER="labelled". This can be either a single label or a comma-separated list of labels.

• PR_READY_STATE: Controls how autoupdate monitors pull requests based on their current draft / ready for review state. Possible values are:

  • "all": (default): No filter, autoupdate will monitor and update pull requests regardless of ready state.
  • "ready_for_review": Only monitor PRs that are not currently in the draft state.
  • "draft": Only monitor PRs that are currently in the draft state.

• EXCLUDED_LABELS: Controls which labels autoupdate will ignore when evaluating otherwise-included PRs. This option works with all PR_FILTER options and can be either a single label or a comma-separated list of labels.

• MERGE_MSG: A custom message to use when creating the merge commit from the destination branch to your pull request's branch.

• RETRY_COUNT: The number of times a branch update should be attempted before autoupdate gives up (default: "5").

• RETRY_SLEEP: The amount of time (in milliseconds) that autoupdate should wait between branch update attempts (default: "300").

• MERGE_CONFLICT_ACTION: Controls how autoupdate handles a merge conflict when updating a PR. Possible values are:

  • "fail" (default): autoupdate will report a failure on each PR that has a merge conflict.
  • "ignore": autoupdate will silently ignore merge conflicts.

Here's an example workflow file with all of the above options specified:

name: autoupdate
on:
  push: {}
jobs:
  autoupdate:
    name: autoupdate
    runs-on: ubuntu-22.04
    steps:
      - uses: docker://chinthakagodawita/autoupdate-action:v1
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
          DRY_RUN: "false"
          PR_FILTER: "labelled"
          PR_LABELS: "autoupdate,keep up-to-date,integration"
          EXCLUDED_LABELS: "dependencies,wontfix"
          MERGE_MSG: "Branch was auto-updated."
          RETRY_COUNT: "5"
          RETRY_SLEEP: "300"
          MERGE_CONFLICT_ACTION: "fail"

Outputs

Name	Description
conflicted	true or false which indicates whether merge conflicts were found or not

Here's an example workflow file with the outputs above:

name: autoupdate
on:
  push: {}
jobs:
  autoupdate:
    name: autoupdate
    runs-on: ubuntu-18.04
    steps:
      - uses: docker://chinthakagodawita/autoupdate-action:v1
        id: autoupdate
        env:
          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
          MERGE_CONFLICT_ACTION: "ignore"

      - run: echo 'Merge conflicts found!'
        if: ${{ steps.autoupdate.outputs.conflicted }}

      - run: echo 'No merge conflicts'
        if: ${{ !steps.autoupdate.outputs.conflicted }}

Examples

See chinthakagodawita/autoupdate-test/pulls for a repository where autoupdate is enabled. This is currently configured to only run on PRs that have the autoupdate tag added to them.

Here's a screenshot:

Limitations

• Branch updates events caused by this action will not trigger any subsequent workflows
  • This is a documented limitation for all GH actions:

    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.

  • There is an open issue in the Github community forum tracking this

Coming soon

• Rebase support
• Token support in custom merge messages

Also see

• automerge for automatic merging of PRs
• autosquash for auto-merging with squash support