GitHub Actions workflow example of running Hackolade Studio CLI

For CI/CD scenarios leveraging the Docker image of Hackolade Studio CLI documented here, you may want to leverage the GitHub Actions workflow. This repository is just a simple example. It should serve as an inspiration for users. It is possible to orchestrate a succession of Hackolade Studio CLI commands, combined with Git commands and others to achieve ambitious use cases, all triggered by events in your repository. For example when a PR for a model is merged in to the main branch.

Licensing

Tip

Running Hackolade Studio Docker image on GitHub Actions requires a concurrent License. To purchase a concurrent license subscription, please send an email to sales@hackolade.com.

This repository exposes a workflow example that uses a license managed as a GitHub Actions secret. License keys should be kept secret.

Build your Docker image and push it to Docker Hub

The Dockerfile contained in this repository allows to build an image with the latest release of Hackolade Studio available at the time of build, using the Docker image hackolade/studio

Tip

In order to significantly save bandwidth, it is advised to build the image and push your image to Docker Hub or your own private Container registry of choice.

In the example we have the image studio:latest hosted on Docker Hub with the plugins we want to use.

docker buildx build -t studio:latest --push .

Note

Make sure your compose file is aligned.

Generating documentation with a Docker image built locally and a compose file

To illustrate how to use the Hackolade Studio CLI in GitHub Actions, this repository contains one workflow file.

It uses an example Couchbase model travel.json contained in this repository.

Note

This workflow example uses a manual trigger (e.g. uses workflow_dispatch GHA trigger event). See below for a trigger example.

The workflow file executes the following steps:

1. Validate a concurrent license key (managed as a repository secret)
2. Generate Markdown documentation for the example travel.json model, followed by the forward-engineering of JSON Schema files for each of the entities in the model
3. Gather logs and generated artifacts into GitHub workspace on the runner
4. Open a Pull Request from these artifacts

The workflow and the compose files are aligned and use the following default variables:

• HACKOLADE_STUDIO_CLI_IMAGE defaulting to studio:latest -> the Docker image name for Hackolade Studio CLI.
• REPOSITORY_DIR_IN_CONTAINER defaulting to /github/workspace/repository -> the working directory for the CLI and where the GitHub repository content is mounted.
• OUTPUT_DIR_IN_CONTAINER defaulting to /home/hackolade/Documents/output -> where artifacts are generated by the CLI.

Common scenario: Trigger the workflow when a Pull Request is merged in to the main branch.

A data modeler pushes a Pull Request with updates to a model made using Hackolade Studio Workgroup Edition.

In this scenario, we would like to automatically generate the new Markdown documentation for this updated model when the Pull Request is being merged into the main branch

Here is a workflow trigger example for this use case:

name: Run Hackolade CLI using Docker Compose on GitHub Actions
on:
    push:
        branches:
            - main
jobs:
 run-hackolade-with-compose:
    runs-on: ubuntu-latest
    env:
        # License key must be managed as a secret (Repository or Organization)
        HACKOLADE_KEY: ${{ secrets.HACKOLADE_CONCURRENT_LICENSE_KEY }}
        HACKOLADE_STUDIO_CLI_IMAGE: studio:latest
        REPOSITORY_DIR_IN_CONTAINER: '/github/workspace/repository'
        OUTPUT_DIR_IN_CONTAINER: '/home/hackolade/Documents/output'
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # OR "2" -> To retrieve the preceding commit.

      #https://github.com/tj-actions/changed-files?tab=readme-ov-file#on-push-%EF%B8%8F
      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@ed68ef82c095e0d48ec87eccea555d944a631a4c # v46
        files: '**/*.hck.json'

      # - ... validate license (check workflow example)

      - name: Generate MD documentation for all changed models
        env:
          ALL_CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
        run: |
          for modelFile in ${ALL_CHANGED_FILES}; do
            modelFilenameWithoutExt=$(echo "${modelFile%.*}")
            docker compose run --rm hackoladeStudioCLI genDoc \
            --model=${modelFile} \
            --format=MD \
            --doc=${{ env.OUTPUT_DIR_IN_CONTAINER }}/${modelFilenameWithoutExt}.md
          done
        ...