Forem: rob

Generating Reports in Figma with a Custom Figma Plugin

rob — Sat, 29 Feb 2020 02:30:00 +0000

Recently, I took on a project that involved building a Figma plugin to generate a property pitch report from data about a property collected by employees, mostly aggregated on a central Wordpress instance. For the unfamiliar, Figma is a neat web-based tool for collaborative design, featuring a very robust set of APIs, which made choosing it for automating the property pitch report process a pretty obvious one.

In this post I'll write about approaching the Figma plugin API and leveraging it to automate aggregating data from various sources to generate a baseline report that can easily be customized further! 🔌

Requirements
Implementation
- Figma Plugins Rundown
- Collecting Input and using React as our iframe
- Manipulating Figma Nodes and Working With the FigmaSandbox
Final Thoughts

Requirements

This plugin would have to be able to:

retrieve basic data collected by employees from our Wordpress instance
download images, generate maps, and retrieve miscellaneous assets from various sources to augment the report
splat all this data onto a Figma document in an attractive, organized manner

As far as implementation goes, this posed a few problems when using Figma Plugins - read on for more details!

Implementation

Figma Plugins Rundown

To start off I am going to give a quick overview of how Figma Plugins work. This is also covered in "How Plugins Run" from the official documentation,
but for some reason it still took me quite a while to figure things out, so I'll explain it slightly differently here:

Sometimes the FigmaSandbox is referred to as the "main thread", and the iframe is also called a "worker".
The "why" of this setup is explained in the official documentation:

For performance, we have decided to go with an execution model where plugin code runs on the main thread in a sandbox. The sandbox is a minimal JavaScript environment and does not expose browser APIs.

That means that you'll have two components to your plugin: a user interface that has code that runs in the iframe, which also handles any browser API usage (any network requests, the DOM, and so on), while any code that does the actual work of handling interactions with Figma (reading layers, manipulating nodes, setting views, and so on) runs in an entirely separate FigmaSandbox. The only way these two can communicate is through message passing via the Figma plugin framework, as described in the above diagram.

This means that to build this thing, we'd either have to:

front-load everything in the iframe before passing everything onto the FigmaSandbox - this would require knowing all such dependencies beforehand, and passing a lot of information around
do some ping-ponging between the iframe and FigmaSandbox, where each page we generate can declare its own dependencies and fetch them appropriately

Structuring Our Plugin

We ended up going with the second option, which lended itself to a more compartmentalized approach, as outlined below:

The following sections cover the iframe and the FigmaSandbox and the outside world in more detail, complete with examples!

Collecting Input and using React as our iframe

I started off using a template I found, nirsky/figma-plugin-react-template, which I quickly forked and made a variant of for my own preferences (mostly related to tooling and styles), which you can find at bobheadlabs/figma-plugin-react-template.

The template sets up the iframe part of our plugin as a Typescript-based React application, which is handy because Figma provides an API typings file that saved me a lot of time. Inputs in the template are collected in standard React fashion with some hooks:

const projectIDInput = React.useRef<HTMLInputElement>(undefined);
const projectIDRef = React.useCallback((element: HTMLInputElement) => {
  projectIDInput.current = element;
}, []);

And later, in your JSX:

<p>Project ID: <input ref={projectIDRef} /></p>

There are a number of ways to do this, so just use whatever you prefer! Once you've collected your parameters, as denoted in above diagrams, when the user kicks off the report generation process we can fire a messsage to the FigmaSandbox via parent.postMessage:

const onSubmit = React.useCallback(() => {
  parent.postMessage({ pluginMessage: {
    type: actions.LoadProject,
    // ... other params
  } }, '*');
}, []);

To enable bidirectional message passing (in our case, to enable asset loading on the fly), we'll need to hook onto incoming messages to the iframe via window.onmessage:

