Deployment Automation with GitHub Actions and Nitric

This guide will demonstrate how Nitric can be used, along with GitHub Actions, to create a continuous deployment pipeline. The actions in the example below target AWS, but can be modified to target Google Cloud or Microsoft Azure.

Workflow setup

To begin you'll need a Nitric project ready to be deployed. If you haven't created a project yet, take a look at the quickstart guide.

Next, we'll add a GitHub Actions workflow file to the project. This is where you'll configure the deployment automation steps. Create a yaml file in a .github/ folder at the root of your project. The file can be named how you like, in our case we'll name it deploy-aws.yaml.

Here is example content you can copy into your workflow file. In the next sections we'll breakdown what's happening in this file, so you can modify it as you see fit.

name: Example Nitric AWS Deployment
on:
  workflow_dispatch:
  push:
    branches:
      - main
env:
  PULUMI_CONFIG_PASSPHRASE: ${{ secrets.PULUMI_ACCESS_TOKEN }}
  PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}
jobs:
  update:
    name: Update Deployment
    runs-on: ubuntu-latest
    steps:
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-region: ${{ secrets.AWS_REGION }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      - name: Install Nitric CLI
        uses: nitrictech/setup-nitric@v1
        with:
          version: 1.28.0
      - name: Install dependencies
        uses: pulumi/setup-pulumi@v2
      - name: Checkout project
        uses: actions/checkout@v3
      - name: Resolve packages
        run: npm install
      - name: Deploy stack to aws
        run: nitric up -s dev -v2

Breaking it down

Edit the config file and start by defining a name.

name: Example Nitric AWS Deployment

Setup the workflow trigger(s)

Triggers tell your workflow when to run.

• workflow_dispatch
  • This trigger allows the workflow to be manually run from GitHub
• push -> branches -> main
  • This will trigger the workflow each time there is a push to the main branch

on:
  workflow_dispatch:
  push:
    branches:
      - main

Environment variables

Configure the environment variables required by Nitric's dependency Pulumi. In this example we store the required values in GitHub secrets. Secrets can be found by navigating to https://github.com/{user}/{project}/settings/secrets/actions.

• PULUMI_ACCESS_TOKEN
  • You can get a pulumi access token by logging into Pulumi on the browser and going to your profile settings. Under the 'Access Tokens' tab click 'Create token'.
• PULUMI_CONFIG_PASSPHRASE
  • For interaction free experiences, Pulumi also requires a passphrase to be configured. Your passphrase is used to generate a unique key which encrypts configuration and state values.

env:
  PULUMI_CONFIG_PASSPHRASE: ${{ secrets.PULUMI_CONFIG_PASSPHRASE }}
  PULUMI_ACCESS_TOKEN: ${{ secrets.PULUMI_ACCESS_TOKEN }}

Intialize your workflow

Assign a name to the first job in the workflow and set which operating system the workflow will be run on.

jobs:
  update:
    name: Update Deployment
    runs-on: ubuntu-latest

AWS Credentials

Setup your AWS action with the following credentials as GitHub secrets:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_REGION

You can obtain a key, including its ID and value, from the amazon console. You can then set your preferred region, such as us-east-2.

steps:
  - name: Configure AWS Credentials
    uses: aws-actions/configure-aws-credentials@v1
    with:
      aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
      aws-region: ${{ secrets.AWS_REGION }}
      aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

Install Nitric and dependencies

These steps install the Nitric CLI and Pulumi, allowing the use of commands such as nitric up.

- name: Install Nitric CLI
  uses: nitrictech/setup-nitric@v1
  with:
    version: 1.28.0
- name: Install dependencies
  uses: pulumi/setup-pulumi@v2

Deploy the stack

Finally, checkout your project and run the up command to deploy your project. In this example our project has a stack named dev, which we can select with the -s argument, e.g. nitric up -s dev -v2. The final argument -v2 sets the Nitric CLI output to verbosity level 2, so the workflow will log plenty of detail for us to use to debug any issues.

- name: Checkout project
  uses: actions/checkout@v3
- name: Resolve packages
  run: npm install
- name: Deploy stack to aws
  run: nitric up -s dev -v2