Upload, Update, Use (Git)
Instead of uploading modules to ApiOmat directly, you only have to push code changes to the Git repository and trigger that ApiOmat pulls these changes from the repository.
Any module can have a Git repository attached and use that to get or push the current code either to or from your ApiOmat installation.
API Endpoints and their behaviour
The flow boils down to the behaviour of these endpoints:
-
POST /yambas/rest/modules/{moduleName}/gitData
-
Appends the git repository information to the module. If the module already had git data attached, the old data is overwritten.
-
The data is stored per system, depending on the X-apiomat-system header that comes with the request.
-
the (old) endpoint POST /yambas/rest/modules/{moduleName}/gitinit is equivalent and works the same, but has been deprecated in favor to this endpoint
-
also supports subfolders (see the section about subfolders below)
-
-
GET /yambas/rest/modules/{moduleName}/gitData
-
Shows the current git data
-
the commitId field shows the id of the last pull from git (see next point)
-
-
GET/POST /yambas/rest/modules/{moduleName}/git - "Git Pull"
-
checks out the repository and branch, which was defined in the gitData, and deploys it to Yambas (if it contains the module code)
-
if the repository does not contain the module, it will generate the module code and deploy it (just like the makeNative endpoint)
-
the update process depends on the "update" parameter of this endpoint, which may either be "true", "false" or "overwrite", like the sdk.property value
-
the commitId in modules git data will be set to the checked out commit
-
nothing will be pushed and the checked out repository will be removed from file system after the deployment is finished
-
-
GET /yambas/rest/modules/{moduleName}/gitPush - "Git Push"
-
checks out the repository, creates the updated module files and pushes them to git
-
the module deployed on yambas will remain the same (use the GET ../git Endpoint to deploy a changed state)
-
Practical Usage
In the common usage there are these three cases:
-
You change code locally
-
You change the data model (e.g. add a MetaModel, change attributes of a MetaModel, ...) via dashboard or REST API
-
You change code and at the same time the data model gets changed via dashboard or REST API
In all cases we will refer to the "MyModules/Native Modules" page (e.g. http://apiomat.yourcompany.com/dashboard/myModule/index), which will look similar to the following after you've created a Native Module:
1. You change code locally
You can make changes to the code you checked out locally to your computer via Git. Either you add/remove/change attributes to a MetaModel, add/remove a whole MetaModel or implement hook methods.
After you've done that, you just commit and push the changes to the Git repository. Then you send a request to the URL that triggers a pull and afterwards a deploy (see screenshot at the beginning of this page). You can do this by simply clicking on the link in the dashboard or you can automate it by using git hooks in your Git repository. You can also create Git hooks which trigger the call of this URL automatically when there are code changes pushed to the repository. For further information about this automation see Git Automatic pull trigger integration.
The response should be similar to the following: "Git checkout of ref master and deploy of module NewNM and system LIVE successful.".
You can also trigger this in the Apidocs or via cURL with a GET request to the endpoint: /modules/{moduleName}/git. See https://apiomat.yourcompany.com/apidocs/index.html#!/modules/cloneAndDeployNativeModuleGit. It's the same URL as shown in the dashboard (or in the screenshot at the beginning of this page).
A pull of a module from the git repository through the /modules/{moduleName}/git endpoint will lead to a checkout of the repository in the specified branch and a deploy of that state.
Keep in mind: If you want to increment the version of your module code-first within your pom.xml, you need to create a new branch first!
Otherwise the module version in your Git repository wouldn't match to the connected module version in Yambas which will produce a bad request error.
2. You change the data model via dashboard or REST API
You can change the data model via dashboard or REST API and add/remove/change attributes to a MetaModel, add/remove a whole MetaModel etc. If you finished with all changes, you can either simply re-deploy your module (e.g. by building it again through the "build" notification in the dashboard) or push your changes to the repository using the "Push changes to Git repository" button or via Apidocs or cURL with a request to the endpoint: /modules/{moduleName}/gitPush. See https://apiomat.yourcompany.com/apidocs/index.html#!/modules/pushMetaModelChanges. The module will not be deployed automatically during the push.
3. You change code and at the same time the data model gets changed via dashboard or REST API
Please read the sections "You change code" and "You change the data model via dashboard or REST API" first to understand the basic behaviour of ApiOmat when updating Git Native Modules.
When you update the data model via code locally and through dashboard or REST API at the same time (or maybe multiple developers work on the same project), the following cases can occur:
-
You trigger the pull + deploy before the push endpoint was called
-
The push endpoint gets called, directly in the same time a push from a developer was made
1. You trigger the pull + deploy before the push endpoint was called
If you trigger the pull + deploy before the push task gets executed, no conflict will occur and the changes you made in the dashboard or via REST API will be overwritten with the code in the Git repository.
2. The push endpoint gets called, in the same time a push from a developer was made
If the push endpoint gets called and in the same time a push from a developer was made, there is a small chance, that ApiOmat just has checked out the current repository state, then a push from a developer gets done while ApiOmat is generating the module code, and the checkout state is not up to date and may therefore lead to a conflict if the same files have changed. You have two possibilities to resolve these changes by setting the "yambas.git.conflictmode" property in your apiomat.yaml.
The first (and default) option is to set "branch" as value. ApiOmat will then create and switch to a branch with a naming pattern like "AOM_MetaModelChange_<timestamp>" (with <timestamp> being the current UNIX epoch time in milliseconds) and push the changes to that branch. You can then manually merge the changes to the originating branch.
The second option is to set "force" as value. ApiOmat will then do a "force push" and overwrite the changes from the developer.
Using Maven
Since ApiOmat version 2.3, every module is delivered with a pom.xml, which will support you in the full lifecycle. Read more about the Maven integration.
Using multiple modules in one git repository
You can put multiple modules into one git repository. The modules' git data now have a special field "subfolder" to specify a folder in the git repository where to find the module (and push the changed files).
You can also use our structrue for integration tests and Yambas will detect such a structure automatically. Even when you're only specifying the root-level of the structure.
Example: Your git-repository is structured as the following:
-
/ (root directory of the checked out project)
-
/smtp/smtp (containing the module files of module SMTP)
-
/smtp/smtp-integrationtest (containing the integration-test files of SMTP)
-
/smtp/Jenkinsfile (Jenkinsfile for module SMTP)
-
/ldap/ldap (containing the module files of module LDAP)
-
/ldap/ldap-integrationtest (containing the integration-test files of LDAP)
-
/ldap/Jenkinsfile (Jenkinsfile for module LDAP)
-
...
Now you can create a Module SMTP and its git data referring to this repository and specifying "smtp" as subfolder. Yambas will then check the subfolder, detect the structure for integration-tests and update the subdirectory automatically to smtp/smtp and work in this directory.
Using Git with key-based auth via SSH
If you want to use key-based auth on your ApiOmat installation, you have to put the private key, which is authorized for your Git repositories, into the correct directory of the ApiOmat installation.
You have to put the private key (named id_rsa) into the .ssh folder of the home directory of the user that owns the Yambas process.
On a Linux system this is the tomcat7 user (so the home directory is /home/tomcat7 on a default installation). The file should be owned by the tomcat7 user and have the file mode 600 (read and write only allowed for that user).
On a Windows system the SSH directory is under C:/Users/Administrator/.ssh (if the tomcat process is configured to run under another user, replace "Administrator" with the other username)
We currently only support SSH keys with no additional password. When you add the module in the Dashboard, simply leave the Git password field empty.
Supported Git Services
This article contains a quick overview about supported Git services. The following table will be extended on request periodically:
|
Git Service |
Supported |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
