Integrating with CI/CD

Akka Serverless can be integrated into a Continuous Integration/Continuous Delivery (CI/CD) process using the akkasls command for deployment. Create a script that installs akkasls and authenticates as an Akka Serverless account. The script needs a refresh token for authentication. You can use your own account in the script, or create a separate account tied to a different email address by inviting that address to your Akka Serverless project.

This page describes:

Creating a refresh token

You will need an Akka Serverless token to set up any CI/CD process. Create a refresh token as follows:

  1. Log in to the account you want to authenticate.

  2. Create a refresh token with execution scope:

    akkasls auth tokens create --type=refresh --scopes=execution --description="My CI/CD token"

    The output will look similar to:

    Token created: cst1.832640ce01f08072e91e3c848eb0767763f94ba9f973fa127d0c285a74e88076
  3. Record the token and configure it in your CI/CD solution as a secret to be passed as an environment variable, for example, as AKKASLS_TOKEN.

The next sections provide examples of how to use the variable.

General steps for configuring akkasls in a CI/CD process

To configure deployment with akkasls, write a script that runs in your CI/CD environment. You need the refresh token to be passed as an environment variable as described above. Additionally, you will need the id(s) of the project(s) you wish to work with.

The script needs the project id (a UUID), not the project name. Because the token has execution scope, it does not have permission to look up a list of projects for the account. We do not recommend widening the scope of the token to all, because it would give the CI/CD provider full permissions to do whatever they want with your project.

The example below assumes use of an AKKASLS_TOKEN environment variable for the refresh token, and an AKKASLS_PROJECT_ID environment variable for the project ID.

The following example script sets up continuous integration on a Linux machine. For other operating systems, see how to download and install akkasls.

# Download and install akkasls
tar -xzf akkasls_linux_amd64.tar.gz
mv akkasls /usr/local/bin

# Log in
akkasls config set refresh-token $AKKASLS_TOKEN

# Set the project to work with
akkasls config set project $AKKASLS_PROJECT_ID

Setting up GitHub Actions for CI/CD

The lightbend-labs/addaserverless-cicd-github-actions repository contains an example of automatic building, testing, and deployment of a Node.js Akka Serverless service. The example shows how you can use GitHub Actions, and the Akka Serverless akkasls-action GitHub Action.

The example demonstrates use of Node.js, see Changing the script for Java for information on adapting it.

How to use the example

To use the example as-is, copy the .yml files into your project repository .github/workflow directory. Enable the workflow Action from the GitHub Actions tab.

The example includes two Workflows defined in .yml files:

  • Triggered by a pull request event, node-build-test.yml runs tests and builds a Docker image.

  • Triggered by a release event, node-build-test-deploy.yml runs tests and builds the image, pushes the image to Docker Hub, and deploys it to Akka Serverless.

The akkasls-action used in the example allows you to execute any akkasls command. It takes two required variables to authenticate and set the project you want to work on correctly:

  • token: The Akka Serverless authentication token, which you create as described in Creating a refresh token.

  • project: The project ID for the Akka Serverless project to deploy the service in. Find the project ID in the Console Projects list or from the command line with akkasls projects list.

Create these variable definitions as encrypted secrets to make sure they are safe and only accessible to your GitHub Actions workflow. See the GitHub documentation for more information.

Adding functionality

To use other akkasls commands in a Workflow, add a snippet similar to the following. Replace the name and command as needed:

- name: List Services
    uses: lightbend-labs/akkasls-action@v2
        cmd: "services list"
        token: ${{ secrets.TOKEN }}
        project: ${{ secrets.PROJECT }}

Elements include:

  • name: A unique name for this workflow step. The example lists AkkaServerless services.

  • uses: The name of the GitHub Action to use (this must be lightbend-labs/akkasls-action@v2).

  • cmd: The command to execute (using akkasls commands).

  • token: The Akka Serverless authentication token.

  • project: the UUID of the project to use this workflow.

Changing the script for Java

To use Java instead of JavaScript:

  1. Copy the .yml files from the .github/workflows to your repository.

  2. Replace the Node.js specific steps with their Java equivalents:

    Replace the following element:

    - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2
          node-version: ${{ matrix.node-version }}

    with this:

    - name: Set up JDK 11
        uses: actions/setup-java@v2
          java-version: '11'
          distribution: 'adopt'
  3. Replace the npm commands:

    - run: npm ci
    - run: npm run build --if-present
    - run: npm test

    With, for example, Maven commands:

    - name: Build with Maven
      run: mvn build