Prerequisites
You’ve already created a GitHub repository and maybe have some initial commits but are now wanting to share this with members of your team or the greater GitHub community.
Why
You’d like a level of confidence that the code that’s merged into the main branch is consumable without having to fix build errors. Of course, this process will not guard against logic errors, but this article will also document requiring pull requests (PRs) so that at least one other developer is reviewing commits before merging changes into main.
Steps
The screenshots in this document are from our fhir-link repository. Fhir-link (pronounced “fire link”) is a .net Core 6.0 Azure function that performs an integration between an FHIR Service and Dynamics 365 Customer Insights. You can find the actual code in the repository there. Good documentation from GitHub is also contained in the GitHub Marketplace and GitHub Docs.
Create GitHub Workflow
The steps below reference the callouts in the editor screen shot. Base your work off of the fhir-link example or the code within the GitHub example.
Figure 1: Visual Studio screenshot of yaml file
- Using your editor of choice, create a yaml file and place it in a .github\workflows directory within your repository.
- Name the action
- Target the pull requests of the branch that will act as your main development. This will act as the trigger to the action.
- Complete the env section with pertinent details:
- Configuration: Release
- DOTNET_CORE_VERSION: our repo targets the current LTS version: 6.0
- WORKING_DIRECTORY: we will work from within the default repo directory
- There’s one job: “build-and-test”. It will contain the steps necessary to pull the code, build and run any test assemblies.
- jobs/build-and-test/runs-on: ubuntu-latest
Ubuntu was chosen since it already has the latest .net core libraries which allows it to run more quickly. “windows-latest” is also an option here.
- jobs/build-and-test/steps/uses: actions/checkout@master
This reference’s GitHub’s repository, hence it is GitHub’s nomenclature: “actions/checkout@master” instead of “actions/checkout@main” - this repo’s nomenclature
- jobs/build-and-test/steps/Setup .NET Core
Ready the .NET core environment to be used in the build.
- jobs/build-and-test/steps/Restore
Pull the code from the GitHub repo to the working directory.
- jobs/build-and-test/steps/Build
Compile the code in the working directory using the Release build configuration
- jobs/build-and-test/steps/Test
Inspect the assemblies and run any test methods found.
Branch Security
Once saved in .github\workflows, the action will run automatically when the “on” event occurs – in this case, the pull request. But there’s nothing forcing a PR to wait for it to complete successfully. To fix this we need to configure a GitHub branch protection rule.
Figure 2: GitHub steps to add a branch protection rule
- Navigate to settings
- Branches
- Branch protection rules > Add Rule
Figure 3: Branch protection setting detail
- Select the branches that this rule should cover. This can be one branch like “main” or “master” or can cover any number using a pattern. The pattern uses fnmatch syntax.
- Enable “Require branches to be up to date before merging”
- Find and select the build-and-deploy workflow. Some notes below.
- This is not the name of the workflow (line 1 in above example yaml), but instead it is the name of the job (line 11 in above example yaml).
- The list isn’t populated immediately. Let the workflow run once (See Validate section) and it should become populated in the list.
Other best practice settings for your main development branch include
- Require a pull request before merging
- Require conversation resolution before merging
- Do not allow bypassing the above settings
Validation
Create a PR, you should see the checks initially in yellow, then turn green when complete (assuming success).
Figure 4: Pull Request view while checks are running |
Figure 5: Pull Request view after checks have completed |
Optional Steps
You may have some reusable components in this repository. If so, this action should also package and publish to your package repository. For more detail, see Publishing to package registries in the GitHub Docs.
Depending on your deployment target (Kubernetes, an app service, a function app, etc) in addition to CI, you may also want to configure Continuous Deployment (CD) in your GitHub repository. The concepts are similar. You can see the sample yaml file from our fhir-link repository here, or see detailed documentation in the GitHub Docs.
Conclusion
This was a good review of GitHub actions and branch security. I hope you found value in this write up.
If you’d like to be part of a community of healthcare developers sharing knowledge and resources, check out our HLS Developer discord at https://aka.ms/HLS-Discord. We have links to all our content there and a bunch of channels to communicate with us and likeminded tech and healthcare people.
Hope to see you there!