Samuel Meuli – Blog

Finding and Auto-fixing Lint Errors with GitHub Actions

Thu, 27 Feb 2020 00:00:00 +0000

Using GitHub Actions to enforce clean code in JavaScript, Python, Ruby, Go and Swift projects

Linters are important tools for detecting potential errors and maintaining a consistent code style in a project. Unfortunately, it can happen that a contributor creates commits without running the linter first and that style violations are merged.

To make sure that contributions are linted, the code analysis can be performed as part of a CI pipeline. Merging can even be blocked as long as linting errors are unresolved.

With Actions, GitHub launched their own CI service last year. By setting up my Lint Action, GitHub Actions can be used to lint code whenever a change is pushed. The action not only shows the lint result on commits and PRs but also creates inline code annotations for each linting error:

These annotations, together with the action’s auto-fix feature, make it easy for both maintainers and contributors to keep the code style in a repository consistent.

Using the Lint Action

To enable the Lint Action in your repository, create a GitHub Actions workflow in the .github/workflows/ directory (e.g. named lint.yml). The file should use a structure similar to the following:


		.github/workflows/lint.yml

name: Lint

on: push

jobs:
  run-linters:
    name: Run linters
    runs-on: ubuntu-latest

    steps:
      - name: Check out Git repository
        uses: actions/checkout@v2

      # TODO: Install your linters here

      - name: Run linters
        uses: samuelmeuli/lint-action@v1
        with:
          github_token: ${{ secrets.github_token }}
          # TODO: Enable your linters here

The Lint Action supports linters and formatters for a variety of programming languages:

CSS (stylelint)
Go (gofmt, golint)
JavaScript (ESLint, Prettier)
Python (Black, Flake8, Mypy)
Ruby (RuboCop)
Swift (SwiftFormat, SwiftLint)

Furthermore, the action can easily be extended to support other languages and tools. A contributing guide can be found here.

Showing Lint Errors on Commits/PRs

For the Lint Action to work, you first need to install the linters you wish to use on the virtual machine. The following example shows how this is done for Python. Code is linted with Flake8 and formatted with Black:


		.github/workflows/lint.yml

  name: Lint

  on: push

  jobs:
    run-linters:
      name: Run linters
      runs-on: ubuntu-latest

      steps:
        - name: Check out Git repository
          uses: actions/checkout@v2

-       # TODO: Install your linters here
+       - name: Set up Python
+         uses: actions/setup-python@v1
+         with:
+           python-version: 3.8
+
+       - name: Install Python dependencies
+         run: pip install black flake8

        - name: Run linters
          uses: samuelmeuli/lint-action@v1
          with:
            github_token: ${{ secrets.github_token }}
-           # TODO: Enable your linters here
+           black: true
+           flake8: true

The approach is the same for other programming languages and linters. You can find more examples in the action’s docs.

Viewing Lint Results

Every time somebody pushes to your repository, the action will now lint the project. Using GitHub’s Check Runs API, the commit will be annotated with the lint result. You can even inspect the specific lines of code where style violations were found.

If the commit is part of a pull request, GitHub will automatically pick up the latest check and display it in a user-friendly way, showing the committer or maintainer whether the PR requires further inspection before a merge can be made:

Auto-fixing Errors

Besides showing lint errors, the Lint Action can also fix some of the issues automatically. This is done by running the linter commands with the corresponding auto-fix arguments and creating a bot commit of the changed files.

Setting up auto-fixing is easy: All you need to do is set the action’s auto_fix option to true.

The auto_fix value can also be determined dynamically using GitHub Actions’ expression syntax. For instance, you might not want any auto-fix commits on your master branch. To only create such bot commits on PR branches, you can configure the action as follows:


		.github/workflows/lint.yml

  name: Lint

- on: push
+ on: [push, pull_request]

  jobs:
    run-linters:
      name: Run linters
      runs-on: ubuntu-latest

      steps:
        - name: Check out Git repository
          uses: actions/checkout@v2

        - name: Set up Python
          uses: actions/setup-python@v1
          with:
            python-version: 3.8

        - name: Install Python dependencies
          run: pip install black flake8

        - name: Run linters
          uses: samuelmeuli/lint-action@v1
          with:
            github_token: ${{ secrets.github_token }}
+           auto_fix: ${{ github.event_name == 'pull_request' }}
            black: true
            flake8: true

Please note that GitHub Actions currently has limitations with pull_request events triggered by forks. See this issue for details.

Making Checks Mandatory

After your checks have run for the first time, you can choose to make them a requirement for pull requests and block merging while there are linting errors. You can configure this in your repository settings under “Branches” → “Add rule” → “Require status checks to pass before merging”.

]]>

Notarizing Your Electron App