React.useEffect(() => {
  window.onmessage = async (event) => {
    const { pluginMessage } = event.data;
    const { type } = pluginMessage;
    try {
      switch (type) {
      /**
       * handle your plugin's various action types - these handlers can also use
       * `parent.postMessage` to pass results back to the FigmaSandbox!
       */
      }
    } catch (err) {
      console.error(type, { err });
    }
  }
}

Remember that browser API access requires being in the iframe, so any network requests and so on should probably happen in one of these window.onmessage handlers.

Manipulating Figma Nodes and Working With the FigmaSandbox

Similar to the iframe, the first step is to listen for messages, this time via figma.ui.onmessage:

figma.showUI(__html__, { height: 300 }); // https://www.figma.com/plugin-docs/manifest/
figma.ui.onmessage = async (msg) => {
  const { type } = msg;
  try {
    switch (type) {
    /**
     * handle your plugin's various action types - remember to make use of the figma API with the
     * `figma` object, and use `figma.ui.postMessage` to send messages back to the iframe!
     */
    }
  } catch (err) {
    console.error(err);
    figma.closePlugin(`Error occured: ${err}`);
  }
};

Since we have no UI component in the FigmaSandbox, this code can just be plain Typescript.

Unlike the iframe, the actual Figma API is accessible to the plugin here via the figma object. For example, to set up an A4-sized frame for each page and set your view onto them:

for (let i = 0; i < pages.length; i += 1) {
  const { name, template } = pages[i];

  // set up frame for this page
  const frame = figma.createFrame();
  frame.name = `Page ${i}: ${name}`;
  frame.resize(PAGE_A4.x, PAGE_A4.y);
  frame.y = i * (PAGE_A4.y + 100);

  // add frame to page
  figma.currentPage.appendChild(frame);
  newNodes.push(frame);

  // ...
}

// select new nodes and zoom to fit
figma.currentPage.selection = newNodes;
figma.viewport.scrollAndZoomIntoView(newNodes);

Working with nodes is pretty straight-forward: like any other graph-like structure, each node represents an element (in this case, an element on your Figma document), and attaching them to other nodes gives your elements a bit of structure. Each node exposes a variety of configuration options. For example, see the TextNode definition from the Figma API typings file:

interface TextNode extends DefaultShapeMixin, ConstraintMixin {
  readonly type: "TEXT"
  clone(): TextNode
  readonly hasMissingFont: boolean
  textAlignHorizontal: "LEFT" | "CENTER" | "RIGHT" | "JUSTIFIED"
  textAlignVertical: "TOP" | "CENTER" | "BOTTOM"
  textAutoResize: "NONE" | "WIDTH_AND_HEIGHT" | "HEIGHT"
  paragraphIndent: number
  paragraphSpacing: number
  autoRename: boolean
  // ...
}

Refer to the typings and official node types documentation to find out what you need!

Example: Declaring, Downloading, and Using an Image Asset

Recall from the earlier diagram that for our templates to declare asset dependencies, a bit of ping-ponging needed to happen between our iframe and FigmaSandbox components to make the appropriate network requests.

Here is an example of a simple template function (which is our way of organizing page generation - feel free to use whatever system suits you best!) that allows the declaration of some dependencies. Our interface is described as follows:

export type Asset = ImageAsset | MapAsset;

export type Assets = {[name: string]: Asset}

export interface Template {
  /**
   * Optional assets function allows templates to declare image dependencies. This callback should
   * return a set of URLs keyed by a useful identifier. If provided, hashes of loaded images will be
   * provided to Template.
   */
  assets?: (data: ProjectData) => Assets;

  /**
   * Calling a template should populate the given frame with this template. The `assets` argument is
   * only provided if `Template::assets` is declared.
   */
  (frame: FrameNode, data: ProjectData, assets?: {[name: string]: string}): Promise<void>;
}

Note that in the template function, assets is a simple key to string value dictionary, while in the assets property, the function returns Assets. This is because Figma images are referenced by a hash - once we have image data, it is easier to simply store the images in Figma first before passing the identifying hashes as values in the asset dictionary to the template function. For declaring assets, a bit more detail is needed - hence the Assets type.

Here's an example function:

async function template(frame: FrameNode, _: ProjectData, assets?: {[name: string]: string}) {
  // set up a simple coloured background via a helper function we made
  Background(frame, LIGHT_BEIGE);

  // create a rectangle to populate with our logo
  const imgN = figma.createRectangle();
  imgN.name = 'logo';
  imgN.fills = [{
    type: 'IMAGE',
    scaleMode: 'FILL',
    imageHash: assets.logo, // image hash for Figma, as described above
  }];
  // center our logo
  imgN.x = frame.width / 2 - imgN.width / 2;
  imgN.y = frame.height / 2 - imgN.height / 2;
  // add the logo to the frame
  frame.appendChild(imgN);
}
// declare a dependency on our logo
template.assets = (): Assets => ({
  logo: {
    type: AssetType.IMAGE,
    uri: `${env.wordpressInstance}/wp-content/uploads/2020/02/Dark-Full-LogoLarge.png`,
  },
});

In our FigmaSandbox message receiver, we'll have to check for asset dependencies before calling the template function:

if (template.assets) {
  // load assets if provided and let main runtime dispatch template load
  figma.ui.postMessage({
    type: actions.LoadAssets,
    assets: template.assets(projectData),
    // used to re-establish context once we've loaded our assets
    frameID: frame.id,
    pageID: i,
    projectData,
  });
} else {
  // if no assets are provided, just load the template directly
  await template(frame, projectData);
}

Then, back over in the iframe message receiver, we'll want to retrieve these assets when requested:

export async function getImage(imageURI: string): Promise<Uint8Array> {
  const resp = await fetch(imageURI);
  // convert image data into Uint8Array to send back to FigmaSandbox
  const blob = await resp.blob();
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => resolve(new Uint8Array(reader.result as ArrayBuffer));
    reader.onerror = () => reject(new Error('Could not read from blob'));
    reader.readAsArrayBuffer(blob);
  });
}

