chore: prepare for a first release

.github/workflows/tests.yml

@@ -0,0 +1,109 @@
+name: Terramate Action Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  simple:
+    name: Terramate latest
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install latest Terramate
+        uses: ./
+
+      - name: Validate execution
+        run: terramate version
+
+  asdf:
+    name: Terramate asdf
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        version: [0.4.2, 0.4.3, skip]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Prepare asdf config
+        if: ${{ matrix.version != 'skip' }}
+        run: echo "terramate ${{ matrix.version}}" >.tool-versions
+
+      - name: Prepare empty asdf config
+        if: ${{ matrix.version == 'skip' }}
+        run: echo >.tool-versions
+
+      - name: Install asdf Terramate
+        uses: ./
+
+      - name: Validate execution
+        run: terramate version
+
+      - name: Validate version - ${{ matrix.version }}
+        id: version
+        if: ${{ matrix.version != 'skip' }}
+        run: terramate version | grep ${{ matrix.version }}
+
+      - name: Validate outputs - ${{ matrix.version }}
+        if: ${{ matrix.version != 'skip' }}
+        run: echo "${{ steps.version.outputs.stdout }}" | grep ${{ matrix.version }}
+
+
+  wrapper:
+    name: Terramate with wrapper
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        version: [0.4.3, latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Terramate Wrapper - ${{ matrix.version }}
+        uses: ./
+        with:
+          version: ${{ matrix.version }}
+
+      - name: Validate execution - ${{ matrix.version }}
+        run: terramate version
+
+      - name: Validate version - ${{ matrix.version }}
+        id: version
+        if: ${{ matrix.version != 'latest' }}
+        run: terramate version | grep ${{ matrix.version }}
+
+      - name: Validate outputs - ${{ matrix.version }}
+        if: ${{ matrix.version != 'latest' }}
+        run: echo "${{ steps.version.outputs.stdout }}" | grep ${{ matrix.version }}
+
+  no-wrapper:
+    name: Terramate without wrapper
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        version: [0.4.3, latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Terramate - ${{ matrix.version }}
+        uses: ./
+        with:
+          version: ${{ matrix.version }}
+          use_wrapper: false
+
+      - name: Validate execution - ${{ matrix.version }}
+        run: terramate version
+
+      - name: Validate - ${{ matrix.version }}
+        if: ${{ matrix.version != 'latest' }}
+        run: terramate version | grep ${{ matrix.version }}

README.md

@@ -1,31 +1,88 @@
 # Terramate Github Action
 
-This is a very simple Github Action that installs Terramate and (by default) a wrapper that allows you to use the stdout, stderr and exit code in subsequent workflow steps. It is only compatible with Ubuntu runners.
+The [`terramate-io/terramate-action`] is a GitHub composite action that sets up Terramate CLI in your GitHub Actions workflows.
+
+- It downloads a specific version or falls back to an [asdf] configured version or the latest available release of [Terramate CLI].
+- It installs [Terramate CLI] into a user specified path or by default to `/usr/local/bin`
+- It installs a wrapper script by default so that calls to `terramate` binary will expose GitHub Action outputs to access the `stderr`, `stderr`, and the `exitcode` of the `terramate` execution.
+- It allows you to configure a default [Terramate Cloud] organization to use Terramate Cloud Features like Drift Detection and Stack Health Information.
+
+## Compatbility
+
+The action currently only supports `ubuntu` runners.
+Please open an issue, if more runner support is required.
 
 ## Usage
 
-There are three optional inputs
-* `version` is the version of Terramate to use. If not defined, the [asdf](https://asdf-vm.com/) `.tool-versions` file is checked, and if that doesn't contain a Terramate entry then the latest Terramate version is used by default.
-* `use_wrapper` if explicitly set to `false` Terramate CLI will not be called via a wrapper script. This means that the GitHub Action Outputs cannot be used in subsequent steps.
-* `cloud_organization` sets the Terramate Cloud organization to use for all steps in this job
+The default action installs Terramate CLI in it's latest version unless a specific version is configured by [asdf] config file `.tool-versions`.
+
+```yaml
+steps:
+  - uses: terramate-io/terramate-action@v1
+```
+
+You can disable [asdf] integration by explicitly specifying `"latest"` as the desired version.
+
+```yaml
+steps:
+  - uses: terramate-io/terramate-action@v1
+    with:
+      version: "latest"
+```
+
+To install a specific version the version can be specified using the `version` argument:
+
+```yaml
+steps:
+  - uses: terramate-io/terramate-action@v1
+    with:
+      version: "0.4.2"
+```
+
+The binary will be installed to `/usr/local/bin` by default. This location can be changed using the `bindir` argument:
+
+```yaml
+steps:
+  - uses: terramate-io/terramate-action@v1
+    with:
+      bindir: /usr/local/bin
+```
+
+To configure the default [Terramate Cloud] Organization set `cloud_organization` argument to your organization short name:
+
+```yaml
+steps:
+  - uses: terramate-io/terramate-action@v1
+    with:
+      cloud_organization: myorganization
+```
+
+To disable using the optional wrapper script by default the `use_wrapper` argument can be set to `"false"`:
 
-Outputs are `stdout`, `stderr` and `exitcode` which can be used in subsequent commands, e.g.
+```yaml
+steps:
+  - uses: terramate-io/terramate-action@v1
+    with:
+      use_wrapper: "false"
+```
+
+Subsequent steps can access outputs when the wrapper script is installed:
 
 ```yaml
-- name: Install terramate
-  uses: terramate-io/terramate-action@main
-
-- name: Terramate run plan
-  id: plan
-  run: terramate run --changed --disable-check-gen-code -- terraform plan -lock-timeout=5m -out out.tfplan
-
-- name: Publish Plans for Changed Stacks
-  uses: marocchino/sticky-pull-request-comment@v2
-  with:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    message: |
-      ${{ steps.plan.outputs.stdout }}
+steps:
+  - uses: terramate-io/terramate-action@v1
+
+  - id: list
+    run: terramate list --changed
+
+  - run: echo ${{ steps.list.outputs.stdout }}
+  - run: echo ${{ steps.list.outputs.stderr }}
+  - run: echo ${{ steps.list.outputs.exitcode }}
 ```
 
-There is a full example [here](./examples/basic.yml)
+<!-- links -->
 
+[asdf]: https://asdf-vm.com/
+[`terramate-io/terramate-action`]: https://github.com/terramate-io/terramate-action
+[Terramate CLI]: https://terramate.io/cli/docs
+[Terramate Cloud]: https://terramate.io

action.yml

@@ -2,28 +2,38 @@ name: 'Terramate'
 description: 'Terramate'
 inputs:
   version:
-    description: 'Terramate version'
+    description: |
+      The Terramate Version to install.
+      If not set and an asdf config is available in .tool-versions at the root of the repository is available, the configured version is used by default.
+      If not set and no asdf config is found, the latest version will be installed.
     required: false
+  bindir:
+    description: The destination directory of the installed terramate executable.
+    required: false
+    default: /usr/local/bin
   use_wrapper:
-    description: 'Use wrapper'
+    description: |
+      The default wrapper script installation can be skipped by setting the use_wrapper variable to 'false'.
     required: false
     default: "true"
   cloud_organization:
-    description: 'Terramate Cloud organization to use'
+    description: Terramate Cloud organization to use by default when using Terramate Cloud features.
     required: false
+
 runs:
   using: "composite"
+
   steps:
-    - name: Adding action_path to GITHUB_PATH
-      run: echo "${{ github.action_path }}" >> $GITHUB_PATH
-      shell: bash
+
     - name: Installing Terramate
-      run: install.sh
       shell: bash
+      run: ${{ github.action_path }}/install.sh
       env:
-        TM_VERSION:  ${{inputs.version}}
-        USE_WRAPPER: ${{inputs.use_wrapper}}
+        TMA_INPUT_VERSION:  ${{inputs.version}}
+        TMA_INPUT_USE_WRAPPER: ${{inputs.use_wrapper}}
+        TMA_INPUT_BINDIR: ${{inputs.bindir}}
+
     - name: Configuring Terramate execution environment
-      run: echo "TM_CLOUD_ORGANIZATION=${{inputs.cloud_organization}}" >> $GITHUB_ENV
       if: ${{ inputs.cloud_organization != '' }}
       shell: bash
+      run: echo "TM_CLOUD_ORGANIZATION=${{inputs.cloud_organization}}" >> $GITHUB_ENV