Working with Git

What you'll learn in this article

This article will describe how Git and Kapeta interacts - and explains best practices for different scenarios

Git support

Kapeta supports Git out of the box and will automatically pick up the git repository, branch and commit hash when your blocks and/or plan are available in git.

We've added additional support for GitHub at the moment - and will be adding
support for other major git vendors in the future.

GitHub Support

The easiest way to publish to Kapeta from GitHub is using the Kapeta Registry Github Action .
Further details can be found on the repository README.md on the action itself.

Semantic Versioning

Whenever you publish to Kapeta - we will automatically calculate the semantic version for you based on the changes you've made to your kapeta asset:

• Deletions / Updates: Major increment
• Additions: Minor increment
• Everything else: Patch increment

Kapeta does allow you to overwrite the default version increment calculations through conventional commit messages. These will be picked up and respected - however you can not cause a "lesser" increment than what is determined by your change to your asset.

MonoRepo

If you prefer to have your plan and all the blocks you're making for that plan in the same repository - that's perfectly fine. The Github action will scan the entire repository for kapeta.yml files and publish them all to Kapeta.
If your blocks are in the same repo Kapeta will also automatically pick up the new version for each for you - and replace them into the plan before publishing the plan itself.

This is by far the simplest way to get setup and will work well for systems where you do not intend to share your blocks with other plans or the community.

Note that you can change the repository structure at any time - Kapeta will continue to work.

The default location when creating new blocks and plans is in ~/KapetaProjects/<yourHandle>/<assetName> - but you can move these folders around if you need to. Just not that when moving folders you need to reimport them - either in the Kapeta Desktop app - or using the command line utility kap

You import using the command line by navigating to your asset folder in your terminal and running kap registry link. This will let the Kapeta desktop app know where to find it.

Multiple Repos

If you prefer to have a single repository per plan and for each block you make - that's perfectly fine as well.

Note that when you work locally your plan will point to "local" versions of your blocks - they wont have a version until you publish them - so you need to publish your blocks before you can publish a new plan.

The simplest way to achieve this is to ensure that when you publish your plan - you have checked out not just the plan - but all its blocks in a subfolder so the kapeta publish command can find them on the disk - similar to how a MonoRepo would work.

In github this would mean creating a temporary local folder - and cloning each of the blocks into that folder - before running the Kapeta Github Action.