switch (type) {
  case actions.LoadAssets: {
    const assets = pluginMessage.assets as Assets;
    const names = Object.keys(assets);
    // prepare to load all declared assets
    const loads = [];
    const loaded = {};
    for (let i = 0; i < names.length; i += 1) {
      const n = names[i];
      const ast = assets[n];
       const assetLoader = async () => {
        switch (ast.type) {
          case AssetType.IMAGE: {
            loaded[n] = await getImage(ast.uri);
            break;
          }
          // ...
        }
      }
      loads.push(assetLoader());
    }
    // await for all promises to resolve
    await Promise.all(loads);
    // send results back to the FigmaSandbox
    parent.postMessage({ pluginMessage: {
      ...pluginMessage, // retain context for the FigmaSandbox
      assets: loaded, // note that at this point, the values in assets is raw image data
      type: actions.AssetsLoaded,
    } }, '*');
  }
}

Now, back to the FigmaSandbox again (woo! ping pong!), we'll want to put all this image data straight into Figma to avoid moving all this raw data around, and generate our template!

// load up context
const frameID = msg.frameID as string;
const pageID = msg.pageID as number;
const projectData = msg.projectData as ProjectData;
const { name, template } = pages[pageID];

// add assets to figma and set up references
const assets = {};
Object.keys(msg.assets).forEach((n) => {
  const data = msg.assets[n] as Uint8Array;
  const imageN = figma.createImage(data);
  assets[n] = imageN.hash;
});

// execute template with loaded assets!
await template(figma.getNodeById(frameID) as FrameNode, projectData, assets);

For the example template, this back-and-forth results in a page that looks like this:

If you find this example hard to follow, try and read through it again and match it up against the plugin sequence diagram illustrated previously - each action should more or less align with the arrows on the diagram. It definitely took me a little while to get the hang of as well 😅

Final Thoughts

