After working extensively to migrate repositories and pipelines from TFS to GitHub, we found that many steps in the pipeline flow involved highly repeated steps across multiple repositories. This is where templates came into play, but we didn’t want to define the same template in each repo, rather store the templates in a centralized repository and call those templates in all of the repositories that require them.
This is where Global GitHub templates come in, as it provides us a way to store our templates in a centralized repository and the ability to call these templates in each repositories pipelines that require them.
Global GitHub templates and reusable workflows
To create a global GitHub template and reusable workflows the following must be done
- Go into your GitHub Organisations repositories and create a new repository e.g. github-workflows
- In this instance we have created a branch as well called v1
- Create a folder called .github
- And in this folder create a folder called template
- Store all your GitHub templates in this folder
- You can also store reusable workflows in the same manner just create a subfolder called workflows in the .github folder and store all your reusable workflows in there
- Now on the top panel of the github-workflows repository click on Settings
- Then on the side panel click on Actions then General
- Scroll to the bottom and on the Access section ensure either one of the following values are checked
- Accessible from repositories in the ‘<Your organization name>’ organization
- Accessible from repositories in the ‘<Your enterprise name>’ enterprise
- Now your templates can be called from other repositories pipelines
- To do this the following format is used in the pipeline
name: Build
uses: "<GitHub Organisation Name>/github-workflows/.github/template/msbuild@v1"
with:
<Parameters defined in template>
- As seen above we are calling the specific github-workflows repository and the specific template msbuild on our v1 branch
- Ensure to replace <GitHub Organisation Name> with the name of your GitHub org so it knows where to find the templates in the github-workflows repository
- Ensure to replace <Parameters defined in template> with the parameters you defined in your templates and the values associated with those parameters
- You can also call the reusable workflow with the following format
deploy-to-dev:
needs: build
uses: <GitHub Organisation Name>/github-workflows/.github/workflows/deploy-dev.yml@v1
secrets: inherit
with:
<Parameters defined in template>
- As seen above we are calling the specific github-workflows repository and the specific reusable workflow deploy-dev.yml on our v1 branch
- Ensure to replace <GitHub Organisation Name> with the name of your GitHub org so it knows where to find the reusable template in the github-workflows repository
- Ensure to replace <Parameters defined in template> with the parameters you defined in your reusable workflow and the values associated with those parameters
- Secrets: inherit is used so all secrets defined in the calling pipeline as well as organization or repository secrets are passed into the reusable workflow
Conclusion
In this blog post, we looked at how to configure Global GitHub templates and the advantages it brings in storing templates and reusable workflows in a centralized repository so they can be used across multiple repositories but be managed in one location. Currently this is only supported for Public and Internal repositories. Hopefully you have found this post informative, if you have other GitHub tips and tricks let us know and don’t be afraid to share your thoughts.
Related Links
- https://docs.github.com/en/actions/using-workflows/reusing-workflows
- https://docs.github.com/en/actions/creating-actions/sharing-actions-and-workflows-with-your-organization
- https://docs.github.com/en/actions/creating-actions/sharing-actions-and-workflows-from-your-private-repository
- https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository