How to Trigger GitHub Actions on Submodule Updates
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
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:
|
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.
- You will need to change the
PARENT_REPOSITORYto point to your parent repository. - Next you can specify which branch you want to check out on the parent
REPOSITORY. - After that, you can choose which branch on the parent repository you would like to create a pull request against.
- Last but not least, we need to update the
OWNERfield.
- You will need to change the
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