Add get-git-ref-info action, update READMEs (#39)

* Add get-git-ref-info action, update READMEs

* Apply suggestions from code review

Co-authored-by: Davide Marchegiani <davide.marchegiani@anu.edu.au>

* Check if the ref is both a branch and a tag first, and error out if so

---------

Co-authored-by: Davide Marchegiani <davide.marchegiani@anu.edu.au>

Author: CodeGat

.github/actions/get-git-ref-info/README.md

@@ -0,0 +1,39 @@
+# Get git ref info Action
+
+This action is a shorthand way to determine whether a given git ref is a branch, tag or commit.
+
+If the specified ref doesn't exist, this action will fail with an error.
+
+## Inputs
+
+| Name | Description | Required | Default | Example |
+| ---- | ----------- | -------- | ------- | ------- |
+| `repository` | The repository to get the git ref info from, in the format `owner/repo` | `true` | N/A | `"ACCESS-NRI/spack-packages"` |
+| `ref` | The simple git reference (branch, tag, or commit SHA) to retrieve information about | `true` | N/A | `some-feature-branch` (branch), `v2.1` (tag), `8d29u23` (short SHA), `03d17eebfda5b873c576bad1dd77acdb8` (full SHA) |
+| `token` | A GitHub Token/PAT that allows cloning of the repository | `false` | `github.token` | `gha_pat_abcds...` |
+
+## Outputs
+
+| Name | Description | Example |
+| ---- | ----------- | ------- |
+| `ref-type` | Type of the given ref, if it's valid | One of `branch`, `tag`, `commit` |
+| `sha` | Full SHA of the given ref, if it's valid | `03d17eebfda5b873c576bad1dd77acdb8` |
+
+## Examples
+
+```yaml
+# ...
+jobs:
+  get-ref:
+    runs-on: ubuntu-latest
+    env:
+     ref: main
+    steps:
+    - id: resolve-ref
+      uses: access-nri/actions/.github/actions/get-git-ref-info@main
+      with:
+        repository: ACCESS-NRI/actions@main
+        ref: ${{ env.ref }}
+
+    - run: echo "Ref ${{ env.ref }} is a ${{ steps.resolve-ref.outputs.ref-type }} with SHA ${{ steps.resolve-ref.outputs.sha }}"
+```

.github/actions/get-git-ref-info/action.yml

@@ -0,0 +1,60 @@
+name: Get git ref info
+description: Action that retrieves information about a git reference
+inputs:
+  repository:
+    required: true
+    description: The repository to get the git ref info from, in the format 'owner/repo'.
+  ref:
+    required: true
+    description: The git reference (branch, tag, or commit SHA) to retrieve information about
+  token:
+    required: false
+    description: |
+      The GitHub token to use for authentication when accessing the repository.
+      Defaults to github.token.
+outputs:
+  ref-type:
+    description: The type of the git reference (branch, tag, or commit)
+    value: ${{ steps.ref-info.outputs.ref-type }}
+  sha:
+    description: The commit SHA that the git reference points to
+    value: ${{ steps.ref-info.outputs.sha }}
+runs:
+  using: composite
+  steps:
+    - name: Checkout ${{ inputs.repository }}
+      uses: actions/checkout@v5
+      with:
+        repository: ${{ inputs.repository }}
+        fetch-depth: 0
+        fetch-tags: true
+        token: ${{ inputs.token || github.token }}
+
+    - name: Get Git Ref Info
+      id: ref-info
+      shell: bash
+      # Determine if the ref is a branch, tag, or commit SHA, and get the SHA for the given ref
+      run: |
+        # Check if the ref exists as both a branch and a tag, in which case we error out
+        if git show-ref --verify --quiet 'refs/heads/${{ inputs.ref }}' && git show-ref --verify --quiet 'refs/tags/${{ inputs.ref }}'; then
+          echo "::error::The specified ref '${{ inputs.ref }}' exists as both a branch and a tag in the repository '${{ inputs.repository }}'. Please specify a unique ref."
+          exit 1
+        fi
+
+        # Check if the ref is a branch, tag, or commit
+        if git show-ref --verify --quiet 'refs/heads/${{ inputs.ref }}'; then
+          echo "ref-type=branch" >> $GITHUB_OUTPUT
+          echo "sha=$(git rev-parse "refs/heads/${{ inputs.ref }}")" >> $GITHUB_OUTPUT
+
+        elif git show-ref --verify --quiet 'refs/tags/${{ inputs.ref }}'; then
+          echo "ref-type=tag" >> $GITHUB_OUTPUT
+          echo "sha=$(git rev-parse 'refs/tags/${{ inputs.ref }}')" >> $GITHUB_OUTPUT
+
+        elif git cat-file -e '${{ inputs.ref }}^{commit}'; then
+          echo "ref-type=commit" >> $GITHUB_OUTPUT
+          echo "sha=$(git rev-parse '${{ inputs.ref }}')" >> $GITHUB_OUTPUT
+
+        else
+          echo "::error::The specified ref '${{ inputs.ref }}' does not exist in the repository '${{ inputs.repository }}'."
+          exit 1
+        fi

README.md

@@ -12,6 +12,7 @@ Custom GitHub Actions and Workflows for use across the ACCESS-NRI.
 * [commenter-permissions README.md](.github/actions/commenter-permission-check/README.md): Determine whether a commenter on a PR has write permissions on the repository.
 * [comment](.github/actions/comment/README.md): Add, modify or delete a comment on a given issue or PR.
 * [cache-svn-auth](.github/actions/cache-svn-auth/README.md): Cache Subversion (SVN)'s authentication password.
+* [get-git-ref-info](.github/actions/get-git-ref-info/README.md): Determine if a given git ref is a branch, tag or SHA, if it exists.
 
 ## Workflows