CI/CD with GitHub Actions

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

Prerequisites

To use the Akka Serverless 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 Akka Serverless authentication token

  • PROJECT: The project ID for the Akka Serverless 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: akkasls
    
    on:
      push:
        branches: [ main ]
    
    jobs:
        build:
            runs-on: ubuntu-latest
            steps:
                - name: List Services
                  uses: lightbend/akkasls-action@v2
                  with:
                    cmd: "services list"
                  env:
                    token: ${{ secrets.TOKEN }}
                    project: ${{ secrets.PROJECT }}

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

- name: List Services (1)
    uses: lightbend/akkasls-action@v2
    with:
        cmd: "services list" (2)
    env:
        token: ${{ secrets.AKKASLS_TOKEN }} (3)
        project: ${{ secrets.AKKASLS_PROJECT }} (4)

Elements include:

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

Example workflow

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

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

How to use the example

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

  • AKKASLS_TOKEN: The Akka Serverless authentication token.

  • AKKASLS_PROJECT: The Akka Serverless 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/akkaserverless-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 AKKASLS_TOKEN and AKKASLS_PROJECT 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.