The Figma plugin documentation is quite robust (except for loading images and a good way to do the back-and-forth described in the above example, which I had to spend a good amount of time figuring out for myself), and feature-wise it's pretty comprehensive as well. If your team has any sort of design needs, I would highly recommend looking into automating some of your processes with Figma!

That said, it can be a bit of work to do seemingly trivial things (at least at first), but when you get the hang of things you can do some pretty cool tricks with it - I'll probably follow up this post with another one about the map generation work I am about to do!

As an aside: the charts in this post were created with Mermaid, which I recently (re)discovered - very nifty.

Make a GitHub Activity Chart with Rough.js

rob — Sat, 09 Nov 2019 21:26:42 +0000

So the other day I had a sudden, irresistible urge to make something using the Rough.js library, which lets you make gorgeously sketchy graphics. The urge probably originated from the fact that I had exams I was meant to study for.

Example squares from the Rough.js website!

I figured that since I've got a healthy amount of GitHub activity lying around, I might as well use this opportunity to put that activity to good use: by making a cute little chart of how much git commit I've been doing recently.

This is just a screenshot, but you can see the live version on my website.

To get started, you'll want to include Rough.js and d3 libraries somewhere in your header:

<script src="https://cdn.jsdelivr.net/npm/roughjs@3.1.0/dist/rough.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/d3/5.12.0/d3.min.js"></script>

And set up a div to populate with your chart:

<div id="canvas-container" height="150px">
  <canvas id="canvas"></canvas>
</div>

For contribution data, I opted to use the custom API used by
sallar/github-contributions-chart, which provides the contribution data in a nice and easy-to-use format (it does not seem like GitHub offers an official way to get the data in a format like this):

{
   "years":[ /* yearly summaries */ ],
   "contributions":[
      // ...
      {
         "date":"2019-11-03", // future days are included with "count": 0
         "count":0,
         "color":"#c6e48b",
         "intensity":0
      },
      {
         "date":"2019-11-02",
         "count":12,
         "color":"#c6e48b",
         "intensity":1
      },
      {
         "date":"2019-11-01",
         "count":1,
         "color":"#c6e48b",
         "intensity":1
      },
      {
         "date":"2019-10-31",
         "count":6,
         "color":"#c6e48b",
         "intensity":1
      },
      {
         "date":"2019-10-30",
         "count":33,
         "color":"#7bc96f",
         "intensity":2
      },
      // ...
   ]
}

Here's the entire snippet, edited slightly for brevity and with comments added explaining what is going on:

const user = 'bobheadxi';
function drawChart() {
  // start off by requesting contribution data
  return fetch(`https://github-contributions-api.now.sh/v1/${user}`)
    .then((resp) => resp.json()) // turn that request data into JSON
    .then((data) => {
      // figure out what our current dimensions are - I chose to always let the
      // height be the same
      const maxWidth = document.getElementById('canvas-container').clientWidth;
      const maxHeight = 150;

      // force the canvas to fill the container
      const canvas = document.getElementById('canvas');
      canvas.width = `${maxWidth}`;
      canvas.height = `${maxHeight}`;

      // the API provides a bunch of zeroes for days in the future, (see the
      // sample data above) so I strip leading zeroes out. this also has the
      // "benefit" of not showing recent inactivity on your generated chart ;
      //  you could probably improve this by actually figuring out which entry
      // corresponds to the current date, but I was too lazy
      let firstNonZero = 0;
      for (let i = 0; i < data.contributions.length; i++) {
          if (data.contributions[i].count > 0) {
              firstNonZero = i;
              break;
          }
      }

      // based on the width, calculate how many days of activity to show so that
      // we get nice-looking bars to fill the space
      const barWidth = 8;
      const barGap = barWidth / 4;
      const days = Math.floor(maxWidth / (barWidth + barGap));

      // get the most recent days (as we just calculated) and turn the array of
      // contributions objects into an array of numbers, then reverse it to get
      // the most recent ones first.
      const counts = data.contributions
        .slice(firstNonZero, firstNonZero+days)
        .map(c => c.count)
        .reverse();

      // get the max so we can scale the bars to kind of fill the height
      const max = d3.max(counts);
      const heightFlex = maxHeight / (max + 4);

      // get your canvas, and iterate over the data to draw in the bars. in
      // hindsight, the load time can probably be improved by merging this with
      // the array manipulations earlier. as textbook authors like to say,
      // "we'll leave this as an exercise for the reader".
      const rc = rough.canvas(canvas);
      counts.forEach((d, i) => {
        // calculate appropriate dimensions for this bar. we want to position
        // the bars with a bit of a gap to avoid having the canvas crop out the
        // "sketchy" rectangle borders (hence the +1 and -1), and give each bar
        // a bit of space to flex their sketchiness.
        const barHeight = heightFlex * d;
        const dim = {
            x: i * (barWidth + barGap) + 1,
            y: maxHeight - barHeight - 1,
            w: barWidth,
            h: barHeight,
        };
        // I choose green because GitHub uses green, but you can adjust this
        // as you wish!
        rc.rectangle(dim.x, dim.y, dim.w, dim.h, { fill: 'green' });
      });
    })
    .catch((err) => console.error(`chart generation error`, { err }));
}

