Blog product

November 14, 2024

Spin gh - Generate GitHub Actions for your Spin Apps in seconds

Thorsten Hans

spin GitHub Actions gh plugin

We are thrilled to announce the first release of the Spin gh plugin! As all developers, we spend considerable time automating tasks using continuous integration or other types of centralized builds. To dramatically simplify this in the context of Spin applications, we sat down and wrote the gh plugin. A simple, yet powerful plugin which is able to generate GitHub Actions for your Spin applications.

What Is Spin

Spin is the open source developer tool for building WebAssembly applications. Spin comes with batteries included to build reactive WebAssembly applications (we often call them Spin apps). Spin is language-agnostic, so you can choose from a wide range of programming languages to build your Spin apps. Spin guarantees portability across different operating systems and architectures, strict sandboxing, and incredible sub-millisecond cold start times. Check out the project documentation to dive deeper into Spin.

What Is a Spin Plugin?

With Spin plugins, one can add new sub-commands and capabilities to Spin without modifying the code base of Spin itself. Spin plugins can be submitted to the central Spin Plugins Repository, which allows users to discover and install them using the spin plugins list and spin plugins install commands. For example, we recently had a community contribution for a Kinesis trigger plugin. Because Spin plugins have their own lifecycle, they can be developed and released independently of Spin, with updates being installed by running spin plugins update (to update the Spin plugin feed) and spin plugins upgrade <plugin-name> (to upgrade a particular Spin plugin).

How to Install the Spin gh Plugin

Because the gh plugin has been submitted to the Spin Plugin Repository, you can install the gh plugin using the following commands:

# Update the list of Spin plugins
spin plugins update

# Install the gh Spin plugin
spin plugins install gh

Once the gh plugin has been installed, you can start generating GitHub Action workflow files for your Spin apps. Before we jump right into using the gh plugin, let’s quickly take a look at all its capabilities.

What the gh plugin can do for you!

Generating a GitHub Action by simply executing a one-liner is cool, but there are plenty of capabilities that may not be that obvious in the first place. See the following list of things the gh plugin does when generating a GitHub workflow for you:

• Recursively examine the current directory and discover all Spin apps and their respective components
• Identify all the different programming languages used
• Identify which plugins are required to compile your source code down to WebAssembly
• Render a GitHub Action Workflow, which
  • Creates a workflow trigger (customizable)
  • Installs the latest Spin version (customizable)
  • Installs Spin plugins (customizable)
  • Set individual workflow environment variables
  • Installs all language-specific tooling
  • Pin language and tool versions (customizable)
  • Builds each Spin App discovered in the current directory tree

With the first release of the gh plugin, Spin apps built with Rust, JavaScript, TypeScript, GoLang and Python are supported. We’ll continuously add support for additional languages in the near-term future.

Using the spin gh plugin

Create a sample Spin App

For illustration purposes, you can use any existing Spin app or create a new one using spin new:

# Create a new Spin App using the http-js template
spin new -t http-js -a hello-spin

# Move into the hello-spin folder
cd hello-spin

Awesome! With your new Spin app in place, you can move on and start generating GitHub Actions.

Create GitHub Actions with spin gh create-action

We tried to come up with reasonable defaults to get you going as fast as possible while still allowing for common customization once you have the hang of things when generating new GitHub Actions.

Let’s start simple and do a dry-run (which will write the contents of the GitHub Action workflow file to stdout only):

# Generate a basic GitHub Action
spin gh create-action --dry-run

Discovered Spin App: hello-spin at .
 - JavaScript Component discovered at .

name: "CI"
on:
  push:
    branches:
      - "main"
env:
  NODE_VERSION: "22"
  SPIN_VERSION: ""
jobs:
  spin:
    runs-on: "ubuntu-latest"
    name: Build Spin App
    steps:
      - uses: actions/checkout@v4
      - name: Install Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "${{ env.NODE_VERSION }}"
      - name: Install Spin
        uses: fermyon/actions/spin/setup@v1
        with:
          plugins: js2wasm
      - name: Component Dependency Installation
        run: npm install
        working-directory: .
      - name: Build hello-spin
        run: spin build
        working-directory: .

Customize GitHub Action Triggers

As an additional example, let’s look at how you could alter the behavior of spin gh create-action to generate a GitHub Action using triggers other than CI for pushes on the main.

The easiest modification might be changing the branch from main to something else. This could be done using the --ci flag:

# Create an Action that runs for every push on my-awesome-branch
spin gh create-action --ci my-awesome-branch --dry-run

Discovered Spin App: hello-spin at .
 - JavaScript Component discovered at

name: "CI"
on:
  push:
    branches:
      - "my-awesome-branch"
# snip

Next, let’s add another trigger to ensure our GitHub Action also runs every night at 2am, using the cron trigger - which we can set using the --cron flag:

# Create an Action that runs for every push on my-awesome-branch and every night at 2am
spin gh create-action --ci my-awesome-branch --cron "0 2 * * *" --dry-run

Discovered Spin App: hello-spin at .
 - JavaScript Component discovered at

name: "CI"
on:
  push:
    branches:
      - "my-awesome-branch"
  schedule:
    - cron: "0 2 * * *"
# snip

These were just two samples to illustrate how you can customize the gh to generate GitHub Action according to your needs.

There are even more customization options baked into the gh plugin. Check out the project README to learn more about all of them.

Bring your own template

Are you managing many Spin Apps? Or, do you want some topping that is not part of the default template used to generate the GitHub Action?

No problem! You can create your own template for generating GitHub Actions with the spin gh create-action command. You don’t have to start from scratch here, you can use the spin gh eject command and use our default template to jump-start yours!

# Store the default template in a file
spin gh eject --output ./my-gh-actions-template.yaml --overwrite

With a tailored template in place, you can invoke spin gh create-action and point to your template using the --template flag, as shown in the snippet below:

# Create a GitHub Action using a custom template
spin gh create-action --name custom-ci --template ./my-gh-actions-template.yaml

If you’re building your own template, you should definitely consider browsing through the project README to discover all the data being passed to the template upon rendering the GitHub Action workflow file.

Let us know what you think about the plugin on our Discord.

If you encounter bugs, would like to see new features, or would like to examine the source code, feel free to visit the repository on GitHub.