Configuring a GitHub workflow with Sigma CLI

GitHub Actions enables you to create custom software development life cycle (SDLC) workflows directly in your GitHub repository. Therefore if you are using GitHub as the version control system of your Sigma project, you can use the Sigma CLI to configure a workflow to automate the build and/or the deployment of your serverless application.

In this article, we discussed the steps on how to configure such a workflow with Sigma CLI, that builds and deploys your project at each update to the master branch of your GitHub repository.

 

Configuring the AWS Keys

Since we need to provide Sigma CLI access to our AWS account, we need to provide an AWS key pair in the workflow configuration. But we should not specify them plainly in our workflow configuration, because then anyone who has read access to your repository can access them, which is a major security concern. On the other hand, if AWS detected that a key pair is compromised as such, they automatically invalidate that key pair, so it won’t be useful anymore.

So the best and the GitHub recommended approach is to configure the AWS access key and the access secret as GitHub Secrets of your projects. We can configure these secrets either at the organizational level or at the repository level. If configured at the organizational level, they can be shared between multiple repositories. But for this article, we’ll configure them at the repository level.

For that,

  • Open the Settings tab of your project on GitHub console and go to the Secrets section.
  • Click on the New Secret button and provide a suitable name such as AWS_ACCESS_KEY for the secret. Then provide your AWS Access Key as the value of the secret and click Add Secret button.
  • In the same manner, add another secret for the AWS Access Secret with a suitable name such as AWS_SECRET_KEY.

GitHub workflow with Sigma CLI

 

Creating a workflow file

The next step is to create a Workflow configuration file for the project. For that,

  • Open the Actions tab of your project on the GitHub console and click on the set up a workflow yourself link.
  • Then a YAML file with a sample configuration will be opened on the .github/workflows subdirectory in your project.
  • Provide a suitable name for the file as you desired.

 

Configuring the workflow

Now let’s configure our workflow on the previously created YAML file step-by-step.

Please note that we are discussing only the most important workflow configurations in the below steps. But you can refer the documentation on GitHub Workflow Configuration and Workflow Syntax for customizing and fine-tuning your workflow further.

Workflow name, triggers, and job

As the first step, let’s give a name for our workflow such as Auto Deployment. Then we need to set the configuration on what kinds of events that this workflow should be triggered. Let’s configure to trigger this workflow for each push to the master branch of the repository. Additionally, we may need to prevent the workflow from getting triggered for the changes pushed to the .github path, which contains configuration files such as the workflow file we are editing right now.

Also, we should define a job with a suitable job ID such as deployment, which we are going to configure in the next steps.

name: Auto Deployment

on:
  push:
    branches: [ master ]
    paths-ignore:
      - '.github/**'
jobs:
  deployment

Workflow execution environment

Then we need to configure the environment to run this job. First of all, we should define a runner to execute this job. GitHub allows using GitHub-hosted runners as well as self-hosted runners. For this workflow, we are going to use the GitHub-hosted ubuntu-latest runner.

We need to have NodeJS version 10 or newer installed for the Sigma CLI and also need Python 3 if your project has Python Lambda functions. Since the above runner has some outdated versions of these, we are also going to use a docker container with these installed to run the build steps. For that, we are going to use the nikolaik/python-nodejs:python3.8-nodejs14 docker image which has NodeJS 14 and Python 3.8 pre-installed. You can use any other docker image as well.

jobs:
  deployment:
    runs-on: ubuntu-latest
    container: nikolaik/python-nodejs:python3.8-nodejs14

Checkout repository to the workflow space and install Sigma CLI

After setting up the execution environment, let’s get started on the job steps. First, let’s check out the repository content to the workflow space using the GitHub in-built checkout@v2 action. After that, we can use the npm install command to install the slappforge-sigma-cli module globally on the execution environment.

jobs:
  deployment:
    runs-on: ubuntu-latest
    container: nikolaik/python-nodejs:python3.8-nodejs14

    steps:
      - uses: actions/checkout@v2

      - name: Install Sigma CLI
        run: npm i slappforge-sigma-cli -g

Build project

Now we are ready to build the project using the Sigma CLI. For that, we need to extract the previously configured AWS Access Key and the AWS Access Secret from the GitHub secrets and assign them to environment variables. Then we can invoke the sigma aws build command with these environment variables as well as other necessary parameters.

