Skip to content

Continuous integration

Caching Conveyor downloads

Please be careful that your CI/build system doesn't download Conveyor over and over again. If you can't pre-install it on your workers for some reason, make sure the download is cached locally. IP addresses that seem to be re-downloading Conveyor on every build may be throttled or blocked.

Conveyor works well with CI platforms like TeamCity, GitHub Actions etc. When building in CI you should supply your signing credentials in a different way than using the defaults.conf file. A simple approach is to create a separate file next to your main conveyor.conf file that looks like this:

include required("conveyor.conf")

app {
    signing-key = ${env.SIGNING_KEY}

    mac.certificate = apple.cer
    windows.certificate = windows.cer

    mac.notarization {
        app-specific-password = ${env.APPLE_ASP}
        team-id = 6MD7Z8H86K
        apple-id = "you@user.host"
    }
}

Call it something like ci.conveyor.conf. Copy your .cer/.pem files to be next to this file (or adjust the paths). Now place your root key and Apple notarization app-specific password into secret environment variables in your CI configuration called SIGNING_KEY and APPLE_ASP respectively. Finally, invoke conveyor like this: conveyor -f ci.conveyor.conf make site. Your main conveyor.conf file will fall back to the generated defaults for self-signing.

An alternative approach is to set a passphrase, then put the encrypted app.signing-key value into your main app config that gets checked into version control. You can then put the passphrase into an environment variable and specify it on the command line with --passphrase=env:PASSPHRASE.

To get Conveyor onto your build agents either download the Linux tarball or pre-install it on your agents. You can get a link for the current version from the download page, which will look like this: https://downloads.hydraulic.dev/conveyor/conveyor-${CONVEYOR_VERSION}-linux-amd64.tar.gz.

Forcing re-downloads of artifacts

Conveyor assumes by default that input URLs are stable/versioned and caches them. It doesn't at this time use HTTP caching, so if you need to rebuild your package because the contents of your input URLs changed without the URL itself changing add the --rerun=all flag at the end of your command line:

conveyor make site --rerun=all

Using GitHub Actions

GitHub Actions has a couple of limitations that require workarounds:

  1. No direct download links for artifacts exported from jobs.
  2. Can only export files using zips, and those zips don't preserve UNIX file permissions.

An example of how to use GitHub Actions with Conveyor is the GitHub Desktop package. It does the build of the platform-specific artifacts in Actions on each commit, but expects you to run Conveyor locally when it's time to release.

It solves the above limitations:

  1. A direct download link to the output of a CI build job is created using the nightly.link service. You give this website the URL of your Actions job YAML, and it gives you back download links that can be used as Conveyor inputs.
  2. UNIX files are wrapped in a tarball which is then in turn exported inside a zip. Windows files are exported directly inside a zip. Conveyor is then told to extract the archives and inner archives to get at the files.

The config for this looks like:

ci-artifacts-url = nightly.link/hydraulic-software/github-desktop/workflows/ci/conveyorize

app {
  windows.amd64.inputs = ${ci-artifacts-url}/build-out-Windows-x64.zip
  mac.amd64.inputs = [{
    from = ${ci-artifacts-url}/build-out-macOS-x64.zip
    extract = 2
  }]
  mac.aarch64.inputs = [{
    from = ${ci-artifacts-url}/build-out-macOS-arm64.zip
    extract = 2
  }]
}

By defining the inputs as an object and then using the extract key, the outer zip and inner tarball can be both unwrapped. This preserves file permissions and other UNIX metadata.

Doing releases from within GitHub Actions

You can use the Conveyor GitHub Action to perform releases from GitHub.

These workflows contain examples of how to use the Conveyor action:

You will need to change your conveyor.conf to point your inputs to the paths specified in the download-artifact steps:

app {
  windows.amd64.inputs += artifacts/windows
  linux.amd64.inputs += artifacts/build-linux-amd64.tar
  mac.amd64.inputs += artifacts/build-macos-amd64.tar
  mac.aarch64.inputs += artifacts/build-macos-aarch64.tar  
}

To release Windows apps with hardware protected keys you have a few options:

  1. Run Conveyor locally instead of driving it from CI, with your key HSM plugged in via USB.
  2. Provide GitHub or your CI system with a build agent that has the signing key plugged in, and supply the passphrase via a secret environment variable (e.g. --passphrase=env:SIGNING_PASSPHRASE).
  3. Use a cloud HSM or signing service like SignPath