wayofdev · lotyp · Mar 28, 2024 · Mar 28, 2024
@@ -16,19 +16,46 @@
 
 # Shared Github Actions
 
-This repository serves as a collection of reusable GitHub Action workflows specifically designed for usage in Wayofdev projects. The workflows stored here encapsulate common and repetitive tasks, allowing them to be easily integrated into multiple projects. This not only reduces the necessity to rewrite code, but also ensures a standardized approach to common operations across all Wayofdev repositories.
+This repository is a collection of reusable GitHub Actions workflows and composite actions, specifically designed for use in Wayofdev projects. These tools encapsulate common and repetitive tasks, allowing for easy integration into multiple projects. This approach not only reduces the need to rewrite code but also ensures standardized operations across all Wayofdev repositories.
+
+Learn more about:
+
+- [Reusing Workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows)
+- [Creating Composite Actions](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) 
+
+<br>
+
+## 📋 Table of Contents
+
+- [Getting Started](#getting-started)
+- [Workflows](#workflows)
+  - [Auto Label and Release Management](#-auto-label-and-release-management)
+  - [Docker](#-docker)
+  - [Create Diagrams](#-create-diagrams)
+  - [Static Analysis](#-static-analysis)
+- [Composite Actions](#composite-actions)
+  - [Dependency Management](#-dependency-management)
+- [License](#license)
+- [Author Information](#author-information)
+- [Contributing](#want-to-contribute)
+
+<br>
 
 ## 🚀 Getting Started
 
-To use these workflows, simply reference them from your project's workflows. Instructions for each workflow are detailed below.
+To use these workflows and actions, reference them directly from your project's workflows. Detailed instructions for each are provided below.
+
+<br>
+
+## ⚡️ Workflows
 
 Read more about [reusing workflows](https://docs.github.com/en/actions/using-workflows/reusing-workflows).
 
-<br>
+### → Auto Label and Release Management
 
-## 📑 Examples
+####  `apply-labels.yml:`
 
-### → `apply-labels.yml:`
+Automatically applies labels to pull requests based on modified paths.
 
 This workflow triages pull requests and applies labels based on the paths that are modified in the pull request. This can help to categorize your pull requests and make it easier to identify the type of changes included.
 
@@ -57,7 +84,7 @@ jobs:
 
 <br>
 
-### → `auto-merge-release.yml:`
+### `auto-merge-release.yml:`
 
 This workflow automatically merges releases. This workflow utilizes [peter-evans/enable-pull-request-automerge](https://github.com/peter-evans/enable-pull-request-automerge) to auto-merge releases that are created by [googleapis/release-please](https://github.com/googleapis/release-please).
 
@@ -92,7 +119,40 @@ jobs:
 
 <br>
 
-### → `build-image.yml:`
+### `create-release.yml:` 
+
+This workflow uses [google-github-actions/release-please-action](https://github.com/google-github-actions/release-please-action) to create automated releases based on [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+Here is an example of how to use this workflow:
+
+```yaml
+---
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - master
+
+name: 📦 Create release
+
+jobs:
+  release:
+    uses: wayofdev/gh-actions/.github/workflows/create-release.yml@master
+    with:
+      os: ubuntu-latest
+      branch: master
+      package-name: docker-php-base
+    secrets:
+      token: ${{ secrets.PERSONAL_GITHUB_TOKEN }}
+
+...
+```
+
+<br>
+
+### → Docker
+
+### `build-image.yml:`
 
 This workflow builds a docker image and pushes it to the GitHub Container Registry.
 
@@ -205,7 +265,9 @@ jobs:
 
 <br>
 
-### → `create-arch-diagram.yml:`
+### → Create Diagrams
+
+### `create-arch-diagram.yml:`
 
 This workflow leverages the [codesee-io/codesee-action](https://github.com/Codesee-io/codesee-action) action to automatically generate architecture diagrams for your codebase whenever a pull request is made.
 
@@ -244,68 +306,156 @@ jobs:
 
 <br>
 
-### → `create-release.yml:`
+### → Static Analysis
 
-This workflow uses [google-github-actions/release-please-action](https://github.com/google-github-actions/release-please-action) to create automated releases based on [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
+### `shellcheck.yml:`
+
+This workflow uses [redhat-plumbers-in-action/differential-shellcheck](https://github.com/redhat-plumbers-in-action/differential-shellcheck) to run shell script analysis.
 
 Here is an example of how to use this workflow:
 
 ```yaml
 ---
 
 on:  # yamllint disable-line rule:truthy
-  push:
-    branches:
-      - master
+  pull_request:
 
-name: 📦 Create release
+name: 🐞 Differential shell-check
+
+permissions:
+  contents: read
 
 jobs:
-  release:
-    uses: wayofdev/gh-actions/.github/workflows/create-release.yml@master
+  shellcheck:
+    uses: wayofdev/gh-actions/.github/workflows/shellcheck.yml@master
     with:
       os: ubuntu-latest
-      branch: master
-      package-name: docker-php-base
+      severity: warning
     secrets:
-      token: ${{ secrets.PERSONAL_GITHUB_TOKEN }}
+      token: ${{ secrets.GITHUB_TOKEN }}
 
 ...
 ```
 
 <br>
 
-### → `shellcheck.yml:`
+## ⚡️ Composite Actions
 
-This workflow uses [redhat-plumbers-in-action/differential-shellcheck](https://github.com/redhat-plumbers-in-action/differential-shellcheck) to run shell script analysis.
+Composite Actions are a powerful feature of GitHub Actions that allow you to create reusable actions using a combination of other actions, shell commands, or both. This enables you to encapsulate a sequence of steps into a single action, making your workflows more modular, easier to maintain, and reducing duplication across your projects. Composite Actions can accept inputs and use outputs, making them highly flexible and adaptable to various use cases.
 
-Here is an example of how to use this workflow:
+### → Dependency Management
+
+### `composer/install:`
+
+This action installs dependencies with Composer based on the specified dependency level (`lowest`, `locked`, `highest`). It's designed to be flexible, allowing you to specify the working directory for the Composer command. 
+
+Here is an example of how to use this action in your existing workfow:
 
 ```yaml
 ---
 
 on:  # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - master
   pull_request:
 
-name: 🐞 Differential shell-check
+name: 📥 Composer Install
 
-permissions:
-  contents: read
+jobs:
+  composer-install:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os:
+          - "ubuntu-latest"
+        php-version:
+          - "8.2"
+        dependencies:
+          - "locked"
+
+    steps:
+      - name: 📦 Check out the codebase
+        uses: actions/checkout@v4
+
+      - name: 📥 Install "${{ matrix.dependencies }}" dependencies
+        uses: wayofdev/gh-actions/actions/composer/install@master
+        with:
+          dependencies: ${{ matrix.dependencies }}
+          working-directory: '.'
+```
+
+<br>
+
+### `composer/get-cache-directory:`
+
+This action determines the Composer cache directory and exports it as `COMPOSER_CACHE_DIR` environment variable. It allows you to specify the working directory for the Composer command to determine the cache directory.
+
+Here is an example of how to use this action in your existing workflow:
+
+```yaml
+---
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+name: 🗂 Get Composer Cache Directory
 
 jobs:
-  shellcheck:
-    uses: wayofdev/gh-actions/.github/workflows/shellcheck.yml@master
-    with:
-      os: ubuntu-latest
-      severity: warning
-    secrets:
-      token: ${{ secrets.GITHUB_TOKEN }}
+  get-composer-cache-dir:
+    runs-on: ubuntu-latest
 
-...
+    steps:
+      - name: 📦 Check out the codebase
+        uses: actions/checkout@v4
+
+      - name: 🔍 Get Composer Cache Directory
+        uses: wayofdev/gh-actions/actions/composer/get-cache-directory@master
+        with:
+          working-directory: '.'
 ```
 
 <br>
 
+###  `composer/get-root-version:`
+
+This action determines the Composer root version based on the specified branch and exports it as `COMPOSER_ROOT_VERSION` environment variable. It's designed to be flexible, allowing you to specify both the branch and the working directory for the Composer command to determine the root version.
+
+Here is an example of how to use this action in your existing workflow:
+
+```yaml
+---
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+name: 🎯 Get Composer Root Version
+
+jobs:
+  get-composer-root-version:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: 📦 Check out the codebase
+        uses: actions/checkout@v4
+
+      - name: 🎯 Get Composer Root Version
+        uses: wayofdev/gh-actions/actions/composer/get-root-version@master
+        with:
+          branch: master
+          working-directory: '.'
+```
+
+These sections are designed to seamlessly integrate with your existing `README.md` documentation, providing clear instructions on how to use the new Composer actions within GitHub workflows.
+
+
+
 ## 🤝 License
 
 [![Licence](https://img.shields.io/github/license/wayofdev/gh-actions?style=for-the-badge&color=blue)](./LICENSE)

@@ -0,0 +1,23 @@
+# Documentation References:
+# - Creating a Composite Action: https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
+# - Metadata Syntax for Inputs: https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs
+# - Runs for Composite Actions: https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-run-steps-actions
+# - Composer CLI Documentation: https://getcomposer.org/doc/03-cli.md#composer-cache-dir
+# - Other Implementations: https://github.com/ergebnis/.github/blob/main/actions
+
+name: 🗂 Get composer cache directory
+description: Determines the composer cache directory and exports it as COMPOSER_CACHE_DIR environment variable
+
+inputs:
+  working-directory:
+    default: .
+    description: Which directory to use as working directory
+    required: true
+
+runs:
+  using: composite
+
+  steps:
+    - name: 🔍 Get composer cache directory
+      run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir --working-dir=${{ inputs.working-directory }})" >> $GITHUB_ENV
+      shell: bash
@@ -0,0 +1,30 @@
+# Documentation References:
+# - Creating a Composite Action: https://docs.github.com/en/actions/creating-actions/creating-a-composite-action
+# - Metadata Syntax for Inputs: https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs
+# - Runs for Composite Actions: https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-run-steps-actions
+# - Composer CLI Documentation: https://getcomposer.org/doc/03-cli.md#composer-root-version
+# - Other Implementations: https://github.com/ergebnis/.github/blob/main/actions
+
+name: 🎯 Get composer root version
+description: Determines the composer root version and exports it as COMPOSER_ROOT_VERSION environment variable
+
+inputs:
+  branch:
+    default: master
+    description: Name of the branch, e.g. "master"
+    required: true
+  working-directory:
+    default: "."
+    description: Which directory to use as working directory
+    required: true
+
+runs:
+  using: 'composite'
+
+  steps:
+    - name: 🎯 Get composer root version
+      env:
+        COMPOSER_DETERMINE_ROOT_VERSION_BRANCH: ${{ inputs.branch }}
+        COMPOSER_DETERMINE_ROOT_VERSION_WORKING_DIRECTORY: ${{ inputs.working-directory }}
+      run: ${{ github.action_path }}/run.sh
+      shell: bash
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+branch="${COMPOSER_DETERMINE_ROOT_VERSION_BRANCH}"
+workingDirectory="${COMPOSER_DETERMINE_ROOT_VERSION_WORKING_DIRECTORY}"
+
+if [[ ! -d ${workingDirectory} ]]; then
+  echo ::error::The value for the \"working-directory\" input needs to be an existing directory. The directory \""${workingDirectory}"\" does not exist.
+
+  exit 1;
+fi
+
+pathToComposerJsonFile="${COMPOSER_DETERMINE_ROOT_VERSION_WORKING_DIRECTORY}/composer.json"
+
+if [[ ! -f "${pathToComposerJsonFile}" ]]; then
+    echo ::error::A composer.json file could not be found in the directory \""${workingDirectory}"\".
+
+    exit 1
+fi
+
+COMPOSER_ROOT_VERSION=$(jq --arg key "dev-${branch}" --raw-output '.["extra"]["branch-alias"][$key]' "${pathToComposerJsonFile}")
+
+if [[ null = "${COMPOSER_ROOT_VERSION}" ]]; then
+    echo ::error:A branch alias has not been defined in \""${pathToComposerJsonFile}"\" for branch \""${branch}"\".
+
+    exit 0
+fi
+
+echo "COMPOSER_ROOT_VERSION=${COMPOSER_ROOT_VERSION}" >> "${GITHUB_ENV}"