jobs:
  deployment:
    runs-on: ubuntu-latest
    container: nikolaik/python-nodejs:python3.8-nodejs14

    steps:
      - uses: actions/checkout@v2

      - name: Install Sigma CLI
        run: npm i slappforge-sigma-cli -g

      - name: Build Project
        env:
          AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
          AWS_SECRET_KEY: ${{ secrets.AWS_SECRET_KEY }}
        run: sigma aws build --s3Bucket deployment.packages.bucket --s3Prefix auto_builds --awsKey $AWS_ACCESS_KEY --awsSecret $AWS_SECRET_KEY

Assign deployment package URL to an environment variable

For the deployment step, we need to have the S3 URL of the deployment package generated via this build step. The above build command will output that S3 URL to the stdout and we have to assign that to an environment variable to be accessed by the deployment step later. So let’s do a small change to the Build Project step as follows to assign the output to an environment variable named DEPLOYMENT_PACKAGE.

jobs:
  deployment:
    runs-on: ubuntu-latest
    container: nikolaik/python-nodejs:python3.8-nodejs14

    steps:
      - uses: actions/checkout@v2

      - name: Install Sigma CLI
        run: npm i slappforge-sigma-cli -g

      - name: Build Project
        env:
          AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
          AWS_SECRET_KEY: ${{ secrets.AWS_SECRET_KEY }}
        run: echo "::set-env name=DEPLOYMENT_PACKAGE::$(sigma aws build --s3Bucket deployment.packages.bucket --s3Prefix auto_builds --awsKey $AWS_ACCESS_KEY --awsSecret $AWS_SECRET_KEY)"

Upload the deployment package as a workflow artifact

As an optional step, let’s upload the above-generated deployment package as a workflow artifact, so we can easily access the deployment package of particular workflow execution later. For that, we can use the GitHub in-built upload-artifact@v2 action as below.

jobs:
  deployment:
    runs-on: ubuntu-latest
    container: nikolaik/python-nodejs:python3.8-nodejs14

    steps:
      - uses: actions/checkout@v2

      - name: Install Sigma CLI
        run: npm i slappforge-sigma-cli -g

      - name: Build Project
        env:
          AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
          AWS_SECRET_KEY: ${{ secrets.AWS_SECRET_KEY }}
        run: echo "::set-env name=DEPLOYMENT_PACKAGE::$(sigma aws build --s3Bucket deployment.packages.bucket --s3Prefix auto_builds --awsKey $AWS_ACCESS_KEY --awsSecret $AWS_SECRET_KEY)"

      - uses: actions/upload-artifact@v2
        with:
          name: deployment-package
          path: sigma_builds/build_*.zip

Deploy Project

As the last step, we are going to deploy the project with the sigma aws deploy command. As we did on the project build step, we are going to first extract the previously configured AWS Access Key and the AWS Access Secret from the GitHub secrets and assign them to environment variables. Then we are going to invoke the deploy command with those environment variables, DEPLOYMENT_PACKAGE variable we created in the build step, and other necessary parameters. Also, we should make sure to set the --autoDepMode parameters to true, so the deployment process goes ahead without waiting for any user confirmations.

jobs:
  deployment:
    runs-on: ubuntu-latest
    container: nikolaik/python-nodejs:python3.8-nodejs14

    steps:
      - uses: actions/checkout@v2

      - name: Install Sigma CLI
        run: npm i slappforge-sigma-cli -g

      - name: Build Project
        env:
          AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
          AWS_SECRET_KEY: ${{ secrets.AWS_SECRET_KEY }}
        run: echo "::set-env name=DEPLOYMENT_PACKAGE::$(sigma aws build --s3Bucket deployment.packages.bucket --s3Prefix auto_builds --awsKey $AWS_ACCESS_KEY --awsSecret $AWS_SECRET_KEY)"

      - uses: actions/upload-artifact@v2
        with:
          name: deployment-package
          path: sigma_builds/build_*.zip

      - name: Deploy Project
        env:
          AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
          AWS_SECRET_KEY: ${{ secrets.AWS_SECRET_KEY }}
        run: sigma aws deploy --depPackage $DEPLOYMENT_PACKAGE --awsKey $AWS_ACCESS_KEY --awsSecret $AWS_SECRET_KEY --autoDepMode true

 

That’s it! We have now configured a CI/CD workflow to our Sigma project repository. You can push a change to the master branch of the repository and see if the workflow works successfully on the Actions tab of the GitHub project console.

You can see the full workflow configuration below.