Skip to content

hackolade/studio-cli-github-actions-examples

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Run Hackolade CLI using Docker Compose on GitHub Actions

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.

Important

The workflows examples are meant to serve as inspiration. You must review each GitHub Action your are using eventually and make sure it complies with your organization security policies and constraints, as well as check potential CVEs that could affect such actions.

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 [email protected].

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: step-security/[email protected]
        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
        ...

Persist logs for troubleshooting when help from Hackolade Support is necessary

Hackolade Studio Cli is persisting its logs inside each Docker container that is created when executing Studio CLI commands. To make sure you gather these logs for each step of your workflow you need to:

  1. Extract these logs from the container into a local.

This is done in the example workflow thanks to a data container serving as a proxy to Docker named volumes. You can then use this container hck-studio-cli-generated-data to retrieve the data you need into a local folder (e.g. ./logs) on the GitHub Action runner.

Example:

      - name: Retrieve Hackolade logs from volumes
        run: |
          docker cp ${{ env.DATA_VOLUMES_CONTAINER_NAME }}:/logs/. ${PWD}/logs/logs-fe-jsonschema-generation
  1. Upload all the files you want to keep to GitHub Artifacts.

This is done in the example workflow thanks to the action actions/upload-artifact. This action makes sure you have a link to a Zip archive containing all your assets for each of your workflow run.

Example:

      - name: Upload logs to Github Artifacts
        id: persist-logs
        uses: actions/[email protected]
        with:
          name: studio-cli-logs
          path: ./logs
          if-no-files-found: warn
          retention-days: 5

About

GitHub Action's workflow examples to leverage Hackolade Studio CLI Docker image for CI/CD use cases

Topics

Resources

Stars

Watchers

Forks

Contributors 2

  •  
  •