Open Source / Software Development / Technology / Tools / Sponsored / Contributed

How to Trigger GitHub Actions on Submodule Updates

10 Feb 2022 6:56am, by and

Kevin Luu
Kevin is an integration engineer at Release.

Here at Release, we power release automation with ephemeral environments.

We recently worked with a customer that leverages git submodules and requested our assistance in triggering an ephemeral environment on ReleaseHub on every submodule update.

If you do not know what submodules are and are curious, you can find more information here.

Customer Scenario

Vicky Koblinski
Vicky is a founding engineer at Release.

The customer has a GitHub repository, which we will refer to as the parent repository, that uses a couple of dependent submodules.

These submodules are stored in a .gitmodules file.

The customer wanted a custom GitHub Action to trigger whenever any of the submodules are updated to create a new branch on the parent repository, create a pull request against the master branch, thus spinning up a new ephemeral environment to test and validate the new changes.

How to Use Submodules in GitHub Actions

You can find our GitHub Action published on the GitHub Actions Marketplace here.

Assuming that you already have git submodules configured and functioning in a GitHub repository, to use the GitHub Action, we must first create a GitHub token that has access to read/write to the parent repository and store it in secrets as RELEASE_HUB_SECRET.

If you need assistance creating a GitHub token, you can view the documentation here: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token

For storing secrets, you can view the documentation here: https://docs.github.com/en/actions/security-guides/encrypted-secrets

Next, you must create a new file in .github/workflows/submodule-update.yml and paste the follow code:

Now, there are a few parameters we can tweak.

  1. First, you can choose how you want the Github Action to be triggered, on push or pull.
  2. Next are the environment variables as seen in the env block.
    1. You will need to change the PARENT_REPOSITORY to point to your parent repository.
    2. Next you can specify which branch you want to check out on the parent REPOSITORY.
    3. After that, you can choose which branch on the parent repository you would like to create a pull request against.
    4. Last but not least, we need to update the OWNER field.

Now you should be able to commit and push your changes and watch the GitHub Action trigger according to the way you configured it to.

Customizing This to Your Workflow

Here’s a link to the GitHub repository: https://github.com/releasehub-com/github-action-create-pr-parent-submodule

Here’s a link to the GitHub marketplace: https://github.com/marketplace/actions/github-action-submodule-updates

Feature image via Pixabay