Sat, 28 Dec 2019 00:00:00 +0000

A guide on notarizing Electron apps for macOS with electron-builder

With the release of macOS Catalina (10.15), Apple made app hardening and notarization mandatory for apps distributed outside the Mac App Store.

Like app sandboxing, the Hardened Runtime is a security feature that restricts your app from utilizing certain system features. Exceptions can also be defined using code signing entitlements.

Notarization is an automated security check by Apple, which involves their servers scanning your app for malicious content and code signing issues. App notarization requires your app to use the Hardened Runtime.

Thankfully, hardening and notarizing Electron apps has become a pretty simple process. This tutorial assumes that you’ve already set up electron-builder in your project. The build tool can be configured to harden your app for you, and the electron-notarize and electron-builder-notarize packages can take care of notarizing your app:

electron-builder builds and signs your app to use the Hardened Runtime
electron-notarize wraps Apple’s altool CLI and uses it to notarize your app
electron-builder-notarize wraps electron-notarize and simplifies its usage with electron-builder

App Configuration

To get started, install electron-builder-notarize in your Electron app:

yarn add --dev electron-builder-notarize

To get notarization to work, add the following options in your package.json file:


		package.json

{
	"build:": {
		"afterSign": "electron-builder-notarize",
		"mac": {
			"hardenedRuntime": true
		}
	}
}

Next, create or update your build/entitlements.mac.plist file with the following code signing entitlements, which are required for Electron to work:


		build/entitlements.mac.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
	<dict>
		<key>com.apple.security.cs.allow-jit</key>
		<true/>
		<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
		<true/>
		<key>com.apple.security.cs.allow-dyld-environment-variables</key>
		<true/>
	</dict>
</plist>

Authentication

Now, you’ll want to give electron-builder-notarize permission to notarize your app. A secure way to do so is using the App Store Connect API.

Sign in to App Store Connect and open the API key page
Create a new API key by clicking on the “+” symbol. Set access permissions to “App Manager”
Download the key file and move it into the ~/private_keys/ directory, where altool will be able to find it
Copy your Issuer ID (1) and Key ID (2):

Notarization

If you pass the credentials you just copied as environment variables to electron-builder, your app should be built and notarized successfully:

API_KEY_ID="..." API_KEY_ISSUER_ID="..." yarn run electron-builder --mac

Please note that the notarization process might take a few minutes.

To avoid your API information being visible in the terminal history, you can use a package like dotenv to read your environment variables from a file instead.

Sources

]]>

Automating the Release of Electron Apps

Sun, 17 Nov 2019 00:00:00 +0000

Using GitHub Actions to automatically build and release your Electron app for macOS, Windows and Linux

One major advantage of building desktop apps with Electron is that your app works on multiple platforms with a single codebase. Unfortunately, there are some challenges in building an app for multiple operating systems:

Setting up and building your app on VMs is somewhat cumbersome
Mac apps can only be built on macOS, which not every developer has access to
Building Windows apps on other platforms has become more difficult with the release of macOS Catalina, which has dropped support for 32-bit apps and therefore breaks Wine

A nice way to solve such problems is to use the recently launched GitHub Actions, which allows you to run CI/CD workflows on multiple operating systems, including macOS, Windows and Ubuntu, which is exactly what you need for building Electron apps.

For this purpose, I created the Electron Builder Action. After setting up the action, your pipeline will automatically build your app on GitHub’s servers using electron-builder. When the action detects that you’ve tagged a commit with a version identifier, it can even release the packaged app for you.

You can read more about using the action here, and see an example of how it’s used in the repository of my Mini Diary Electron app.

]]>

Removing Dead Keys on macOS

Sun, 17 Nov 2019 00:00:00 +0000

A tutorial on re-mapping dead keys on macOS keyboard layouts

Depending on the macOS keyboard layout you’re using, you might have “dead keys”. A dead key represents a symbol that isn’t a full character and therefore isn’t immediately inserted into the text when typed. Examples of dead keys are ^, ` and ~. For instance, when typing ` followed by a, macOS will insert à instead.

