todaypp / asdf-actions

GitHub Actions for the asdf version manager

asdf GitHub Actions

This repo provides a collection of asdf related actions for use in your workflows.

Usage

How to specify the version

There is a point that is particularly easy to misunderstand. It's where you specify the version of the action itself.

- name: Test plugin
  uses: asdf-vm/actions/plugin-test@v1
  #                                ^^^
  with:
    command: my_tool --version

We recommend that you include the version of the action. We adhere to semantic versioning, it's safe to use the major version (v1) in your workflow. If you use the master branch, this could break your workflow when we publish a breaking update and increase the major version.

steps:
  # Reference the major version of a release (most recommended)
  - uses: asdf-vm/actions/plugin-test@v1
  # Reference a specific commit (most strict)
  - uses: asdf-vm/actions/plugin-test@a368498
  # Reference a semver version of a release (not recommended)
  - uses: asdf-vm/actions/[email protected]
  # Reference a branch (most dangerous)
  - uses: asdf-vm/actions/plugin-testmaster

Example workflow

name: Main workflow

on:
  pull_request:
    paths-ignore:
      - "**.md"
  push:
    paths-ignore:
      - "**.md"
  schedule:
    - cron: 0 0 * * 5

jobs:
  plugin_test:
    strategy:
      fail-fast: false
      matrix:
        os:
          - macos-latest
          - ubuntu-latest

    runs-on: ${{ matrix.os }}

    steps:
      - name: Test plugin
        uses: asdf-vm/actions/plugin-test@v1
        with:
          command: my_tool --version

  lint:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Run ShellCheck
        run: shellcheck bin/*

  format:
    runs-on: macos-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Install shfmt
        run: brew install shfmt

      - name: Run shfmt
        run: shfmt -d .

Trick to avoid problems

Using the images provided by the Actions team may be difficult to test correctly due to current asdf implementation constraints. In this case, you can use Docker containers and avoid them.

jobs:
  plugin_test:
    strategy:
      fail-fast: false
      matrix:
        container:
          - alpine:latest
          - centos:latest
          - ubuntu:latest

    runs-on: ubuntu-latest

    container:
      image: ${{ matrix.container }}

    steps:
      - name: Test plugin
        uses: asdf-vm/actions/plugin-test@v1
        with:
          command: my_tool --version

Actions

Main actions

These two actions are probaly the most useful:

• asdf-vm/actions/install - Install your .tool-versions plugins and tools.

steps:
  - name: asdf_install
    uses: asdf-vm/actions/install@v1

See action.yml inputs.

• asdf-vm/actions/plugin-test - Test your shiny new asdf plugin.

steps:
  - name: asdf_plugin_test
    uses: asdf-vm/actions/plugin-test@v1
    with:
      command: my_tool --version

See action.yml inputs.

Lower level actions

These actions are used internally by the above ones. And you won't need to use them directly, unless you actually want.

• asdf-vm/actions/plugins-add - Only install plugins, not tool versions.

  See action.yml inputs.

• asdf-vm/actions/setup - Just installs asdf itself.

  See action.yml inputs.