The following are from a braindump I did for my teamn (everything here is public knowledge):
Getting Setup to Building and Developing with the Workflows
This section outlines setting up your development environment for working with workflows:
- Download the Visual Code. This tool is best to sit outside of your environment.
- Click Extensions > Search for PowerShell and install the PowerShell. This feature will also install PowerShell local to your system. PowerShell is used in the Windows workflow.
- Install ShellCheck. This feature is used to check your code and make sure you are following best practices when generating the shell scripts.
- Add an alias to your terminal settings:
alias code=’/Applications/Visual\ Studio\ Code.app/Contents/Resources/app/bin/code’
For me, this is in the .zshrc file.
You’ll also need access to:
- Bash shell
- git tools
Debugging GitHub Actions
If the GitHub Action fails, you should check the following:
- Review the PR Workflow
- Click on Details
- Select the Job that is failing
- Click on the Settings > View raw logs
- Navigate down to the end of the file to the BUILD FAILURE
- Scroll up from the BUILD FAILURE point (at least in Maven)
- Look for the failing tests
- If there are not enough details, go back to Step (b)
- Click on Summary
- Scroll down to Artifacts
- Download the Artifacts related to the build. These files are kept for 90 days or until we hit a storage limit. Note, we purposefully use the upload-artifacts step.
- Extract the files and you should have the Docker Console log file, test results any other workflow logging.
- IBM/FHIR Repository Actions – You can filter through list of Actions.
- You can filter on the failing workflows and get a good big picture.
- GitHub Status – You should subscribe to the site’s updates (via email). This is going to be very helpful to figure out what’s going on with GitHub. You should also check this when the transient errors appear systemic or non-deterministic – e.g. not failing in the same spot. At least one person on the team should sign up for the GitHub Status.
- GitHub Community: Actions – I rarely go here, but sometimes I find that someone has posted with the same question, it may have an answer. Very rarely, I post directly there.
If you encounter anything that looks transient – e.g., network download (Wagon Failure), disk space, filesystem failure – you can choose to rerun the failing workflow.
- Navigate to the failing Job-Workflow
- Click Re-run all jobs
- Repeat for all Workflows that failed
If you see a failure in a particular GitHub Step, such as actions/checkout or actions/setup-java, you should go search that actions issues:
- If actions/setup-java is failing, navigate to https://github.com/actions/setup-java
- Check the Issues (Search for the issue)
- Search for settings that may help
Note, sometimes they intentionally fail a GitHub Action workflow to signal that you should upgrade or change.
How to do Local Development with GitHub Actions
- Navigate to https://github.com/ibm/fhir
- Click Fork
- If a Fork already exists, be sure to Fetch Upstream > Fetch and Merge
- Click Pull Requests and Create the ci-skip label
- Click Labels
- Click New Label
- Click Create label
- Clone the fork – git clone https://github.com/prb112/FHIR.git
- I typically create a local folder called prb112 then clone into it.
- Once the main branch is active, git checkout -b new-ci
- Open your code using your alias: code ~/dev/fhir
- You’ll see:
- Edit your automation files in .github and build
- Click Terminal > New Terminal
- Update the .github/workflows/<file> you are changing so the job.<workflow_job>.if condition is invalid:
if: “!contains(github.event.pull_request.labels.*.name, ‘ci-skip’)”
I change ci-skip to ci-skip-ignore so that I can run just that one targeted workflow.
- Test the steps locally by executing the steps in the workflow line-by-line in the terminal session.
- Once you are comfortable with the changes:
- git add <files>
- git commit -s -m “My edits for issue #2102010”
- Push your new branch – git push -u origin new-ci
- Create your new Pull Request targeting the IBM:fhir main branch and add ci-skip.
The targeted workflow you are building with is the only one that runs. Note, you have a LIMITED number of execution minutes for GitHub Workflows.
Finding GitHub Actions to use/tips in Use
There are many folks using GitHub Actions, and many have figured out better patterns (or evolved to have better patterns).
- Go here – https://github.com/actions/
- Search: <my query> file:yml site:github.com
Each workflow runs in a hosted-runner (or virtual-environment). These hosted-runners are containers specified declaratively in the workflow:
These hosted-runners have a number of pre-installed libraries and tools – Docker, podman, java-11, jq, perl, python, yarn et cetra.
These workflows (except the site, javadocs and release) follow a similar pattern:
- Setup Prerequisites
- Run the Pre-integration Steps
- Execute the Tests
- Run the Post Integration Steps
- Archive the Results
This pattern evolved from build.yml and integration.yml as the starting point all the way to the most recent migration.yaml. Migration.yml is the most sophisticated workflow-jobs that are created.