Check for gh_action_ref explicitly and document GHA inputs (#4701)

Author: alisonlhart

.config/constraints.txt

@@ -1,29 +1,29 @@
 # This file was autogenerated by uv via the following command:
 #    tox run -e deps
-ansible-compat==25.5.0    # via ansible-lint (pyproject.toml)
+ansible-compat==25.6.0    # via ansible-lint (pyproject.toml)
 ansible-creator==25.6.0   # via ansible-lint (pyproject.toml)
 astroid==3.3.10           # via pylint
 asttokens==3.0.0          # via stack-data
-attrs==25.3.0             # via jsonschema, referencing
+attrs==25.3.0             # via jsonschema, referencing, ansible-lint (pyproject.toml)
 babel==2.17.0             # via mkdocs-material
 backrefs==5.9             # via mkdocs-material
 beautifulsoup4==4.13.4    # via linkchecker, mkdocs-htmlproofer-plugin
 bindep==2.13.0            # via tox-extra
 black==25.1.0             # via ansible-lint (pyproject.toml)
 boolean-py==5.0           # via license-expression
-bracex==2.6               # via wcmatch
+bracex==2.6               # via wcmatch, ansible-lint (pyproject.toml)
 cachetools==6.1.0         # via tox
 cairocffi==1.7.1          # via cairosvg
 cairosvg==2.7.1           # via mkdocs-ansible
 certifi==2025.7.14        # via requests
-cffi==1.17.1              # via cairocffi, cryptography
+cffi==1.17.1              # via cairocffi, cryptography, ansible-lint (pyproject.toml)
 chardet==5.2.0            # via tox
 charset-normalizer==3.4.2  # via requests
-click==8.2.1              # via black, mkdocs
+click==8.2.1              # via black, mkdocs, ansible-lint (pyproject.toml)
 colorama==0.4.6           # via griffe, mkdocs-material, tox
 coverage==7.10.0          # via coverage-enable-subprocess, ansible-lint (pyproject.toml)
 coverage-enable-subprocess==1.0  # via ansible-lint (pyproject.toml)
-cryptography==45.0.5      # via ansible-core
+cryptography==45.0.5      # via ansible-core, ansible-lint (pyproject.toml)
 csscompressor==0.9.5      # via mkdocs-minify-plugin
 cssselect2==0.8.0         # via cairosvg
 decorator==5.2.1          # via ipdb, ipython
@@ -48,17 +48,17 @@ ipdb==0.13.13             # via ansible-lint (pyproject.toml)
 ipython==8.36.0           # via ipdb, ansible-lint (pyproject.toml)
 isort==6.0.1              # via pylint
 jedi==0.19.2              # via ipython
-jinja2==3.1.6             # via ansible-core, ansible-creator, mkdocs, mkdocs-macros-plugin, mkdocs-material, mkdocstrings
+jinja2==3.1.6             # via ansible-core, ansible-creator, mkdocs, mkdocs-macros-plugin, mkdocs-material, mkdocstrings, ansible-lint (pyproject.toml)
 jmespath==1.0.1           # via ansible-lint (pyproject.toml)
 jsmin==3.0.1              # via mkdocs-minify-plugin
 jsonschema==4.24.0        # via ansible-compat, ansible-lint (pyproject.toml)
-jsonschema-specifications==2025.4.1  # via jsonschema
+jsonschema-specifications==2025.4.1  # via jsonschema, ansible-lint (pyproject.toml)
 license-expression==30.4.3  # via ansible-lint (pyproject.toml)
 linkchecker==10.5.0       # via mkdocs-ansible
 markdown==3.8             # via markdown-include, mkdocs, mkdocs-autorefs, mkdocs-htmlproofer-plugin, mkdocs-material, mkdocstrings, pymdown-extensions
 markdown-exec==1.11.0     # via mkdocs-ansible
 markdown-include==0.8.1   # via mkdocs-ansible
-markupsafe==3.0.2         # via jinja2, mkdocs, mkdocs-autorefs, mkdocstrings
+markupsafe==3.0.2         # via jinja2, mkdocs, mkdocs-autorefs, mkdocstrings, ansible-lint (pyproject.toml)
 matplotlib-inline==0.1.7  # via ipython
 mccabe==0.7.0             # via pylint
 mergedeep==1.3.4          # via mkdocs, mkdocs-get-deps
@@ -75,7 +75,7 @@ mkdocs-minify-plugin==0.8.0  # via mkdocs-ansible
 mkdocstrings==0.30.0      # via mkdocs-ansible, mkdocstrings-python
 mkdocstrings-python==1.16.12  # via mkdocs-ansible
 mypy==1.16.1              # via ansible-lint (pyproject.toml)
-mypy-extensions==1.1.0    # via black, mypy
+mypy-extensions==1.1.0    # via black, mypy, ansible-lint (pyproject.toml)
 netaddr==1.3.0            # via ansible-lint (pyproject.toml)
 packaging==25.0           # via ansible-compat, ansible-core, bindep, black, mkdocs, mkdocs-macros-plugin, pyproject-api, pytest, pytest-sugar, tox, tox-extra, tox-uv, ansible-lint (pyproject.toml)
 paginate==0.5.7           # via mkdocs-material
@@ -85,13 +85,13 @@ pathspec==0.12.1          # via black, mkdocs, mkdocs-macros-plugin, mypy, yamll
 pbr==6.1.1                # via bindep
 pexpect==4.9.0            # via ipython
 pillow==11.3.0            # via cairosvg, mkdocs-ansible
-platformdirs==4.3.8       # via black, mkdocs-get-deps, pylint, tox, virtualenv
+platformdirs==4.3.8       # via black, mkdocs-get-deps, pylint, tox, virtualenv, ansible-lint (pyproject.toml)
 pluggy==1.6.0             # via pytest, tox
 prompt-toolkit==3.0.51    # via ipython
 psutil==7.0.0             # via pytest-xdist, ansible-lint (pyproject.toml)
 ptyprocess==0.7.0         # via pexpect
 pure-eval==0.2.3          # via stack-data
-pycparser==2.22           # via cffi
+pycparser==2.22           # via cffi, ansible-lint (pyproject.toml)
 pygments==2.19.2          # via ipython, mkdocs-material, pytest
 pylint==3.3.7             # via ansible-lint (pyproject.toml)
 pymdown-extensions==10.16  # via markdown-exec, mkdocs-ansible, mkdocs-material, mkdocstrings
@@ -107,8 +107,8 @@ pyyaml==6.0.2             # via ansible-compat, ansible-core, ansible-creator, m
 pyyaml-env-tag==1.1       # via mkdocs
 referencing==0.36.2       # via jsonschema, jsonschema-specifications, types-jsonschema, ansible-lint (pyproject.toml)
 requests==2.32.4          # via linkchecker, mkdocs-htmlproofer-plugin, mkdocs-material
-rpds-py==0.26.0           # via jsonschema, referencing
-ruamel-yaml==0.18.11      # via ansible-lint (pyproject.toml)
+rpds-py==0.26.0           # via jsonschema, referencing, ansible-lint (pyproject.toml)
+ruamel-yaml==0.18.14      # via ansible-lint (pyproject.toml)
 setproctitle==1.3.6       # via pytest-xdist
 setuptools==80.9.0        # via pbr
 six==1.17.0               # via python-dateutil
@@ -129,11 +129,11 @@ types-pyyaml==6.0.12.20250516  # via ansible-lint (pyproject.toml)
 urllib3==2.5.0            # via requests
 virtualenv==20.32.0       # via tox
 watchdog==6.0.0           # via mkdocs
-wcmatch==10.0             # via ansible-lint (pyproject.toml)
+wcmatch==10.1             # via ansible-lint (pyproject.toml)
 wcwidth==0.2.13           # via prompt-toolkit
 webencodings==0.5.1       # via cssselect2, tinycss2
 yamllint==1.37.1          # via ansible-lint (pyproject.toml)
-zipp==3.23.0              # via importlib-metadata
+zipp==3.23.0              # via importlib-metadata, ansible-lint (pyproject.toml)
 
 # The following packages were excluded from the output:
 # ansible-core

.github/workflows/tox.yml

@@ -53,7 +53,7 @@ jobs:
       GITHUB_ACTIONS_TEST: "true"
     steps:
       - uses: actions/checkout@v4
-      - name: Self test 1
+      - name: Self test 1 # Test without explicit ref - fallback to main
         uses: ./
         with:
           # basically we only lint linter own configuration, which should be passing.
@@ -71,6 +71,12 @@ jobs:
           args: .ansible-lint
           working_directory: docs
           expected_return_code: "2" # expected to fail because the given argument does not exist in this folder
+      - name: Self test 4 # Test explicit ref override - expect warning message
+        uses: ./
+        with:
+          args: .ansible-lint
+          gh_action_ref: "v25.5.0"
+
   build:
     name: ${{ matrix.name }}
     runs-on: ${{ matrix.os || 'ubuntu-24.04' }}

README.md

@@ -29,24 +29,31 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Run ansible-lint
-        uses: ansible/ansible-lint@main
+        uses: ansible/ansible-lint@main # or vX.X.X version
         # optional (see below):
         with:
           args: ""
+          gh_action_ref: "<version - e.g. `v25.5.0`>" # Not recommended for non-composite action use
           setup_python: "true"
           working_directory: ""
           requirements_file: ""
 ```
 
-All the arguments are optional and most users should not need them:
+By default, the workflow uses ansible-lint installed from `main`. For production or stable workflows, it is recommended to specify a particular release tag (in format v.X.X.X).
+
+All the arguments are optional:
 
 - `args`: Arguments to be passed to ansible-lint command.
+- `gh_action_ref`: The git branch, tag, or commit to use for ansible-lint.
+  Not recommended for standard use - only use with composite actions where
+  `GH_ACTION_REF` is set to the parent action version.
+- `requirements_file`: Path to the requirements.yml file to install role and
+  collection dependencies.
 - `setup_python`: If python should be installed. Default is `true`.
 - `working_directory`: The directory where to run ansible-lint from. Default is
-  `github.workspace`. That might be needed if you want to lint only a subset of
+  `github.workspace`. Needed if you want to lint only a subset of
   your repository.
-- `requirements_file`: Path to the requirements.yml file to install role and
-  collection dependencies.
+
 
 For more details, see [ansible-lint-action].
 

action.yml

@@ -13,7 +13,7 @@ inputs:
   setup_python:
     description: If false, this action will not setup python and will instead rely on the already installed python.
     required: false
-    default: true
+    default: "true"
   working_directory:
     description: The directory where to run ansible-lint from. Default is `github.workspace`.
     required: false
@@ -23,11 +23,11 @@ inputs:
     required: false
     default: ""
   expected_return_code:
-    description: Expected return code from ansible-lint. Default is 0. Used for self-testing purposes.
+    description: (Internal use only) Expected return code from ansible-lint. Default is 0. Used for self-testing purposes.
     required: false
     default: "0"
   gh_action_ref:
-    description: The branch, tag, or commit to use for ansible-lint.
+    description: The branch, tag, or commit to use for ansible-lint. Only recommended for use with composite actions where `GH_ACTION_REF` is set to the parent action version.
     default: ""
     required: false
 runs:
@@ -47,10 +47,15 @@ runs:
     # This allows a user to override it using the input variable
     - name: Determine github action ref
       shell: bash
+      env:
+        GH_ACTION_REF_INPUT: ${{ inputs.gh_action_ref }}
+        GITHUB_ACTION_REF: ${{ github.action_ref }}
       run: |
-        action_ref="${{ inputs.gh_action_ref }}"
-        if [[ -z "${{ inputs.gh_action_ref }}" ]]; then
-          action_ref="${{ github.action_ref || 'main' }}"
+        action_ref="${GH_ACTION_REF_INPUT:-${GITHUB_ACTION_REF:-main}}"
+        if [[ ${GH_ACTION_REF_INPUT} ]]; then
+          echo "::warning::Using input 'gh_action_ref': Loading ansible-lint version ${action_ref}. This input should only be used in composite actions where built-in 'GH_ACTION_REF' is set to the parent action version. If possible, use the 'uses: ansible-lint@<version>' syntax instead."
+        else
+          echo "Using ansible-lint ref: $action_ref"
         fi
         echo "ACTION_REF=${action_ref}" >> "$GITHUB_ENV"
 

pyproject.toml

@@ -534,6 +534,9 @@ convention = "google"
 [tool.setuptools.dynamic]
 dependencies = {file = [".config/requirements.in"]}
 optional-dependencies.docs = {file = [".config/requirements-docs.in"]}
+# 'lock' will work only if you use a python version supported by the latest
+# release of ansible-core, otherwise installation will fail
+optional-dependencies.lock = {file = [".config/requirements-lock.txt"]}
 optional-dependencies.test = {file = [".config/requirements-test.in"]}
 
 [tool.setuptools_scm]