web-ext GitHub Action

This action allows you to run a few mozilla/web-ext commands useful during add-on development. It supports lint, build and sign.

Generally you can use these inputs:

• cmd: The command to run (lint, build, sign)
• source: The directory the add-on is in. For sign, this should be the xpi file instead
• artifacts: The output directory, defaults to web-ext-artifacts
• verbose: Output more debugging if set to true
• channel: The channel to use, listed or unlisted
• ignoreFiles: A json string containing an array of files to be ignored. Web-ext by default already ignores the most frequently ignored files.

There are a few more specific to each command.

lint

Linting supports annotations, this is great for pull requests. A token is not required for this action, though if GITHUB_TOKEN is in the environment, it will be used to create a check run that gives you more detailed information.

name: "Lint"
on:
  push:
    branches:
      - main
  pull_request:

jobs:
  lint:
    name: "Lint"
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout"
        uses: actions/checkout@v4

      - name: "web-ext lint"
        uses: kewisch/action-web-ext@v2
        with:
          cmd: lint
          source: src
          channel: listed

build

A simple web-ext build. You can use the target output for subsequent steps.

You can use the following extra options:

• filename: Template string for the packed extension's filename, available for download through the job's artifacts. The placeholders in braces ({...}) are replaced by the corresponding entries in the extension's manifest.json. E.g. "{name}-{version}.xpi".

name: "Build"
on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    name: "Build"
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout"
        uses: actions/checkout@v4

      - name: "web-ext build"
        id: web-ext-build
        uses: kewisch/action-web-ext@v2
        with:
          cmd: build
          source: src
          filename: "{name}-{version}.xpi"
          ignoreFiles: '[ "package.json","package-lock.json","yarn.lock" ]'

      - name: "Upload Artifact"
        uses: actions/upload-artifact@v4
        with:
          name: target.xpi
          path: ${{ steps.web-ext-build.outputs.target }}

sign

Send the add-on for signature to AMO. To reduce the load on AMO servers, please don't use this for on-commit or nightly builds. If you want to test your add-on you can do so in about:debugging. Using this for betas or releases is great though. Please note that listed add-ons will not be signed immediately, this is indicated during the build process but is not counted as a failure.

You can use the following extra options:

• sourceCode: Submit a zip with source code to adhere to the source code submission policy.
• metaDataFile: A JSON file with additional metadata for the version release. See example below for details.
• approvalNotes: A shortcut to set .version.approval_notes in the submitted metadata.
• releaseNotes: A shortcut to set .version.release_notes in the submitted metadata.
• license: The license for the version. See example below for details.
• licenseFile: If using a custom license, the license file to submit.
• apiKey: The API key used for signing.
• apiSecret: The API secret used for signing.
• apiUrlPrefix: The URL of the signing API, defaults to AMO production.
• timeout: The number of milliseconds to wait for upload and validation to complete before giving up. Defaults to 900000 ms (15 minutes).
• approvalTimeout: The number of milliseconds to wait for AMO to approve the submission and return the signed XPI. Set to 0 to skip waiting entirely: the action succeeds as soon as upload and validation succeed, and no signed XPI is downloaded (the target and name outputs will be null). AMO API v5 only.

Changing apiUrlPrefix to https://addons.thunderbird.net/api/v4 will allow you to submit to addons.thunderbird.net, or you can make use of the staging/dev instances.

Please see the example below on how to use the sign command.

Complete example

This is a complete example of a publish script. It is triggered when you create and publish a release on GitHub. You can of course also turn things around and trigger on tag creation, and subsequently create the release if the upload succeeds.

name: "Publish"
on:
  release:
    types: [published]

jobs:
  sign:
    name: "Release"
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout"
        uses: actions/checkout@v4

      - name: "web-ext lint"
        uses: kewisch/action-web-ext@v2
        with:
          cmd: lint
          source: src
          channel: listed

      - name: "web-ext build"
        id: web-ext-build
        uses: kewisch/action-web-ext@v2
        with:
          cmd: build
          source: src

      - name: "Collect sources"
        run: git archive --format=zip --output=sources.zip ${{ github.ref }}

      - name: "Collect metadata"
        id: metadata
        run: echo "json=$(jq -c . < amo_metadata.json)" >> $GITHUB_OUTPUT

      - name: "web-ext sign AMO"
        id: web-ext-sign
        uses: kewisch/action-web-ext@v2
        with:
          cmd: sign

          # Source must be the zip/xpi file of the add-on. If your add-on is required to submit
          # source as per https://extensionworkshop.com/documentation/publish/source-code-submission/
          # policy, you can use sourceCode with a zip file of the original sources. Submitting
          # source code is not always required, don't do so if you don't need to.
          source: ${{ steps.web-ext-build.outputs.target }}
          sourceCode: sources.zip
          channel: unlisted

          # Various metadata you can set through the API. See the documentation for the
          # --amo-metadata parameter to web-ext sign at
          # https://extensionworkshop.com/documentation/develop/web-ext-command-reference/#web-ext-sign
          # for more information. You can leave out metaDataFile if all you want to set is approval
          # notes, release notes, or a license.
          metaDataFile: amo_metadata.json
          approvalNotes: "Please find more information at https://github.com/kewisch/action-web-ext"
          releaseNotes: ${{ github.event.release.body }}

          # You can set one of the known licenses from
          # https://mozilla.github.io/addons-server/topics/api/licenses.html#license-list
          # by just passing the license property. If you have a custsom license, read it from a
          # file as follows.
          license: Apache-2.0       # You only need to specify a license file if you are using a
          licenseFile: LICENSE.md   # custom license. Please see action.yml for details.

          # Specify API secrets. No need to specify apiUrlPrefix, it defaults to AMO production
          apiKey: ${{ secrets.AMO_SIGN_KEY }}
          apiSecret: ${{ secrets.AMO_SIGN_SECRET }}
          timeout: 900000

      - name: "web-ext sign ATN"
        id: web-ext-sign
        uses: kewisch/action-web-ext@v2
        with:
          # This is how to sign for Thunderbird. Note that Thunderbird uses API v4, where many
          # metadata fields are not supported.
          cmd: sign
          source: ${{ steps.web-ext-build.outputs.target }}
          channel: listed
          apiUrlPrefix: "https://addons.thunderbird.net/api/v4"
          apiKey: ${{ secrets.ATN_SIGN_KEY }}
          apiSecret: ${{ secrets.ATN_SIGN_SECRET }}

      - name: "Attach release assets to release"
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          gh release upload ${{ github.event.release.tag_name }} \
            ${{ steps.web-ext-sign.outputs.target }}