Initial action implemention

.github/workflows/integration-tests.yaml

@@ -0,0 +1,233 @@
+---
+name: Integration Tests
+on:
+  pull_request:
+    paths:
+      - "action.yaml"
+      - ".github/workflows/integration-tests.yaml"
+
+jobs:
+  setup-simple:
+    name: Setup Simple
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        index:
+          - 1
+          - 2
+    outputs:
+      results-json: ${{ steps.matrix-output.outputs.json }}
+    steps:
+      - uses: actions/checkout@v4
+      # Slow down on job to ensure that this is the last run
+      - if: ${{ strategy.job-index == 0 }}
+        run: sleep 5
+      # Keep `id` the same between `setup-simple` and `setup-complex`
+      # to ensure we can separate output per job.
+      - uses: ./
+        id: matrix-output
+        with:
+          yaml: |
+            index: ${{ matrix.index }}
+          debug: true
+
+  test-simple:
+    name: Test Simple
+    needs: setup-simple
+    runs-on: ubuntu-latest
+    steps:
+      - name: Output JSON
+        run: |
+          if [[ "${output_json}" != "${expected_json}" ]]; then
+              cat <<<"${output_json}" >"output"
+              cat <<<"${expected_json}" >"expected"
+              diff output expected | cat -te
+              exit 1
+          fi
+        env:
+          output_json: ${{ needs.setup-simple.outputs.results-json }}
+          expected_json: |-
+            [
+              {
+                "index": 1
+              },
+              {
+                "index": 2
+              }
+            ]
+
+  setup-complex:
+    name: Setup Complex
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        build:
+          - name: App One
+            repo: user/app1
+          - name: App Two
+            repo: user/app2
+        version:
+          - "1.0"
+          - "2.0"
+    outputs:
+      results-json: ${{ steps.matrix-output.outputs.json }}
+    steps:
+      - uses: actions/checkout@v4
+      # Keep `id` the same between `setup-simple` and `setup-complex`
+      # to ensure we can separate output per job.
+      - uses: ./
+        id: matrix-output
+        with:
+          yaml: |
+            name: ${{ matrix.build.name }}
+            repo: ${{ matrix.build.repo }}
+            version_string: "${{ matrix.version }}"
+            version_number: ${{ matrix.version }}
+          debug: true
+
+  test-complex:
+    name: Test Complex
+    needs: setup-complex
+    runs-on: ubuntu-latest
+    steps:
+      - name: Output JSON
+        run: |
+          if [[ "${output_json}" != "${expected_json}" ]]; then
+              cat <<<"${output_json}" >"output"
+              cat <<<"${expected_json}" >"expected"
+              diff output expected | cat -te
+              exit 1
+          fi
+        env:
+          output_json: ${{ needs.setup-complex.outputs.results-json }}
+          expected_json: |-
+            [
+              {
+                "name": "App One",
+                "repo": "user/app1",
+                "version_string": "1.0",
+                "version_number": 1
+              },
+              {
+                "name": "App One",
+                "repo": "user/app1",
+                "version_string": "2.0",
+                "version_number": 2
+              },
+              {
+                "name": "App Two",
+                "repo": "user/app2",
+                "version_string": "1.0",
+                "version_number": 1
+              },
+              {
+                "name": "App Two",
+                "repo": "user/app2",
+                "version_string": "2.0",
+                "version_number": 2
+              }
+            ]
+
+  test-empty:
+    name: Test Empty
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./
+        id: matrix-output
+        continue-on-error: true
+        with:
+          yaml: ""
+          debug: true
+      - name: Action failed
+        if: ${{ steps.matrix-output.outcome != 'failure' }}
+        run: exit 1
+
+  test-duplicate:
+    name: Test Duplicate
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./
+        id: matrix-output1
+        continue-on-error: true
+        with:
+          yaml: |
+            demo: 1
+          debug: true
+      - uses: ./
+        id: matrix-output2
+        continue-on-error: true
+        with:
+          yaml: |
+            demo: 2
+          debug: true
+      - name: Action failed
+        if: ${{ steps.matrix-output1.outcome != 'success' || steps.matrix-output2.outcome != 'failure' }}
+        run: exit 1
+
+  setup-race-condition:
+    name: Setup Race Condition
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        index:
+          - 1
+          - 2
+    outputs:
+      results-json: ${{ steps.matrix-output.outputs.json }}
+    steps:
+      - uses: actions/checkout@v4
+      - if: ${{ strategy.job-index == 0 }}
+        run: sleep 5
+      - uses: ./
+        id: matrix-output
+        with:
+          yaml: |
+            index: ${{ matrix.index }}
+          debug: true
+      - if: ${{ strategy.job-index == 1 }}
+        run: sleep 30
+
+  test-race-condition:
+    name: Test Race Condition
+    needs: setup-race-condition
+    runs-on: ubuntu-latest
+    steps:
+      - name: Output JSON
+        run: |
+          if [[ "${output_json}" != "${expected_json}" ]]; then
+              cat <<<"${output_json}" >"output"
+              cat <<<"${expected_json}" >"expected"
+              diff output expected | cat -te
+              exit 1
+          fi
+        env:
+          output_json: ${{ needs.setup-race-condition.outputs.results-json }}
+          expected_json: |-
+            [
+              {
+                "index": 1
+              },
+              {
+                "index": 2
+              }
+            ]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Beacon Biosignals
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,86 @@
-# matrix-output
-Collect outputs from each matrix job
+# Matrix Output
+
+Collect outputs from each matrix job. Currently, setting output for matrix jobs will cause outputs of earlier completed jobs to be overwritten by jobs completed later (see [discussion](https://github.com/orgs/community/discussions/26639)). This action allows the output from each matrix job to be collected into a JSON list to be utilized by dependent jobs.
+
+## Requirements
+
+The `matrix-output` action requires that each job in the job matrix uses a distinct job name which is unique within the workflow file. By default job matrix job names are distinct (e.g. `name: Build` -> `Build (App One, user/app1)`) so this only a problem if you accidentally specify the same job name for multiple matrix jobs. If the job name is not unique within the workflow this action will fail and report the ambiguous job name.
+
+Additionally, the `matrix-output` action is intended to only be used once within a job. Attempting to utilize this action multiple times within the same job will cause the second use of this action to fail.
+
+Finally, it is highly recommended that the `matrix-output` is either the last step in the job or the near the end of the job. If you choose to have this action run before other slow running actions you may see some extended runtimes for the last few running jobs in the matrix. In order to guarantee correct output we require that the last running job has a complete set of outputs from all other jobs in the matrix. To ensure the last running job has a complete set of outputs we have those jobs wait for other jobs with an incomplete set of outputs.
+
+## Examples
+
+```yaml
+# CI.yaml
+jobs:
+  build:
+    name: Build ${{ matrix.build.name }}
+    # These permissions are needed to:
+    # - Use `matrix-output`: https://github.com/beacon-biosignals/matrix-output#permissions
+    permissions:
+      actions: read
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        build:
+          - name: App One
+            repo: user/app1
+          - name: App Two
+            repo: user/app2
+    outputs:
+      json: ${{ steps.matrix-output.outputs.json }}
+    steps:
+      - uses: docker/build-push-action@v6
+        id: build-push
+        with:
+          tags: ${{ matrix.build.repo }}:latest
+          push: true
+      # !!! Important: In order to reduce delays we highly recommend that the
+      # `matrix-output` action is either the last step in a job or close to the end.
+      - uses: beacon-biosignals/matrix-output@v1
+        id: matrix-output
+        with:
+          yaml: |
+            name: ${{ matrix.build.name }}
+            image: ${{ matrix.build.repo }}@${{ steps.build-push.outputs.digest }}
+
+  test:
+    name: Test ${{ matrix.build.name }}
+    needs: build
+    runs-on: ubuntu-latest
+    container:
+      image: ${{ matrix.build.image }}
+    strategy:
+      fail-fast: false
+      matrix:
+        build: ${{ fromJSON(needs.build.outputs.json) }}
+    steps:
+      ...
+```
+
+## Inputs
+
+The `matrix-output` action supports the following inputs:
+
+| Name             | Description | Required | Example |
+|:-----------------|:------------|:---------|:--------|
+| `yaml`           | A string representing a YAML data. Typically, a simple dictionary of key/value pairs. | Yes | <pre><code class="language-yaml">name: ${{ matrix.name }}&#10;...</code></pre> |
+
+## Outputs
+
+| Name   | Description | Example |
+|:-------|:------------|:--------|
+| `json` | A string representing a JSON list of dictionaries. Each dictionary in the list contains the output for a single job from the job matrix. The order of this list corresponds to the job index (i.e. `strategy.job-index`). | <pre><code class="language-json">[&#10;  {&#10;    "name": "Server.jl",&#10;    ...&#10;  },&#10;  {&#10;    "name": "Client.jl",&#10;    ...&#10;  }&#10;]</code></pre> |
+
+## Permissions
+
+The follow [job permissions](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) are required to run this action:
+
+```yaml
+permissions:
+  actions: read
+  contents: read
+```