Open format: using GitHub Actions to work with Sketch documents

During this series, we’ve seen Monday Studio develop some tools to automate their workflow. In previous articles, we told you that it was possible to run these tools on many continuous integration services. Today we’ll show you how to do that on GitHub Actions, remotely and automatically.

Using GitHub Actions to run your design workflow automations means you don’t need to install anything on your computer. Everything runs automatically in the cloud when you send your updates to a shared repository. And if you ever need to make tweaks to your tools, you can do that using GitHub Codespaces — or other online code editors that run entirely on your browser, like Visual Studio Code.

Using GitHub Actions means faster onboarding for new team members, less TCO, less friction and fewer version compatibility issues with developer tools. Everything runs from the same, centralized source of truth. As a bonus, it’s quick and easy to integrate with existing workflows and tools.

Using GitHub Actions to run your design workflow automations means you don’t have to worry about dependencies and maintenance of your development environment. Plus, you can edit and run that code everywhere, enabling a true multi-platform workflow.

Requirements

You only need a device with a browser to follow along with this article. In fact, to give you an idea of what we mean when we say this is a multi-platform approach to running automations, you can even complete all the steps below using a smartphone.

What we’ll build

Today we’re not going to build anything. We’ll revisit the repositories for all the tools we’ve built in the series, and take a look at their .github/workflows folders.

For all these projects, you’ll see a YAML file that looks roughly like this:

name: Name of the action we're running

on:
  # Instructions about *when* to run this automation
  ...

jobs:
  # Instructions about *what* to run in this automation
  ...

We’ve set up the repositories as Public Templates on GitHub. You can click the “Use this template” button on the home page of each repository to make your own editable copy of the project:

When to run our Actions

Generally speaking, we want our automations to run whenever the code changes. We can specify that with this code, that tells GitHub Actions to run this action when we push code to the main branch or open a pull request that targets it:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

Sometimes you’ll want to limit the scope of actions to specific files. There’s an example of this in our Sketch to JSON automation. The action will only run when we modify the JSON file where we define the colors of our library:

on:
  push:
    paths:
      - colors.json
      - .github/workflows/**.yml
    branches: [main]

Automatically running Actions is very satisfying. But sometimes you need to run an Action manually — especially when debugging it. To do this, you can add a workflow_dispatch: item to your on: section:

on:
  push:
    ...
  pull_request:
    ...
  workflow_dispatch:

That will enable a button on GitHub’s website that you can press whenever you need to run the action:

The button even works on the mobile version of GitHub, so you can run your automations while you’re taking a walk in the park!

What to run in an Action

Once we’ve defined when we want to run an Action, it’s time to specify what the Action is going to do. For any of the projects in this series, the answer is always the same — we want GitHub Actions to run yarn start to run the code in the project.

Before we can do that, we need to tell the server that’s running our action a few things about our ideal working environment (the version of node we want to use, etc…). If you take a look at the code in .github/workflows for any of our projects, you’ll see something like this:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      ...
      - name: Install node
        uses: actions/setup-node@v2
        with:
          node-version: 14.16
      - name: Install dependencies
        run: yarn install
      - name: Update Sketch Library
        run: yarn start
      ...

In short, this tells GitHub Actions we want to use a Linux server (Ubuntu, in this case), install version 14.16 of the node runtime, and run yarn install on our project.

Closing the loop

Now that we know how to make GitHub Actions run the code in our projects, we probably want to gather the fruits of our work and store the output somewhere. There are different ways we can do this, but two are especially useful — committing the changes back to our repository and storing the assets as Artifacts on the Actions page on GitHub.

Committing your changes

If the output of our project is something we want to store in the repository, along with the rest of our files, our best bet is to commit the result of running the Action. This is as simple as adding this as the last step on our workflow file:

      - name: Push changes in Sketch Library
        uses: actions-x/commit@v2
        with:
          email: developer@sketch.com
          name: Sketch Developer
          files: color-library.sketch

Running the Action will commit any file listed in the files: section to your repository. You can modify the commit message, or even push the changes to a different repository. Check the documentation for actions-x/commit for more information.

Storing Action Artifacts

If the resulting files are too big, or you don’t want them to pollute the history of your project, you can store them as Artifacts on GitHub Actions. Anyone who visits the page can download these Artifacts. To do this, the last step of your Action should look like this:

      - uses: actions/upload-artifact@v2
        with:
          name: Material Design Icons - Sketch Library
          path: material-design-icons.sketch

Now, whenever an Action runs, the files specified in the path: section will be available in the Artifacts section of the Action on GitHub’s website:

Check the documentation for actions/upload-artifact for more information.

Final words

In this article, we’ve covered how to use GitHub Actions to run your Sketch automations from the cloud. We hope you’ve enjoyed this series, and that you can use this knowledge to come up with new ways to make your design process better, easier and reduce friction.

As always, let us know if you’ve made something great. We’d love to hear from you!