Requirements

• bash script that builds your KAB
  • This script should build your project and create a KAB.
  • The npm and maven build systems have plugins for building KAB’s but you can have your script build a KAB using kabtool.
• Admin access of a GitHub repo that builds kabs
• Admin access to the org in kosStudio

Steps

1. Ensure that the default_artifact_store is visible in your artifact stores. If this is not set please contact the KOS team. This is the location in the cloud where your published KAB will be located. Your KAB’s need to be accessible via the internet which is what we provide with the default artifact store.

2. Create an artifact in kosStudio and save the name. An artifact needs to be created so that the build automation can publish against it. The build automation needs the name to know what artifact this KAB belongs to. 

3. Create and save studio api key, this is used to authenticate your build automation so that it can publish KAB’s against your artifacts. Only if you have the API key can you publish to the default artifact store.

4. In your repo that builds a KAB paste an updated version of this build.json in .github folder.

{
  "default_keyset": "test.kos",
  "build_cmd": "./build_artifacts.sh",
  "artifacts": [
    {
      "id": "new-artifact",
      "filename": "/target/new-artifact.KAB",
      "artifactstore": "default_artifact_store",
      "qualifier": "any"
    }
  ]
}

What to update in the build.json

• Update the “build_cmd” value with a bash script that builds your project and outputs a KAB
  1. "build_cmd": "./build_artifacts.sh",
  2. the build script needs to be in the repo and the path starts at the root of the repo
• Update the  “id” value with the name of the artifact you created in kosStudio
• Update “filename” value with the KAB output file from the build command
  1. The filename is relative to the root of the repo

5. Paste in this workflow template in .github/workflows/

name: Workflow template
on:
  push:
    branches:
      - main
  workflow_dispatch:
jobs:
  template:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/kosdev-code/kos-buildpublish/kos_builder:dockerimage
      credentials:
        username: ${{ github.actor }}
        password: ${{ secrets.github_token }}
      env:
        KOS_KABTOOL_JAR: "/usr/local/lib/KABtool.jar"
        JAVA_CMD: "java"
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          repository: ${{ github.repository }}
          token: ${{ secrets.GITHUB_TOKEN }}
          path: ${{ github.event.repository.name }}
          lfs: true
      - name: Build and Publish
        env:
          STUDIO_APIKEY: ${{ secrets.STUDIO_APIKEY }}
        working-directory: ./${{ github.event.repository.name }}
        run: |
          kos_build_handler.sh automation .github/build.json

⚠️ Ensure that the the JSON file referenced at the bottom of the YAML is correct.

This workflow is a GitHub action that will be executed every time that a push is made to the main branch. You can update this behavior depending on your needs. You can also manually run the GitHub action and publish on demand, which is what is often used for numbered releases. 

6. Update workflow template name (optional)

• set any environment variables if your build process needs it

7. Set the STUDIO_APIKEY environment variable to be the one you generated

Now you can run your build automation and your KAB’s will be available to your organization. 

For a more in depth explanation of what is happening and advanced configurations checkout https://github.com/kosdev-code/kos-buildpublish.