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.
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.
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:
- Validate a concurrent license key (managed as a repository secret)
- 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
- Gather logs and generated artifacts into GitHub workspace on the runner
- 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.
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
...
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:
- 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
- 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