GitHub implementation

HeartAI source code, task and project management, and associated processes are administered through the Git version control software and the GitHub software development framework. Git and GitHub are the primary mechanisms to contribute to, manage, and deploy HeartAI. These frameworks provide structured processes for administrators and developers to manage HeartAI, including support for:

  • Software, document, and process version control.
  • Project and product management tooling.
  • Functionalities to package and deploy software for both local and remote environments.
  • Administrator and developer GitHub account management.
  • Utilities for software testing, analysis, and deployment.
  • Knowledge base management including error reporting and reference documentation.

HeartAI repository branches allow different aspects of the repository to be separated and developed independently. Developers will typically work within their own branches, and when a suitable level of development is achieved these branches will be requested to merge with the primary representative branches of the HeartAI source. The following branches implement the primary functionality of HeartAI and are protected by default:

Branch name Description Restrictions Requirements
master Representative branch for HeartAI system deployment Must be merged into from a pull request. Pull request must have at least one administrator review
gh-pages Representative branch for HeartAI website and documentation deployment Must be merged into from a pull request. Pull request must have at least one administrator review

To apply source contribution to these branches, contributors must pull request their branch to merge with one of the corresponding origin branches noted above. Contributions to these branches are governed by an administrative review process as represented with the following figure:

review-process-for-source-contribution.svg

With administrative approval, the contributor’s branch may be merged with the nominated origin branch, and will become part of the representative branches of the HeartAI source. The representative branches, master and gh-pages, trigger downstream deployment behaviour following modification to the origin source. This includes unit and integration testing, publication of representative packages and images, and deployment to HeartAI instances of Red Hat OpenShift and other remote environments.

GitHub Actions process

The HeartAI GitHub repository is integrated with GitHub Actions, providing mechanisms to test and package source software. These actions are typically triggered following commits to origin, with action functionality corresponding to the nature and location of the commit. The following table provides a general overview of GitHub Actions functionality within the HeartAI source repository:

