CI/CD with GitHub Actions

Use the Kalix setup-kalix-action GitHub Action to use GitHub Actions with your Kalix project. The action supports commands for installing, authenticating, and invoking the Kalix CLI. Releases are tracked on the GitHub releases page. The action is present in the GitHub marketplace.

Prerequisites

To use the Kalix GitHub Action, you’ll need to:

  • Create a service token for your project

  • Get the UUID of your project, which can be obtained by running akka projects list

Configure variables

The GitHub Action uses two required variables to authenticate and set the project you want to work on correctly:

  • KALIX_TOKEN: The Kalix service token

  • KALIX_PROJECT_ID: The project ID for the Kalix project you’re using

These variables should be configured as secrets new tab for your repository.

Create a workflow

Follow these steps to create a workflow to invoke the GitHub Action for your project:

  1. Create a folder named .github at the root of the project folder.

  2. Create a file named config.yml in the .github folder.

  3. Open config.yml for editing and add:

    name: kalix

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Install Kalix CLI
        uses: lightbend/setup-kalix-action@v1
        with:
          token: ${{ secrets.KALIX_TOKEN }} (1)
          project-id: ${{ vars.KALIX_PROJECT_ID }} (2)
      - name: List services (3)
        run: kalix service list (4)
    1 The Kalix authentication token.
    2 The UUID of the project to which the service belongs.
    3 A unique name for this workflow step. The example lists Kalix services.
    4 The command to execute.

Example workflow

The lightbend/kalix-cicd-github-actions repository contains an example of a workflow that automatically builds, tests, and deploys a Node.js service to Kalix.

The repository contains 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 Kalix.

How to use the example

The setup-kalix-action used in the example workflows allows you to execute any kalix command. It takes two required variables to authenticate and set the active project:

  • KALIX_TOKEN: The Kalix authentication token.

  • KALIX_PROJECT_ID: The Kalix project ID for the service to be deployed.

The workflows additionally use variables to supply Docker credentials for building the service image:

  • DOCKERHUB_USERNAME

  • DOCKERHUB_TOKEN

To use the lightbend/kalix-cicd-github-actions example, copy the workflow files and save the required variables as GitHub secrets new tab:

  1. Copy the workflow .yml files from the example repository .github/workflows/ new tab directory into your project repository .github/workflow directory.

  2. In the project GitHub repository, use the saved values to create secrets for the KALIX_TOKEN and KALIX_PROJECT_ID variables.

  3. Create secrets to store your Docker username and password as DOCKERHUB_USERNAME and DOCKERHUB_TOKEN variables.

  4. Modify the .yml files, if required.

  5. From the GitHub Actions tab, view both workflows.