CI/CD Integration

In case you have your own way of managing source code for serverless functions (i.e GitHub, or a CI/CD pipeline somewhere), you can still use STATEWIZE by deploying your functions' onto states in a flow.

This is possible using the CLI. Let's look at a practical example:

Deploying your code

Imagine we've built this flow on STATEWIZE:

A flow with 2 states

Now, let's say we already have a code repository with the source code which we would like to deploy to these two states. Specifically:

Existing project

This is a project you own and manage. It can be in Typescript, have external libraries installed via npm, whatever you like. Now, assume we have 2 functions:

  1. First, inside the file, saveRequestToDb.ts, which should be deployed onto the state named save-request.

  2. Second, inside the file updateBI.ts, which should be deployed onto the state named update-bi.

STATEWIZE does not build your code or run your tests. STATEWIZE expects to receive the final bundle for every state, in its final form.

Meaning, compiled to es5 commonjs runtime. So, assuming that after running your typescript compilation, you would have 2 built compiled functions under the build folder:

compiled functions

And that is what we want to deploy to STATEWIZE, to each state respectively. The next step is to define the Specfile:

Stwspec.json file

The purpose of this file is to define which source code should go where. Let's take a look:

{
"stw-v1": {
"deployment": {
"bundles": [
{
"bundleDir": "./build",
"runtime": "nodejs12.x",
"token": "TUP12345...",
"layout": [
{
"stateName": "save-request",
"entryPoint": "functions.saveRequestToDb.save"
},
{
"stateName": "update-bi",
"entryPoint": "functions.updateBI.update"
}
]
}
]
}
}
}

The structure is simple. We have a deployment, which can have one or more bundles. Each bundle has a layout, which specifies what goes where from that bundle.

  • Bundle - a bundle defines a directory with code that should be deployed somewhere. In the example above - it's our build directory, as that's where the deployable code will be waiting. The whole directory will be deployed for every state, and you just need to specify which function should be executed from which file (this is done in the Layout configuration). You can have more than one bundle, if you have built code in different directories, but in most cases - one is enough. Each bundle defines the runtime (one of nodejs12.x, python3.8) for the code, and the deployment token (See instructions further down on this page).

  • Layout - Each bundle defines the layout - which file contains what method, and where should that be deployed to (which state).

In the Specfile above, we have specified that we are deploying source code from the ./build directory, using the deployment token we fetched before. The runtime of our code is nodejs12.x. The file functions/saveRequestToDb.js has a method called save, and this is what should be run by the state save-request. The other file functions/updateBI.js has a method called update, and this is what should be run by the state save-request. More examples and an explanation about entry points is available further down.

Security best practice: We recommend NOT pasting your token verbatim in the Stwspec.json file, but rather having it available as an ENVIRONMENT variable, and providing the key instead. So, in the Stwspec.json file, instead of

"token": "TUP12345......"

we would have:

"token": "DEPLOYMENT_TOKEN"

The CLI

Our CLI is available here: https://www.npmjs.com/package/stw-cli

Instructions for installing it are available on NPM.

Deploying

Once our CLI is installed, our code is built and our Specfile is defined, all that is left is to run the deployment command:

stw deploy -p $PUBLIC_KEY -a $API_KEY

That's it! Your code should now be deployed to STATEWIZE.

Entry Point

The entryPoint parameter is structured in the following way:

path.path.file-name-without-extension.function-name-to-execute

  • So if your code was under test.js, and the function to execute was bla(), the entryPoint would be test.bla.

  • If your code was under somewhere/across/the/rainbow.js, and the function to execute was main(), the entryPoint would be somewhere.across.the.rainbow.main.

Fetching Tokens

API Key and Public key:

  1. Navigate to your Settings page: https://app.statewize.com/settings/user-settings

  2. If you haven't done so already, generate an API token. Your public key and token will appear:

Generating API access keys

Make sure to save your API token, as it will only be shown once.

That's it!

The public key / API token pair is unique per workspace. So if working across multiple workspaces, make sure to generate a new set!

Deployment token:

The deployment token is unique per flow and per environment. So in order to fetch that token, go to the flow you want to deploy and click on "Integrate":

Flow view

In the screen that opens, choose the "Deployment tokens" tab:

Copy the token for the right environment. For example. you may choose to use the staging token when deploying from the develop branch, or the production token when deploying from the main branch. Your CI/CD - your choice.