GitHub Action job Function Event trigger
Core service testing Perform integration testing of the service Push to origin/*
Hello world service testing Perform integration testing of the service Push to origin/*
Hello world service publish Build and publish service to Quay image repository Push to origin/master
HIB interface service testing Perform integration testing of the service Push to origin/*
HIB interface service publish Build and publish service to Quay image repository Push to origin/master
HIB FHIR translation service testing Perform integration testing of the service Push to origin/*
RAPIDx AI service testing Perform integration testing of the service Push to origin/*
RAPIDx AI service publish Build and publish service to Quay image repository Push to origin/master

Example: GitHub Actions workflows

The following example components show GitHub Actions workflows for the HeartAI HelloWorldService:

  • Performing integration testing of the service:
name: "Hello world service testing"
on:
  push:
jobs:
  hello-world-service-test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:latest
        env:
          TZ: Australia/Adelaide
          POSTGRES_DB: heartai
          POSTGRES_USER: heartai
          POSTGRES_PASSWORD: heartai
          POSTGRES_ROOT_PASSWORD: heartai_root
        ports:
          - "5432:5432"
        options: >-
          --name heartai-postgres
          --hostname heartai-postgres
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
      keycloak:
        image: quay.io/keycloak/keycloak:16.1.1
        env:
          TZ: Australia/Adelaide
          DB_VENDOR: h2
          KEYCLOAK_USER: heartai
          KEYCLOAK_PASSWORD: heartai
        ports:
          - "9990:8080"
        options: >-
          --name heartai-keycloak
          --hostname heartai-keycloak
    steps:
      - name: "Initialise environment"
        run: sudo chown -R $USER:$USER /home/runner/work/HeartAI
      - name: "Wait for services readiness"
        uses: nev7n/[email protected]
        with:
          url: 'http://localhost:9990/'
          responseCode: 200
          timeout: 60000
          interval: 1000
      - name: "Checkout HeartAI repository"
        uses: actions/[email protected]
      - name: "Setup Keycloak realm"
        run: source $GITHUB_WORKSPACE/deploy/development/keycloak/shell/createDevRealm.sh
      - name: "Setup Scala environment"
        uses: olafurpg/[email protected]
        with:
          java-version: "[email protected]"
      - name: "Use SBT to compile and test Scala"
        run: "sbt -v -Dfile.encoding=UTF-8 helloWorldIMPL/test"
  • Building and publishing the service:
name: "Hello world service publish"
on:
  push:
    branches:
      - master
jobs:
  hello-world-service-publish:
    runs-on: ubuntu-latest
    steps:
      - name: "Login to Quay"
        uses: docker/[email protected]
        with:
          registry: quay.io/heartai
          username: ${{ secrets.QUAY_USERNAME }}
          password: ${{ secrets.QUAY_PASSWORD }}
      - name: "Checkout"
        uses: actions/[email protected]
      - name: "Setup Scala"
        uses: olafurpg/[email protected]
        with:
          java-version: "[email protected]"
      - name: "Publish"
        run: sbt -Ddocker.registry=quay.io/heartai helloWorldIMPL/docker:publish

GitHub UI for repository overview

The following example shows the GitHub web interface for the repository overview. This page provides a high-level overview of the repository, and includes information such as:

  • The repository file structure, with detail about the most recent commit for the directory / file.
  • The rendered GitHub README documentation.
  • Repository metadata, including corresponding website(s) and most recent software version release.
  • Published repository packages.
  • Repository contributors.

Example: GitHub UI for repository overview

github-home.png

GitHub UI for commits

The following example shows the GitHub web interface for a Git commit, representing an incremental change to the repository history. For commits, GitHub provides functionalities such as:

  • Assignment of the commit with a repository Git commit ID as a unique SHA-1 hash of commit information.
  • What changes were made to the repository.
  • Who authored the changes.
  • Functionality and metrics to understand the extent of the changes.

Example: GitHub UI for repository commits

github-commit.png

GitHub UI for pull requests

The following examples show the GitHub web interface for a GitHub pull request, representing a request to merge one repository branch with another. For pull requests, GitHub provides functionalities such as:

  • Request process to submit an incremental update to a primary repository branch.
  • Ability to assign reviewers to review a pull request.
  • Ability to label pull requests, and associate pull requests to GitHub projects and GitHub milestones.
  • Enforcement of repository policies, such as requiring at least one administrator review and approval before accepting a pull request.
  • Integrated testing and event-driven behaviour through GitHub Actions capabilities.

Example: GitHub UI for repository closed pull requests

github-pull-requests.png

Example: GitHub UI for repository pull request

github-pull-request.png

GitHub UI for networks

The following example shows the GitHub web interface for GitHub networks. This graph allows an interactive visualisation of repository development history. The GitHub web interface for networks provides:

  • A scrollable and interactive visualisation of repository development history.
  • Linking of network data points corresponding to a repository Git commit ID.
  • Popup information when interacting with network data points, displaying further information about the corresponding commit.

Example: GitHub UI for repository network

github-network.png

GitHub UI for issues

The following examples show the GitHub web interface for GitHub issues. This page provides functionalities to support project planning, task management, and team management. An issue typically represents a well-defined task or query in relation to the repository, and the issues web interface provides a centralised framework to manage these tasks. For issues, GitHub provides support for:

  • Issue creation with authorship corresponding to the GitHub user account.
  • Functionalities for labeling and tagging issues.
  • Assigning repository members to the issue.
  • Assigning issues to GitHub projects.
  • Assigning issues to GitHub milestones.

Example: GitHub UI for repository open issues

github-issues-open.png

Example: GitHub UI for repository closed issues

github-issues-closed.png

GitHub UI for milestones

The following example shows the GitHub web interface for GitHub milestones. This page provides functionalities to support project planning over larger time epochs. A milestone typically bundles repository issues related to a major platform or project development goal. For milestones, GitHub provides support for:

  • Documenting milestone purposes and goals.
  • Linkage between repository issues and a milestone.
  • Providing an overview of milestone development progress.

Example: GitHub UI for repository milestone open issues

heartai-software-github-milestones.png

GitHub UI for projects

The following example shows the GitHub web interface for GitHub projects, providing Kanban-like functionalities to manage projects and product. For projects, GitHub provides functionalities such as:

  • Project tasks that are linkable to corresponding repository issues, with inheritance of issue features such as web interface interactivity integrations.
  • Inheritance of GitHub issue assignees and labels.
  • Customisable board columns.

Example: GitHub UI for repository project board

github-projects.png

GitHub UI for releases

The following example shows the GitHub web interface for GitHub releases. This feature provides functionalities for tagging, packaging, and delivering repository software. Releases are typically created in relation to a major repository milestone. GitHub releases support:

  • Linking of the release at a point in time of the repository history corresponding to a repository Git commit ID.
  • Tagging the release. GitHub provides additional support for tags that are structured as software versions.
  • The repository source and software may be bundled and downloaded through the release page. Typical bundles are composed as zip and tar.gz files.
  • The release version is displayed on the web interface repository overview.

Example: GitHub UI for repository release

github-releases.png

GitHub UI for GitHub Actions

The following example shows the GitHub web interface for GitHub Actions. This feature allows general event-driven behaviour to occur following interaction with GitHub as a Git commit, such as behaviour driven by a Git push to the GitHub repository, or as part of a GitHub pull request process. These capabilities are backed by Microsoft Azure cloud resources, and include broad access to compute services. This is particularly suitable for performing unit- and integration-testing of repository software and for deployment processing generally. The GitHub Actions web interface provides:

  • An overview of all GitHub Actions workflows and jobs that have been registered with the repository.
  • Linking of the GitHub Actions workflow with a repository Git commit ID.
  • The ability to view the GitHub Actions workflow in real-time, including logging functionality through backing Microsoft Azure cloud resources.

Example: GitHub UI for repository GitHub Actions workflow

github-actions.png