// draw the chart on page load and scale it when the window size changes!
window.onload = drawChart;
window.onresize = drawChart;

It's not the fastest thing in the world and could probably do with a lot of improvement, but it works for now!

Branch Previews with Google App Engine and GitHub Actions

rob — Sat, 09 Nov 2019 19:20:00 +0000

⚠️ WARNING: Please make sure you pin usages of bobheadxi/deployments to a specific version! The usage examples in this article may not be up to date - please see the Action usage docs for more details: GitHub Deployments Action

Shortly after I returned to school, early in October 2019 I started
working part-time remotely for Sumus, a property management company based out of Lethbridge, Alberta. My role was primarily as a software developer on a investor portal they wanted to build. I wasn't starting from scratch - there was already a sizeable codebase going, and a simple deployment set up on Google App Engine.

Right off the bat I had a number of tech-debt-related issues I wanted to address before I started developing new features, one of which was automating this deployment process. App Engine does not seem to have a great way of doing this outside of using their source control, so I decided to do this myself.

As I progressed on the automation of the App Engine deployment,
I realized branch previews were not that much more of a hassle to set up, so I got those up and running as well - Heroku has a nice article about why staging environments are nice to have. This blog post will cover some of the work I did on this front, and hopefully give a good idea about how you can go about creating a similar setup for your own projects if you want. Our project consists of a React frontend serviced by a Node.js backend, so my post will lean a bit towards that particular setup, but should apply to a variety of different stacks.

Here's a sneak peak of the end result:

The Problem
Solution
- Staging and Release
- Versioning Frontends and Backends
- Automation
- GitHub Actions + App Engine
- GitHub Deployments
Wrapup

The Problem

First off, a quick intro to App Engine. This was my first encounter with App Engine, so this won't be the best rundown, but in a nutshell App Engine seems like a reasonably priced way to deploy your application in a serverless fashion with the flexibility to scale to your needs. It also offers nice out-of-the-box integration with Google's other monitoring offerings, which is a nice plus.

Most of the official documentation seems to indicate that deployment happens primarily through:

defining an application specification, the app.yaml
using the gcloud CLI to push a deployment out from your copy of the codebase

The old process for deploying our application involved making sure I had all my credentials and stuff set up, and running:

gcloud app deploy app.yaml

There was no real way short of making sure I wasn't axing someone else's
deployment or notifying everyone of what is currently active short of shooting a Slack announcement and hoping it's seen and handled appropriately. I felt like
the entire process would be more comfortable if it was automated and tied to source control, so that:

permissions are easier to manage as the team grows
it's easier to tell what is deployed, and where
less work to continuously update and manage deployments

Solution

I didn't actually start off with leveraging GitHub Actions for automating this process - my first iteration used CircleCI, where we run our tests, style checks, and and so on. This had the advantage of allowing me to stage deployments based on whether or not previous checks pass:

