[!TIP]

We recommend switching to gh-actions-lux.

Publishes packages to LuaRocks when a git tag is pushed. No need to add a rockspec to your repository for each release (or at all).

Quick links

• Features
• Prerequisites
• Usage
• Inputs
• Example configurations
• Limitations
• Related
• Acknowledgements

Features

• Generates a lux.toml from repository metadata and action inputs, unless the repository already provides a lux.toml.
• Tests a local installation from the generated rockspec before uploading.
• Uploads the package to LuaRocks using lux.
• Tests the installation of the uploaded package.

Prerequisites

• A LuaRocks account and an API key.
• Add the API key to your repository's GitHub Actions secrets as LUX_API_KEY.

Usage

Create .github/workflows/release.yml in your repository with the following contents:

name: LuaRocks release
on:
  push:
    tags: # Will upload to luarocks.org when a tag is pushed
      - "*"
  pull_request: # Will test a local install without uploading to luarocks.org

jobs:
  luarocks-release:
    runs-on: ubuntu-latest
    name: LuaRocks upload
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: LuaRocks Upload
        uses: nvim-neorocks/luarocks-tag-release@v9
        env:
          LUX_API_KEY: ${{ secrets.LUX_API_KEY }}

[!NOTE]

Use the v9 tag to keep up with the latest releases, without breaking changes.

Inputs

The following optional inputs can be specified using with:

name

The name of the the luarocks package.

• Defaults to the repository name.

dependencies

Lua dependencies, added to the generated project with lx add. Any dependencies specified here must be available on LuaRocks.

[!NOTE]

lux requires an explicit version requirement for each dependency. Bare names (e.g. plenary.nvim) are resolved by lux to the latest version at publish time. This may change in the future (see lux#2011).

A lua entry (e.g. lua >= 5.4) sets the published Lua version constraint and is not added as a dependency.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    dependencies: |
      plenary.nvim
      telescope.nvim

labels

Labels to add to the rockspec. If none are specified, this action will use the repository's GitHub topics.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    labels: |
      neovim

copy_directories

Directories in the source directory to be copied to the rock installation prefix as-is. Useful for installing documentation and other files such as samples and tests.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    copy_directories: |
      {{ neovim.plugin.dirs }}
      src
      examples

[!NOTE]

The value {{ neovim.plugin.dirs }} (set by default) expands to common Neovim plugin directories (see also :help runtimepath):

• autoload
• colors
• compiler
• doc
• filetype.lua
• ftdetect
• ftplugin
• indent
• keymap
• lang
• lsp
• menu.vim
• parser
• plugin
• queries
• query
• rplugin
• spell
• syntax

[!WARNING]

Do not use the following directory names: lua, lib, rock_manifest or the name of your rockspec; those names are used by the .rock format internally, and attempting to copy directories with those names using the build.copy_directories directive will cause a clash.

summary

A short description of the package (one line). If excluded, this action will fetch it from your repository's about section.

detailed_description

A more detailed description of the package. Can be multiple lines.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    detailed_description: |
      Publishes packages to LuaRocks when a git tag is pushed.
      Automatically generates a rockspec from repository metadata
      and tests the installation before releasing.

template

Path to a custom extra.rockspec.

Use this to customise the generated project's build specification, dependencies, or other fields that cannot be expressed through the action inputs. lux merges the extra.rockspec over the generated lux.toml.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    template: "/path/to/my/extra.rockspec"

[!WARNING]

An extra.rockspec must not define version or source (those are generated by the action), and the $placeholder templating from earlier versions of luarocks-tag-release no longer applies.

license (optional)

The license used by this package. If not set (by default), this workflow will fetch the license SPDX ID from GitHub. If GitHub cannot detect the license automatically, you can set it here.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    license: "MIT"

[!NOTE]

If GitHub can detect the license automatically, it will be displayed in your repository's About section.

version (optional)

The version to publish (without the rockspec revision).

By default, lux derives the version from the git tag (a leading v is stripped). If there is no SemVer tag, a dev version is published.

Set this input to publish a specific version, for example from a scheduled workflow that has no tags. Setting it to "scm" or "dev" publishes a dev release.

The specrev input has been removed; lux manages the rockspec revision automatically.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    version: "0.0.123"

fail_on_duplicate (optional)

When set to true will cause the workflow to fail with an error if the rock already exists on the server. By default, if the rock already exists with a given version, the workflow will do nothing and fall back to other tasks instead (e.g. running tests).

extra_lux_args

Extra arguments passed to the lux command.

Example:

- run: |
    sudo apt-get install -y libcurl4-openssl-dev
- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    extra_lux_args: |
      --lua-version 5.4 --variables CURL_INCDIR=/usr/include/x86_64-linux-gnu

[!TIP]

To find out where apt installs headers (assuming you are have set runs-on: ubuntu-xyz), you can run dpkg -L <package-name>.

gpg_private_key (optional)

An ASCII-armoured GPG private key used to sign the uploaded rockspec. When unset, uploads are not signed.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v9
  with:
    gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
    gpg_passphrase: ${{ secrets.GPG_PASSPHRASE }}

gpg_passphrase (optional)

The passphrase for gpg_private_key, if one is set.

sign_protocol (optional)

The GPG signing protocol used by lux when a key is provided. Defaults to default. Ignored when gpg_private_key is unset.

Example configurations

See the Example configurations wiki page.

Limitations

• This workflow only works on public repositories.
• It was designed with Neovim plugins in mind. It should work with any LuaRocks package (lua >= 5.1), but this has not been tested.
• The published Lua version constraint defaults to >= 5.1. To change it, add a lua entry to the dependencies input (e.g. lua >= 5.4).
• To build/install with a specific Lua version, pass extra_lux_args: --lua-version <version> (lux otherwise detects or installs a suitable Lua).

Related

• rocks.nvim: A modern approach to Neovim plugin management, which uses luarocks.
• Luarocks :purple_heart: Neovim: A simple sample repository showing how to push your Neovim plugins to luarocks.

Acknowledgements

Thanks to:

• @Conni2461 for the help debugging the first drafts.
• The neorocks surgeons:
  • @teto
  • @vhyrro
  • @NTBBloodbath
  • @vigoux
  • @vsedov
  • @mrcjkb