CI/CD with Altostra CLI and Github Actions

Overview

In this tutorial, we will add basic CI/CD steps to an existing Altostra project, and integrate it with GitHub Actions.

We'll see how to:

1. Create a basic project
2. Add a GitHub Actions workflow to your project
3. Generate an API Key you can use to provide automated access to your account
4. Connect GitHub actions to your Altostra account using the API Key

Let's get started!

Things you'll need for this tutorial

1. An Altostra Account (Don't have one yet? Just login here)
2. Altostra extension for Visual Studio Code (VSCode Marketplace or see docs)
3. A connected AWS cloud account ( Web Console settings or see docs)
4. An Environment connected to your AWS Account (Web Console environments or see docs) - We'll call it Dev for berevity, but you can pick any of your environments
5. A GitHub account (Free. Don't have one yet? Just signup here)

We'll be using Altostra template to create a simple CRUD service. If you want to learn more about the project, try our Create a Simple API Project tutorial.

Step 1: Create the sample project

In this step we'll create the project we will be building the CI/CD flow for.

In the Altostra Web Console:

1. Go to Projects
2. Click Create Project
3. In the Name field we'll use "Alto CI/CD"
4. In the Template field, click the drop-down menu and select simple-crud-service-nodejs

This step will create the 'Alto CI/CD' project in your GitHub account, and populate it with the template project.

You can now git clone the project to your local machine, and open it in VSCode.

Step 2: Add GitHub Actions CI workflow

GitHub Actions allow you to trigger a workflow on multiple types of events - from a simple push to multiple events and even scheduled events (you can read more about GitHub Actions triggers here). In this tutorial we'll use a simple push event, and in this phase we'll only push the project images to the Altostra repository (We'll add the deploy step in a few steps).

In your project, at the project root, create a new file called altostra-ci.yaml, under .github/workflows/altostra-ci.yaml

Copy-paste the following code to the file:

name: Node.js CI

on:
  push:
    branches:
    - master

jobs:
  build:
    name: Altostra Push
    runs-on: ubuntu-latest

    steps:
      - name: Set node version
        uses: actions/setup-node@v1
        with:
          node-version: '12.x'
      - name: Install Altostra CLI
        run: |
             npm install -g @altostra/cli
             alto --version
             alto api-key set ${{ secrets.ALTO_API_KEY }}
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Install dependencies
        run: npm install
      - name: Push to Altostra
        # The "$(node -p -e "require('./package.json').version")" is extracting the version number from your package.json file
        run: alto push v$(node -p -e "require('./package.json').version") --json

This GitHub Actions workflow basically tells GitHub to run the "Altostra Push" job whenever someone pushes to the master branch.

Each time it will checkout the code, install dependencies, config the Altostra CLI, and use the Altostra API key to push the latest version to the Altostra repository.

Step 3: Getting the API Key

In order for the Github Actions workflow to be able to access your account, it requires an Altostra API Key.

In the Altostra Web Console, on the Settings page:

2. Click the Tokens tab
3. Click Create Token
4. Give your token a meaningful name so you'll recognize it later
5. Keep your token somewhere safe - this is the last time you'll see this token!

Step 4: Connecting the secret API Key to GitHub

Your API Key lets the bearer of the token to act in your account - which is why it should always be kept safe, and preferably encrypted. In order to use the API Key in the GitHub Actions workflow without jeopardizing it, we will store it as a GitHub Secret.

Go to your GitHub repository, and:

1. Click on Settings
2. Select Secrets from the left side menu
3. Click New Secret
4. Name your secret ALTO_API_KEY
5. Paste your secret into the input field.

Your secret is not visible to anyone (including yourself) - it can only be updated or deleted.

Let's Run!

We created a project, added a CI workflow, created an API key and placed it within GitHub's secrets store. All we need to do now is trigger the workflow with a push command.

1. git push your latest changes to your GitHub repository
2. Go to your GitHub's project page, and click Actions - You will see your workflow running. Once it's successfully finished,
3. Go to your project page in the Altostra Web Console:
4. Go to Images tab.
5. You should see an image with the latest version number

Congratulations! You've built your first CI using Altostra and GitHub Actions!

Turning the CI into CI/CD

The move from CI to CI/CD is not trivial - it usually requires some kind of canary testing, automated integration and sanity tests to make sure that your version is stable and production-ready. In this part of the tutorial we'll skip the testing phase and show you how to add the "Deploy" phase of the CI/CD.

Adding a "Deploy" phase to your current CI workflow is simple.

First, add the following code snippet at the end of your altostra-ci.yaml file.

      - name: Deploy to Prod
        run: alto deploy production:v$(node -p -e "require('./package.json').version") --env Prod --json

Then, run git push again to trigger the updated workflow.

This time, after the workflow is successfully completed:

1. Go to your project page in the Altostra Web Console
2. Go to Instances tab
3. Your instance will be deploying
4. Clicking the arrow link on your instance will take you directly to your project stack on AWS Console

Test

Now that our application is deployed we can go ahead and test our API Gateway and endpoints.

First, get the API Gateway endpoint.

1. Go to your AWS stack
2. Click on Resources
3. Click on the API Gateway resource
4. Click on Stages
5. Select Prod
6. Copy the Invoke URL

Now, lets send a sample request:

curl --location --request POST '${YOUR_API_GATEWAY_ENDPOINT}/resource' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "john doe",
    "email": "john.doe@gmail.com"
}'

You should get this response:

HTTP/2 200
content-type: application/json
content-length: 0

Now you can go to your DynamoDB table and check for entries:

Now let's test our GET request:

curl --location --request GET '${YOUR_API_GATEWAY_ENDPOINT}/resource/{<YOUR RESOURCE_PK>}'

You should get a similar response:

{
    "id": "7832eddbcdbad68f17407382b15f948a",
    "email": "john.doe@gmail.com",
    "name": "john doe"
}

Congratulations, you've successfully created a fully working CI/CD workflow with Altostra and Github Actions!