Unfortunately this was eating up a huge chunk of our pipeline minutes - as you can see in the image above, the appengine_stage job takes more than 97% of each build when a branch is configured to stage. This brought us uncomfortably close to hitting the CircleCI free tier, so I ended up moving it to GitHub Actions to split up our workloads.

Staging and Release

I first ran into the concept of branch previews working on the UBC Launch Pad website, where we leveraged Netlify's great branch preview feature. It was a fantastic way to do some live testing and get feedback quickly, so I leveraged branch previews again during my time with nwPlus working on the nwHacks 2019 website, where I used a tool I worked on, ubclaunchpad/inertia, to quickly stage previews for the nwPlus design team to provide feedback on.

Now that I'm back to working on websites, I figured branch previews would come in useful here again (and they have so far!). To accomodate this, I introduced some extra steps to our deployment flow:

Staging deployments are primarily for previewing branches. By default, the only staged branch would be master, but additional branches can be staged by adding the desired branch to the GitHub Action configuration. These deployments are named based on their branch, i.e. stage-master or stage-my-branch.
Release deployments are for deploying tags. These deployments are promoted (unlike the staging deployments) such that all traffic to the application route to the most recent release deployment by default. These are named based on their tag, i.e. release-v0-3-0.

Versioning Frontends and Backends

A bit of a conundrum when deploying multiple versions of a multi-component service is making sure that they talk to the correct instances - for example, a branch preview deployment probably does not want to have its frontend talk to the backend of a different deployment if you are trying to demonstrate a new feature.

For service-to-service deployments, this is fairly straight forward - App Engine provides a variety of default environment variables you can use to interpret the appropriate backend to talk to. We can take advantage of how App Engine addresses un-promoted deployments:

https://${version}-dot-${project}.appspot.com # unpromoted
https://${project}.appspot.com                # promoted

In a multi-service setup, you also get an additional ${component} piece attached to the address:

https://${version}-dot-${component}-dot-${project}.appspot.com # unpromoted
https://${component}-dot-${project}.appspot.com # unpromoted

Then, following by using a "versioning" scheme of version=branch_name, we can easily determine where the desired service should be located, and point our requests to the correct address.

The only hurdle to this is for frontends. We have to know the version at buildtime, which sadly App Engine's default build feature does not provide, so you'll have to either:

generate a .env file to be consumed at build time and upload it with your build
build in CI with the appropriate variables

The latter is probably best practice anyway, since you want to optimize your App Engine setup for fast instance start times, but in case you are running your builds in App Engine (our deployments were previously) this is a minor hurdle to be aware of.

Automation

GitHub Actions + App Engine

GitHub Actions is a pretty new product, which I guess is probably GitHub's answer to GitLab's CI/CD features. I've come to like it a lot more for anything outside of running your tests and whatnot, since it has a lot of interesting hooks and triggers based on normal GitHub activity that you can leverage, but for this example I won't be using many of those. If you're following along you might want to consult the official workflow syntax documentation.

Anyway, to get started I set up a staging workflow:

# .github/workflows/appengine-stage.yml
name: appengine-stage
on:
  push:
    branches:
    - master
    # insert branches to stage here

All I really want to do here is declare what branches I want to stage, and make staging additional branches just a matter of adding it to the configuration in your PR (and removing it when you're done). I'm thinking of using PR labels for this, but haven't figured out a good way to do it yet.

The first step is to actually grab your branch name. GitHub only provides you with the commit's reference, which takes the form of:

refs/heads/${branch_name}

So we'll want to extract it with a script:

steps:
- name: Extract branch name
  id: get_branch
  shell: bash
  run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/} | tr / -)"

There's a couple of things going on here:

