Report Bug

luarocks-tag-release
Automatically publish luarocks packages from git tags.
Designed to work with Neovim plugins.

🏷️🚀🌒

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).

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

• Can generate a rockspec based on repository metadata and information provided to the action.
• Tests a local installation from the rockspec file before uploading.
• Uploads the package to LuaRocks.
• Tests the installation of the uploaded package.
• Runs luarocks test with lua, neovim 0.9 and/or neovim-nightly as the interpreter.

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

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@v6
        env:
          LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}

The following optional inputs can be specified using with:

The name of the the luarocks package.

• Defaults to the repository name.

Lua dependencies. Any dependencies specified here must be available on LuaRocks.

Example:

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

Lua dependencies of the test suite. Any dependencies specified here must be available on LuaRocks.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v6
  with:
    test_dependencies: |
      luaunit

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@v6
  with:
    labels: |
      neovim

Lua interpreters to run luarocks test with. If set to an empty string (default), or no .busted file is present, no tests will be run.

Supported interpreters:

• neovim-stable - With access to the Neovim 0.9 Lua API.
• neovim-nightly - With access to the Neovim nightly Lua API.
• lua - Plain luajit

Example:

- name: LuaRocks Test and Upload
  uses: nvim-neorocks/luarocks-tag-release@v6
  with:
    test_interpreters: |
      neovim-stable
      neovim-nightly

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@v6
  with:
    copy_directories: |
      {{ neovim.plugin.dirs }}
      src
      examples

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

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

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v6
  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.

By default, this workflow will generate a rockspec based on a predefined template.

You can also add a modified template to your repository and specify the path to it with the template variable.

Example:

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

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@v6
  with:
    license: "MIT"

The package version to release to LuaRocks (without the rockspec revision). By default, this workflow will use github.ref_name (the git tag or branch name) to determine the LuaRocks package version. If you do not have a workflow that releases based on tags, you can manually set the version input.

Setting this input to either null, "scm" or "dev" will result in a scm release, where the generated rockspec's source URL is the repository's URL.

The following is an example for a basic workflow that runs daily at 00:00, sets the package version to 0.0.<number_of_commits>, and publishes to LuaRocks if there have been any commits in the last 24 hours:

name: "release"
on:
  workflow_dispatch: # allows manual triggering
  schedule:
    - cron: '0 0 * * *' # runs daily at 00:00
  pull_request: # Will test a local install without uploading to luarocks.org

jobs:
  luarocks-upload:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0 # Required to count the commits
      - name: Set luarocks version
        run: echo "LUAROCKS_VERSION=0.0.$(git log --oneline | wc -l)" >> $GITHUB_ENV
      - name: Get new commits
        run: echo "NEW_COMMIT_COUNT=$(git log --oneline --since '24 hours ago' | wc -l)" >> $GITHUB_ENV
      - name: LuaRocks Upload
        uses: nvim-neorocks/luarocks-tag-release@v6
        if: ${{ env.NEW_COMMIT_COUNT > 0 }}
        env:
          LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}
        with:
          version: ${{ env.LUAROCKS_VERSION }}

The specrev (revision) of the generated rockspec. Defaults to '1'.

Example:

- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v6
  with:
    version: "scm"
    # Add logic or determining if the specrev needs to be incremented
    specrev: "${{ env.SPECREV }}"

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 args to pass to the luarocks command. This is useful if luarocks cannot find headers needed for the installation.

Example:

- run: |
    sudo apt-get install -y libcurl4-openssl-dev
- name: LuaRocks Upload
  uses: nvim-neorocks/luarocks-tag-release@v6
  with:
    extra_luarocks_args: |
      CURL_INCDIR=/usr/include/x86_64-linux-gnu

See the Example configurations wiki page.

• 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.
• This action uses lua 5.1. So any packages that depend on lua > 5.1 will fail to install.

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

Thanks to:

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