CI/CD with GitHub Actions

Use the Kalix kalix-action GitHub Action to use GitHub Actions with your Kalix project. The action supports commands for installing, authenticating, and invoking the Kalix CLI.

Prerequisites

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

Configure variables

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

  • TOKEN: The Kalix authentication token

  • PROJECT: 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:
        build:
            runs-on: ubuntu-latest
            steps:
                - name: List Services
                  uses: lightbend/kalix-action@v3
                  with:
                    cmd: "services list"
                  env:
                    token: ${{ secrets.TOKEN }}
                    project: ${{ secrets.PROJECT }}

To use other kalix commands in your workflow, copy the snippet below and replace the name and cmd properties as needed:

- name: List Services (1)
    uses: lightbend/kalix-action@v3
    with:
        cmd: "services list" (2)
    env:
        token: ${{ secrets.KALIX_TOKEN }} (3)
        project: ${{ secrets.KALIX_PROJECT_ID }} (4)

Elements include:

1 A unique name for this workflow step. The example lists Kalix services.
2 The command to execute (using kalix commands).
3 The Kalix authentication token.
4 The UUID of the project to which the service belongs.

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 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.