[set-output name=branch;] uses GitHub Actions' ability to set an output for a step to allow other steps to access the extracted branch
${GITHUB_REF#refs/heads/} trims off the leading refs/heads/ bit of a reference
echo ${...} | tr / - pipes the branch name to tr which then replaces all slashes with dashes (App Engine does not allow slashes in version names, and I have a habit of using them)

Then, in other steps you can access the branch name like so:

stage-${{ steps.get_branch.outputs.branch }}

All that's really left to do is run the deployment.

- uses: actions-hub/gcloud@268.0.0
  env:
    APPLICATION_CREDENTIALS: ${{ secrets.GCLOUD_SERVICE_KEY }}
  with:
    args: app deploy client/app.yaml server/app.yaml --no-promote --quiet --version stage-${{ steps.get_branch.outputs.branch }}

The release workflow is very similar, except it runs on releases and generates version names based on the tagged version:

# .github/workflows/appengine-release.yml
name: appengine-release
on:
  release:
    types: [ published ]
jobs:
  release:
    # ...
    steps:
    - name: Extract tag name
      id: get_tag
      shell: bash
      run: echo "##[set-output name=tag;]$(echo ${GITHUB_REF#refs/tags/} | tr . -)"

I also have a separate workflow for pruning previews. Since previews are typically set up for pull requests, the prune job runs when pull requests close (ideally it should be on branch deletion, but there doesn't seem to be a simple trigger for that at the moment):

# .github/workflows/appengine-prune.yml
name: appengine-prune
on:
  pull_request:
    types: [ closed ]
jobs:
  prune:
    # ...
    steps:
    # ...
    - uses: actions-hub/gcloud@268.0.0
      env:
        APPLICATION_CREDENTIALS: ${{ secrets.GCLOUD_SERVICE_KEY }}
      with:
        args: app versions delete stage-${{ steps.get_branch.outputs.branch }} --quiet

GitHub Deployments

As a bit of a stretch goal, I wanted to be able to see the deployments within the GitHub UI, just like with the Netlify branch previews. For example:

There's another example of this at the top of this article. It's mostly a small quality of life thing, but the more I thought about it the more I wanted it so...

Anyway, this feature is called "GitHub Deployments". I tried a bunch of available Actions from the marketplace for working with this, but for some reason I couldn't really get any of them to work the way I wanted, which is to:

create a new deployment
set a status for it
change that deployment's status
replace the previous deployment's status

I was probably holding them all wrong, but after a few hours I just went ahead and wrote my own Action, bobheadxi/deployments, for doing exactly what I wanted. Then all I had to do was add a step before and after each of my workflows:

jobs:
  deploy:
    steps:
    - uses: bobheadxi/deployments@master
      id: deployment
      with:
        step: start
        token: ${{ secrets.GITHUB_TOKEN }}
        env: release-${{ steps.get_tag.outputs.tag }}
        transient: true
        desc: Setting up staging deployment for ${{ steps.get_tag.outputs.tag }}
    # ... as before
    - name: Update deployment status
      uses: bobheadxi/deployments@master
      if: always()
      with:
        step: finish
        token: ${{ secrets.GITHUB_TOKEN }}
        status: ${{ job.status }}
        env: ${{ steps.deployment.outputs.env }}
        env_url: https://release-${{ steps.get_tag.outputs.tag }}-dot-project.appspot.com
        deployment_id: ${{ steps.deployment.outputs.deployment_id }}

For pruning, I needed to be able to go and deactivate all deployments associated with the preview environment. Since I owned the action I just added the feature.

- uses: bobheadxi/deployments@master
  with:
    step: deactivate-env
    token: ${{ secrets.GITHUB_TOKEN }}
    env: stage-${{ steps.get_branch.outputs.branch }}
    desc: Deployment was pruned

And that was it! As a bonus, notifications for these deployments show up in Slack via the GitHub integration:

Wrapup

There's definitely a bunch of caveats in this approach, and if the resources are available to you it might be easier to use a platform like Heroku to do all this hard work for you. That said, this was a fun hack and has made staging previews for the team to assess and rolling out releases a lot safer-feeling and less of a hassle.