Interacting with Git repositories from Warp 10

Having the ability to store and read files from Warp 10 is something often requested. Today we talk about a WarpScript extension which introduces functions to interact with git repositories.

When you have been working with Warp 10 for a while you usually find yourself with quite a few macros and runners deployed in your instance. And from time to time you wish you could easily add or modify some of that WarpScript code. Well, the good news is: now you can!

Thanks to the recently introduced capabilities features (available since the release 2.8.0), access to powerful functions can now be controlled, and therefore we created a WarpScript extension which can interact with git repositories so you can create and modify files directly from Warp 10.

What can it do?

The git WarpScript extension introduces new functions which can interact with git repositories configured in your Warp 10 instance. These functions can store, list and retrieve content, inspect commit logs, apply tags and remove files.

Those functions can be used from any WarpScript code if the right capability was previously added using CAPADD.

While this extension does not provide a full-fledged git client, it has proved very useful in many scenarios, such as storing generated code, snapshots of data or updating backend macros and scheduled WarpScript code.

Setting up Warp 10 to work with git

Configuring a Warp 10 instance to work with git is very simple. First, you need to download the git WarpScript extension from WarpFleet, then simply enable the extension and set a value for the git.rootdir key which should point to a root directory where all accessible git repositories will reside (potentially via symbolic links to their true location).

warpscript.extension.git = io.warp10.ext.git.GitWarpScriptExtension
git.root = /path/to/git/root

Once this is done, restart your Warp 10 instance.

Generating tokens with the right capabilities

As stated earlier, thanks to the capabilities feature, access to the configured git repositories can be managed via specially crafted tokens.

The following capabilities control various aspects of the interaction with those repositories:

git.repo

Via the .cap:git.repo token attribute, this defines the name of the repository which can be accessed. This is the name of a directory or symbolic link present in the directory defined in git.root.

git.name and git.email

The capabilities .cap:git.name and .cap:git.email set the name and email address which will appear in commit logs for operations which modify a repository. If unset, the name warp10-ext-git and the email address contact@senx.io will be used.

git.subdir

If the capability .cap:git.subdir is set, only this subdirectory of the repository defined in git.repo will be accessible. All paths will be relative to this subdirectory.

This is handy when you want to grant access to specific areas of a repository to different users without managing multiple repositories.

git.ro

When the capability .cap:git.ro is present in a token, regardless of the associated value, the repository is only accessible in read only mode.

The easiest way to create a token suitable for interacting with a git repository is by using the TOKENGEN function. The following snippet shows how to create a token which can only be used for setting capabilities:

{
  "type" "READ"
  "owner" "00000000-0000-0000-0000-000000000000"
  "application" "dummy"
  //
  // Expiry in milliseconds
  //
  "expiry" NOW 100 ADDYEARS 1000 /
  "attributes" {
    //
    // Forbid the use of token for authentication or access to data
    //
    ".nofind" ""
    ".noauth" ""

    //
    // Git related attributes (capabilities)
    //
    ".cap:git.repo" "gitrepo"
    ".cap:git.name" "First Last"
    ".cap:git.email" "first.last@domain.tld"
  }
}
"token.secret" // As configured for io.warp10.script.ext.token.TokenWarpScriptExtension
TOKENGEN

The generated token can then be used in a call to CAPADD.

Using the git extension functions

The creation of a commit is simply done in the following way:

"TOKEN_WITH_GIT_CAPABILITIES" CAPADD
"Hello, Git!" "content" STORE
{
  "content" $content
  "message" "First commit"
  "repo" "gitrepo"
  "path" "hello/git.txt"
}
GITSTORE

This will create or modify the file hello/git.txt in the repo gitrepo (the name must match the one present in the token) and commit the change with the specified message. The function will return the id of the revision containing the change.

Access to the content of that file can be done simply using GITLOAD:

"TOKEN_WITH_GIT_CAPABILITIES" CAPADD
{
  "repo" "gitrepo"
  "path" "hello/git.txt"
}
GITLOAD

Note that the content is returned as a byte array, use BYTES-> to convert it to a STRING if needed.

If you want to modify the runners or macros of your Warp 10 instance using the git extension functions, simply create symbolic links in git.root which point to the warpscripts and macros directories in your installation. Then initialize a git repository within those directories and commit the files you want to be able to load.

Takeaways

The git extension adds functions which allow you to interact with git repositories directly from Warp 10. This opens up a lot of possibilities, some of which will be presented in future blog posts.