How to Trigger GitHub Actions on Submodule Updates

We recently worked with a customer on git submodules who wanted to trigger an ephemeral environment on Releasehub on every submodule update.

Feb 10th, 2022 6:56am by Kevin Luu and Vicky Koblinski

Featued image for: How to Trigger GitHub Actions on Submodule Updates

Feature image via Pixabay

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:

---
name: Submodule Updates
 
#############################
# Start the job on all push #
#############################
on:
  push:
    branches-ignore: [master, main]
  pull_request:
    branches: [master, main]
 
###############
# Set the Job #
###############
jobs:
  build:
    name: Submodule update
    runs-on: ubuntu-latest
    env:
      PARENT_REPOSITORY: 'org/example-repository'
      CHECKOUT_BRANCH: 'main'
      PR_AGAINST_BRANCH: 'main'
      OWNER: 'org'
 
    steps:
      ##########################
      # Checkout the code base #
      ##########################
      - name: Checkout Code
        uses: actions/checkout@v2
 
      ####################################
      # Run the action against code base #
      ####################################
      - name: run action
        id: run_action
        uses: releasehub-com/github-action-create-pr-parent-submodule@v1
        with:
          github_token: ${{ secrets.RELEASE_HUB_SECRET }}
          parent_repository: ${{ env.PARENT_REPOSITORY }}
          checkout_branch: ${{ env.CHECKOUT_BRANCH}}
          pr_against_branch: ${{ env.PR_AGAINST_BRANCH }}
          owner: ${{ env.OWNER }}

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

---

name: Submodule Updates

#############################

# Start the job on all push #

#############################

on:

push:

branches-ignore: [master, main]

pull_request:

branches: [master, main]

###############

# Set the Job #

###############

jobs:

build:

name: Submodule update

runs-on: ubuntu-latest

env:

PARENT_REPOSITORY: 'org/example-repository'

CHECKOUT_BRANCH: 'main'

PR_AGAINST_BRANCH: 'main'

OWNER: 'org'

steps:

##########################

# Checkout the code base #

##########################

- name: Checkout Code

uses: actions/checkout@v2

####################################

# Run the action against code base #

####################################

- name: run action

id: run_action

uses: releasehub-com/github-action-create-pr-parent-submodule@v1

with:

github_token: ${{ secrets.RELEASE_HUB_SECRET }}

parent_repository: ${{ env.PARENT_REPOSITORY }}

checkout_branch: ${{ env.CHECKOUT_BRANCH}}

pr_against_branch: ${{ env.PR_AGAINST_BRANCH }}

owner: ${{ env.OWNER }}

Now, there are a few parameters we can tweak.

First, you can choose how you want the Github Action to be triggered, on push or pull.
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

Kevin is an integration engineer at Release.