How to automagically open pull requests with GitHub Actions

Whenever you catch yourself in a repetitive task, try this: step back and think about ways you might automate it. One tool CI/CD folks love to use for automation is GitHub Actions.

GitHub Actions are widely used to run tests and perform checks on our code. But what happens when your automation changes the code, and you want to commit those changes? If you're thinking of running the script manually and opening a pull request, this is an option. But here's an even better option: automate the process by using GitHub Actions to open pull requests for you. This article shows you how, step by step.

The scenario

At Aiven, we've got an interesting problem: we keep expanding our list of cloud providers. This is nice because it gives you the flexibility to choose whatever provider works for you. For us, maintainers of dev portal documentation, it's a challenge to ensure that the most up-to-date information about our cloud providers is available for our readers.

You can find a list of Aiven's cloud providers on Docs.aiven.io, which is also the portal where we host the developer documentation. To quickly retrieve a list of currently-available cloud providers, my colleague Lorna Mitchell wrote a Python script that pulls our cloud listing from the Aiven API and generates documentation, which is really cool!

Having the script was great. Now, by running the script, we could quickly generate fresh documentation out of the Aiven API data. This didn't automate the process entirely, though. Getting the changes merged still required a number of manual actions on a regular basis: run the script, check if there are new changes to commit, create pull requests, and so on.

This is a good example of a case where you can configure a GitHub Actions workflow to run the script periodically and open a pull request when changes are detected. So if you have a similar challenge, below you'll find how to add an automation flow step by step.

Configure GitHub Actions workflow

Time for some action - or better, GitHub Actions! You can follow these steps to configure your GitHub Actions workflow:

1) Check the script

Let's ensure that the script works correctly before using it for automation. So, here you can run your script a couple of times and check that it is working as it is supposed to.

To make the process easier, you can add the commands to run the script in a Makefile. Makefiles are a helpful way to organize code compilation, and it helps to run long commands in a shorter version using the make command. Following our example, here is what we add to the Makefile:

SOURCEDIR     = .
# (Re)Generate cloud listing
cloud-list:
    python "$(SOURCEDIR)/scripts/aiven/clouds.py" "includes/clouds-list.rst"
Copy to clipboard

Now we can simply run the script with:

make cloud-list
Copy to clipboard

This step ensures that the script you use to change the code produces the changes you want to commit in a pull request. Mistakes happen. If your script isn't working as expected, you may need to debug your code before proceeding. If the script is working, then you can go ahead and create the GitHub workflow.

2) Create a GitHub workflow

In this step, you need to add a YAML file to define the workflow configuration. First, make sure you have created a .github/workflows/ folder; if not, you can go ahead and create the directory. Then, create a YAML file to define the workflow configuration, for example, .github/workflows/cloud-list.yaml. In this file, you can define the name of the workflow. In our example, we start by giving a name to our workflow:

name: Cloud - Create PR to update available list
Copy to clipboard

Pick a name for a file and for the workflow that is related to the changes you are bringing to your code. This can help your code and to identify your workflows. Check out this quick guide from GitHub in how to create your first workflow.

3) Choose a trigger

GitHub Actions enable you to trigger your workflow to run based on a certain event or events. In the example, the job needs to run periodically. For that, configure it to run on schedule according to a cron job.

The cron syntax can be confusing sometimes. To double-check your cron syntax, you can use an online and free tool called crontab guru. Besides this, the page contains many examples that can help understand the syntax better.

For example, this workflow is configured to run every Tuesday at 6 AM UTC (8 AM CEST) time:

on:
schedule:
    - cron: "0 6 * * 2"
Copy to clipboard

On GitHub Actions, the time is based on UTC, so you may want to consider this during the setup.

Note: On GitHub Actions, the shortest interval you can run scheduled workflows is once every 5 minutes.
If you want to run your job in every pull request or have a different use case, you can check out all the available triggers to run your workflow on the GitHub documentation.

4) Install dependencies and run the script

A GitHub workflow is composed of one or more jobs. A job is a set of steps executed in a certain environment defined on the runs-on. In the example below, the CloudList job runs on the latest ubuntu image. After defining the environment, you need to checkout from a branch, for example the main branch, and decide on the Python version. Finally, you need to add a step to install the dependencies and run your script.

jobs:
CloudList:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout the repo
        uses: actions/checkout@v2
    - name: Set up Python 3.8
        uses: actions/setup-python@v2
        with:
        python-version: "3.8"
    - name: Install dependencies
        run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Update available cloud list
        run: make cloud-list
Copy to clipboard

With this, the job already runs periodically and generates the file. However, the final goal is to open a pull request so maintainers can check the changes and merge the code. So let's see how you can add the pull request step to your workflow.

5) Create pull request

You can create a pull request by using the Create Pull request action in our workflow. A cool feature here is that you can add some customization related to your pull request that can help in the pull request review process, including labels and a defined branch name, for example:

- name: Create Pull Request
uses: peter-evans/create-pull-request@v4
with:
    commit-message: Cloud - Update available list
    title: Cloud - Update available list
    body: Cloud - Update available list
    base: main
    labels: automated-pr, Clouds & Regions
    branch: cloud-update-advanced-params
    delete-branch: true
Copy to clipboard

The workflow runs the specified jobs according to the scheduled time even if the action is not merged.

Besides periodically running a workflow, you can combine it with the option to manually trigger your workflow, which can help you to test it. You can check out this GitHub Actions manual for that.

When the action takes place, this is what the shiny new pull request looks like ✨:

So every week, the workflow runs and keeps our Aiven cloud list always updated for our beloved users. 🧡

Conclusion

As devportal maintainers, we are happy to use GitHub Action in our CI/CD process to keep our Aiven cloud list always up-to-date.

In this article, we reviewed the workflow code one segment at a time. The complete script looks like this:

File: .github/workflows/cloud-list.yaml

name: Cloud - Create PR to update available list
on:
  schedule:
    - cron: "0 6 * * 2"
jobs:
  CloudList:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the repo
        uses: actions/checkout@v2
      - name: Set up Python 3.8
        uses: actions/setup-python@v2
        with:
          python-version: "3.8"
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: Update available cloud list
        run: make cloud-list
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v4
        with:
          commit-message: Cloud - Update available list
          title: Cloud - Update available list
          body: Cloud - Update available list
          base: main
          labels: automated-pr, Clouds & Regions
          branch: cloud-update-advanced-params
          delete-branch: true
Copy to clipboard

Read more

Besides periodically running a workflow, you can also add the option to trigger your workflow manually. You can check out this GitHub Actions manual with all the information.

If what you have in mind for your pull request looks different, you can check out more examples on how to customize the create-pull-request actions to fit your use case.

Here you can find more examples to learn how to use GitHub Actions to open pull requests for you. Have fun automating your pull requests ⚙️!

--

If you have any feedback or questions, hit us up on Twitter or LinkedIn. Make sure you follow our changelog and blog RSS feeds, and if you want the latest news about Aiven and our services - plus a bit extra on all things open source - subscribe to our monthly newsletter!