For programmers, this behavior is often undesirable. For example, the tilde (~) is a useful shortcut for the $HOME shell variable, and the backtick (`) is used for template literals in JavaScript. Therefore, if you’re not using the symbols in your language, it might be preferable if these characters were inserted immediately when typed.

Fortunately, reconfiguring your keyboard layout to remove these dead keys is relatively easy. The Ukelele app can help you with this task:

Download and install Ukelele from its website or using brew cask install ukelele.
Open the Ukelele app.
In the application menu, select File → New From Current Input Source. This will detect your keyboard layout and create a copy that you can modify.
In the main window, Ukelele displays your layout with the dead keys highlighted in red. Right-click each of your dead keys, select the corresponding modifier key if necessary (e.g. the shift or option key) and enter the key’s value at the bottom of the dialog. This will change the key’s behavior to insert the symbol right away.
Once you’ve re-mapped all dead keys, save your keyboard layout and copy it to the ~/Library/Keyboard Layouts directory.
Reboot your Mac.
Open the System Preferences and navigate to Keyboard → Input Sources → +. Your custom keyboard layout can be found under the language it’s based on. You can now add your new keyboard layout and activate it from the menu bar.

]]>

Publishing an Electron App on the Mac App Store

Tue, 09 Apr 2019 00:00:00 +0000

Having your Electron app on the Mac App Store makes it simpler for users to discover and download your app. This guide explains how to get your app listed

I went through this process when publishing Mini Diary. electron-builder's docs aren’t great and existing tutorials are overly complicated or outdated. This guide aims to provide simple and comprehensive instructions on how to publish an app on the Mac App Store.

Important: This tutorial assumes that you have followed all steps outlined in the previous post on packaging and publishing Electron apps.

1. `electron-builder` Configuration

To generate a package for the Mac App Store every time you run your build script, extend the electron-builder configuration in your package.json file by the following settings:


		package.json

{
	"build": {
		"mac": {
			"target": ["dmg", "mas", "zip"],
			"electronLanguages": ["en"]
		}
	}
}

The "mas" key in the "target" array configures electron-builder to build your app for the Mac App Store (MAS) in addition to the default formats. Specifying "electronLanguages" affects which languages are shown on your app’s MAS page. If you don’t set this parameter, a long list of different languages will be displayed by default. You can find the language keys of the different locales in the Electron docs (make sure you replace hyphens with underlines).

2. App ID

Next, your MAS app needs an App ID. You can generate one in the Apple Developer Portal. App IDs are usually of the form com.yourcompany.yourapp. This App ID needs to be the same as the one you specified in your package.json file under the build.appId key.

3. Entitlement Files

All apps distributed on the Mac App Store need to be sandboxed. As the developer of such an app, you need to specify the privileges that your app needs to function, and macOS will prevent it from using any other system functionality.

To specify the privileges required by your app, create the following file in your project’s build folder:


		build/entitlements.mas.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.security.app-sandbox</key>
	<true/>
	<!-- Add entitlements here -->
</dict>
</plist>

Now, add all entitlements your app needs to this file (see Apple’s docs for possible entitlements). The simplest way to do so is using Xcode. For example, if your Electron app needs to be able to read specific files using an open dialog, your entitlements file should look like this:


		build/entitlements.mas.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.security.app-sandbox</key>
	<true/>
	<key>com.apple.security.files.user-selected.read-only</key>
	<true/>
</dict>
</plist>

If you’re also distributing your app outside the Mac App Store and intend to sandbox that version as well, create a file named entitlements.mac.plist in the build directory with the same content as the entitlements.mas.plist file.

4. Provisioning Profile

Navigate to the “Profile” section of the Apple Developer Portal. Create two provisioning profiles for your app: A “Mac App Development” and a “Mac App Store” provisioning profile. Download the two files and make sure you remember which one is for development and which one is for production (e.g. by naming them dev.provisionprofile and prod.provisionprofile).

5. Testing

Development

To test the MAS build, place dev.provisionprofile in your project’s root. Extend your electron-builder config in package.json by the following:


		package.json

{
	"build": {
		"mas": {
			"type": "development"
		}
	}
}

If you’re also sandboxing your non-MAS Mac build, you should also add "type": "development" to the build.mac config.

Run yarn build. You should now be able to open your packaged MAS app (placed in the dist/mas directory).

Production

If everything is working as expected, you can build your app for production. Simply replace dev.provisionprofile with prod.provisionprofile, remove the "type": "development" lines from your package.json again and run the yarn build script. Please note that you will not be able to open the built production app (it will crash on launch). This is the expected behavior.

6. Upload to MAS

Go to App Store Connect and open “My Apps”. Create a new entry for your Mac app.

Open Xcode. From the menu, launch Xcode → Open Developer Tool → Application Loader and follow the steps from there. This tool will upload your app to App Store Connect.

Finally, go back to your app listing in App Store Connect, fill in all information about your app and select the uploaded build. Make sure you explain thoroughly why your app needs the specified entitlements. You can now submit your app for review, which usually takes about a day. Once your app is accepted, you can publish your app on the Mac App Store.

Sources

]]>

Packaging and Publishing an Electron App

Sun, 07 Apr 2019 00:00:00 +0000

Electron simplifies the development of cross-platform desktop apps. Unfortunately, packaging and releasing an Electron app for the different platforms is not a straightforward task. This post aims to guide you through the process

Packaging

electron-builder is a third-party tool that facilitates the process of packaging an Electron app. The tool handles various tasks required for building a production-ready app, like the inclusion of native dependencies, code signing, upload to a download server, and the inclusion of an auto-updater tool.

Run the following command to add electron-builder to your Electron project:

yarn add --dev electron-builder

Next, add the following scripts to your package.json file:


		package.json

{
	"scripts:": {
		"postinstall": "electron-builder install-app-deps",
		"build": "electron-builder --mac --windows --linux",
		"release": "electron-builder --mac --windows --linux --publish always"
	}
}

The postinstall script will execute after every yarn install and makes sure that native dependencies match your app’s version of Electron. The build script can be used to package your app for all specified platforms. The release script builds the app and publishes it on your download server.

You can also specify configuration parameters for electron-builder in your package.json file under the "build" key. I recommend the following options:


		package.json

{
	"name": "your-app",
	"build": {
		"appId": "com.yourcompany.yourapp",
		"productName": "Your App",
		"mac": {
			"category": "public.app-category.lifestyle"
		},
		"dmg": {
			"icon": false
		},
		"linux": {
			"target": ["AppImage"],
			"category": "Office"
		}
	}
}

See here for a list of possible Mac app categories and here for the available Linux categories.

Finally, create a folder named build in your project’s root directory and copy your app icon (named icon.png) into it. If you don’t add this file, the default Electron icon will be used.

You can now run yarn build and your app should get packaged for the platforms you specified earlier. You can find the output in the dist directory (which you should add to your .gitignore).

It’s important to know that, by default, electron-builder will include all dependencies from your package.json file in the app package, whereas development dependencies are ignored. To keep your app size small, you need to specify dependencies as devDependencies if your app doesn’t use them in production. If you’re using a module bundler like Webpack, you should either mark the bundled dependencies as devDependencies (to avoid having them in your package twice) or configure electron-builder to skip these dependencies (using the "files" configuration key).

Auto Update

electron-builder comes with built-in support for electron-updater, which checks your download server for new app versions every time the app is launched. If a more recent version exists, it’s automatically downloaded in the background and installed after the user closes the app.

To use electron-updater in your project, run the following command:

yarn add electron-updater

Add the following code to your main process:


		main.js

const autoUpdater = require("electron-updater");

app.on("ready", () => {
	autoUpdater.checkForUpdatesAndNotify();
});

If you’re using GitHub Releases for distributing your app (explained later in this guide), that’s all the configuration you need for the auto-updater to work!

Code Signing

For auto-updating to work on macOS, your code needs to be signed:

To obtain code signing certificates, you need to be enrolled in the Apple Developer Program (costs annually).
Install Xcode if necessary.
Open Xcode → Preferences → Accounts → Manage Certificates. Add one of each macOS-related certificate. Having one of each type allows for distribution both inside and outside the Mac App Store. The certificates are automatically added to your Keychain, where electron-builder can detect them. Your code will now automatically be signed whenever you run the build script.

Code signing of Windows apps is optional. If you choose not to sign your app, your users will be presented with a warning when installing your app.

Release

Manual Release

electron-builder supports various platforms for storing your app. By default, GitHub Releases will be used to store the files. To be able to publish on GitHub, generate a Personal Access Token for electron-builder.

Whenever you want to publish a new version of your app, do the following:

Increase the version number in your package.json file. Commit and push this change.
Run the release script with your GitHub token: GH_TOKEN=... yarn release. Your app will be built and the packages will be uploaded to GitHub. A release draft for the new version will be created.
Open the GitHub page of your repository and find the new release draft with the download links for your app. Add a changelog and publish the release.

That’s it! Your Electron app is now ready to be downloaded from its GitHub page. If you additionally want to publish your app on the Mac App Store, see this follow-up post.

Using GitHub Actions

Instead of building and releasing the app manually, you can also use GitHub Actions to do this task for you. You can read more about this process in my other blog post.

]]>

Samuel Meuli – Blog

Finding and Auto-fixing Lint Errors with GitHub Actions

Using the Lint Action

Showing Lint Errors on Commits/PRs

Viewing Lint Results

Auto-fixing Errors

Making Checks Mandatory

Notarizing Your Electron App

App Configuration

Authentication

Notarization

Sources

Automating the Release of Electron Apps

Removing Dead Keys on macOS

Publishing an Electron App on the Mac App Store

1. electron-builder Configuration

2. App ID

3. Entitlement Files

4. Provisioning Profile

5. Testing

Development

Production

6. Upload to MAS

Sources

Packaging and Publishing an Electron App

Packaging

Auto Update

Code Signing

Release

Manual Release

Using GitHub Actions

1. `electron-builder` Configuration