Altostra Docs

    ›Tutorials

    Getting Started

    • Welcome to Altostra
    • Connect your accounts
    • Install the developer tools
    • Log in from the CLI

    Tutorials

    • Create a Static Website
    • Create a Scalable Webhook
    • Create a Simple API Project
    • Try Altostra without connecting cloud accounts
    • CI/CD with Altostra CLI and Github Actions

    How To

      Working with projects

      • Create a new project
      • Deploy a project
      • Manage a project

      Working with environments

      • Manage an environment
      • Configure instances expiration for an environment

      Working with the Editor

      • Grant access to vendor services
      • Use the Parameter Store
      • Use a custom CloudFormation resource
      • Attach a custom policy to a Function
      • Connect a Function to VPC
      • Add filter policy to SNS subscription

      Organization account settings

      • Set General Settings
      • Connect a Git account
      • Connect Cloud Accounts
      • Manage log aggregation accounts

    CLI

    • Altostra CLI
    • Commands

      • templates
      • new
      • init
      • push
      • deploy
      • sls-deploy
      • sync
      • invalidate
      • domains
      • console
      • environments
      • images
      • instances
      • build
      • config
      • import
      • projects
      • tasks
      • activity-log
      • login
      • logout
      • account
      • whoami
      • api-key
      • docs

      Options

      • --debug
      • --verbose
      • Scripting options
    • Configuration files

    Errors And Solutions

    • Autnentication Required

    Technical Reference

    • Environments
    • Playground Environment
    • Instances
    • Project image
    • Image Repository
    • Log Shipping
    • Deployment Modes
    • Altostra Cloud Integration

    Integrations

      CI/CD

      • CircleCI

      Git

      • Git integration
      • Connect a GitHub account
      • Connect a Bitbucket account

    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.

    wc-create-project

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

    git-clone-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:

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

    create-api-key

    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.

    add-api-key-to-github

    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

    push-action

    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

    push-action

    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

    api-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:

    dynamo-db

    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!

    ← Try Altostra without connecting cloud accountsCreate a new project →
    • Overview
    • Things you'll need for this tutorial
    • Step 1: Create the sample project
    • Step 2: Add GitHub Actions CI workflow
    • Step 3: Getting the API Key
    • Step 4: Connecting the secret API Key to GitHub
    • Let's Run!
    • Turning the CI into CI/CD
    © 2021 Altostra, Inc.