Overview

The GitHub Actions Builder provides a way to automatically build applications from source code using GitHub Actions. This allows Nullstone to wait for a build completed by GitHub Actions before deploying the application. Optionally, Nullstone can trigger this workflow so that it is coordinate with preview environments.

Workflow Filename

The GitHub Actions Builder needs to know which GitHub Actions workflow is configured to build your application. The workflow filename should be .github/workflows/<workflow-name>.yml.

Trigger Workflow

If you configure Nullstone to initiate the build workflow, Nullstone will perform a dispatch workflow against the GitHub Actions workflow. Your GitHub Actions workflow should have the following:

• workflow_dispatch trigger
• Optionally, inputs for each NULLSTONE_... environment variable
  • NULLSTONE_STACK
  • NULLSTONE_APP
  • NULLSTONE_ENV
  • NULLSTONE_VERSION
  • NULLSTONE_COMMIT_SHA

on:
  workflow_dispatch:
    inputs:
      NULLSTONE_ORG:
        type: string
        description: 'Nullstone Organization'
        required: true
      NULLSTONE_STACK:
        type: string
        description: 'Nullstone Stack'
        required: true
      NULLSTONE_APP:
        type: string
        description: 'Nullstone App'
        required: true
      NULLSTONE_ENV:
        type: string
        description: 'Nullstone Environment'
        required: true
      NULLSTONE_VERSION:
        type: string
        description: 'Nullstone Version'
        required: true
      NULLSTONE_COMMIT_SHA:
        type: string
        description: 'Nullstone Commit SHA'
        required: true

Example

The following example performs a build in GitHub Actions when a user triggers a deployment in Nullstone. The GitHub Actions workflow file builds and pushes a Docker image to your container registry. When this workflow completes, Nullstone will perform a deployment.

Before starting, make sure you do the following as well:

• Set NULLSTONE_ORG to your Nullstone organization.
• Add NULLSTONE_API_KEY to your repository secrets.

# .github/workflows/build-my-app.yml
name: Build my-app

on:
  workflow_dispatch:
    inputs:
      NULLSTONE_ORG:
        type: string
        description: 'Nullstone Organization'
        required: true
      NULLSTONE_STACK:
        type: string
        description: 'Nullstone Stack'
        required: true
      NULLSTONE_APP:
        type: string
        description: 'Nullstone App'
        required: true
      NULLSTONE_ENV:
        type: string
        description: 'Nullstone Environment'
        required: true
      NULLSTONE_VERSION:
        type: string
        description: 'Nullstone Version'
        required: true
      NULLSTONE_COMMIT_SHA:
        type: string
        description: 'Nullstone Commit SHA'
        required: true

env:
  NULLSTONE_ORG: ${{ inputs.NULLSTONE_ORG }}
  NULLSTONE_API_KEY: ${{ secrets.NULLSTONE_API_KEY }}
  NULLSTONE_STACK: ${{ inputs.NULLSTONE_STACK }}
  NULLSTONE_APP: ${{ inputs.NULLSTONE_APP }}
  NULLSTONE_ENV: ${{ inputs.NULLSTONE_ENV }}
  
jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          ref: ${{ inputs.COMMIT_SHA }}

      - name: Set up Nullstone
        uses: nullstone-io/setup-nullstone-action@v0

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      
      - name: Wait for app to be provisioned
        run: |
          nullstone wait --for=launched --block=${{ inputs.NULLSTONE_APP }}

      - name: Build Docker image
        run: |
          docker build -t my-app:latest .

      - name: Push Docker image
        run: |
          nullstone push --source=my-app:latest --app=${{ inputs.NULLSTONE_APP }} --version=${{ inputs.NULLSTONE_VERSION }}

Watch Workflow

If you don't configure Nullstone to initiate the build workflow, Nullstone will watch a GitHub Actions workflow triggered by GitHub.

Support and examples coming soon!