Merge pull request #3 from ansible-actions/docs

install requirements from file and explain vars

Author: DO1JLR

Diff for: README.md

@@ -1,35 +1,13 @@
  Action Ansible Linting
-===============================
+========================
 
-Linting Ansible roles...
+Linting ansible roles using the ansible-lint package directly from pypi.
 
-Work in Progress...
+Optionally it is possible to install some requirements like ansible collections, roles or pip packages. For more details about it, have a look at the Variables
 
-```yml
-inputs:
-  target:
-    description: |
-      Target for ansible linter
-      For example './', 'roles/my_role/' or 'site.yml'
-    required: true
-  required_collections:
-    description: |
-      You can define a required ansible collection here.
-      They will be installed using ansible-galaxy collection install <YourInput>.
-    required: false
-  required_roles:
-    description: |
-      You can define a required ansible role here.
-      They will be installed using ansible-galaxy role install <YourInput>.
-    required: false
-  python_dependency:
-    description: |
-      Install a Python Package using pip
-      They will be installed using pip install <YourInput>.
-    required: false
-```
+## Usage
 
-## Example Setup
+Example of ``.github/workflows/ansible-linting-check.yml``
 ```yaml
 ---
 name: Ansible Lint check
@@ -51,7 +29,30 @@ jobs:
           fetch-depth: 0
 
       - name: Run ansible-lint
-        uses: ansible-actions/[email protected]
+        uses: ansible-actions/[email protected]
+        with:
+          target: "./"
+```
+
+This will run the command ``ansible-lint ./``
+
+You can install some reuqirements, example:
+```yml
+[...]
         with:
-          target: "site.yml"
+          target: "./"
+          required_collections: 'community.general'
+          python_dependency: 'jmespath'
 ```
+*This will install the community.general collections as well as the jmespath pip package.*
+
+## Variables
+
+| name | required | description | example values |
+| --- | --- | --- | --- |
+| ``target`` | true | Target for ansible linter | ``./`` or ``site.yml`` or ``path/to/ansible/`` |
+| ``required_collections`` | - | define one ansible collection to install | ``community.general`` |
+| ``collections_yml`` | - | define path of yml file for installing multiple ansible collections | ``requirements.yml`` |
+| ``required_roles`` | - | define one ansible role to install | ``namespace.rolename`` |
+| ``python_dependency`` | - | define one pip package to install | ``jmespath`` |
+| ``python_dependency_file`` | - | define path of txt file for installing multiple python packages | ``requirements.txt`` |

Diff for: action.yml

@@ -12,26 +12,38 @@ inputs:
   required_collections:
     description: |
       You can define a required ansible collection here.
-      They will be installed using ansible-galaxy collection install <YourInput>.
+      They will be installed using ansible-galaxy collection install <YourInput> --upgrade.
+    required: false
+  collections_yml:
+    description: |
+      Install multiple Collections, defined from requirements.yml file
+      They will be installed using ansible-galaxy collection install -r <YourInput> --upgrade.
     required: false
   required_roles:
     description: |
       You can define a required ansible role here.
-      They will be installed using ansible-galaxy role install <YourInput>.
+      They will be installed using ansible-galaxy role install <YourInput> --upgrade.
     required: false
   python_dependency:
     description: |
       Install a Python Package using pip
-      They will be installed using pip install <YourInput>.
+      They will be installed using pip install --upgrade <YourInput>.
+    required: false
+  python_dependency_file:
+    description: |
+      Install a Python Packages from file using pip
+      They will be installed using pip install --upgrade -r <YourInput>.
     required: false
 runs:
   using: docker
   image: Dockerfile
   env:
     TARGET: ${{ inputs.target }}
     REQCOLLECTIONS: ${{ inputs.required_collections }}
+    COLLECTIONSYML: ${{ inputs.collections_yml }}
     REQROLES: ${{ inputs.required_roles }}
     PIPPACKAGE: ${{ inputs.python_dependency }}
+    PIPPACKAGETXT: ${{ inputs.python_dependency_file }}
 branding:
   icon: 'check-circle'
   color: 'blue'

Diff for: ansible_docker.py

@@ -60,6 +60,8 @@ def run_command(self, command):
     ENV_REQUIRED_COLLECTION_NAME = "REQCOLLECTIONS"
     ENV_REQUIRED_ROLE_NAME = "REROLE"
     ENV_PIPPACKAGE_NAME = "PIPPACKAGE"
+    ENV_PIPPACKAGE_TXT_NAME = "PIPPACKAGETXT"
+    ENV_COLLECTIONS_YML_NAME = "COLLECTIONSYML"
 
     # check for target variable
     env_target = EnvironmentManager(ENV_TARGET_NAME)
@@ -72,36 +74,57 @@ def run_command(self, command):
     env_collection = EnvironmentManager(ENV_REQUIRED_COLLECTION_NAME)
     reqired_collection = env_collection.check_optional_environment_variable()
 
+    # check for required collection variable
+    env_collection_yml = EnvironmentManager(ENV_COLLECTIONS_YML_NAME)
+    reqired_collection_yml = env_collection_yml.check_optional_environment_variable()
+
     # check for required role variable
     env_role = EnvironmentManager(ENV_REQUIRED_ROLE_NAME)
     reqired_role = env_role.check_optional_environment_variable()
 
-    # check for required role variable
+    # check for install pip packages variable
     env_pip = EnvironmentManager(ENV_PIPPACKAGE_NAME)
     pip_pkg = env_pip.check_optional_environment_variable()
 
+    # check for install packages.txt variable
+    env_pip_txt = EnvironmentManager(ENV_PIPPACKAGE_TXT_NAME)
+    pip_pkg_txt = env_pip_txt.check_optional_environment_variable()
+
     # run ansible commands
     ansible_version_checker = AnsibleCommandExecution()
 
-    # Optionally install required ansible collections
+    # Optionally install required ansible collections directly
     if bool(reqired_collection):
         ansible_command = ["ansible-galaxy", "collection", "install",
                           f"{reqired_collection}", "--upgrade"]
         version_info = ansible_version_checker.run_command(ansible_command)
         print(f"COLLECTION INSTALL SUCCESSFUL\n{version_info}")
 
+    # Optionally install required ansible collections from yml file
+    if bool(reqired_collection_yml):
+        ansible_command = ["ansible-galaxy", "collection", "install", "-r",
+                          f"{reqired_collection_yml}", "--upgrade"]
+        version_info = ansible_version_checker.run_command(ansible_command)
+        print(f"COLLECTION.YML INSTALL SUCCESSFUL\n{version_info}")
+
     # Optionally install required ansible roles
     if  bool(reqired_role):
         ansible_command = ["ansible-galaxy", "role", "install", f"{reqired_role}", "--upgrade"]
         version_info = ansible_version_checker.run_command(ansible_command)
         print(f"ROLE INSTALL SUCCESSFUL\n{version_info}")
 
-    # Optionally install pip package
+    # Optionally install pip package directly
     if  bool(pip_pkg):
         ansible_command = ["pip", "install", "--upgrade", f"{pip_pkg}"]
         version_info = ansible_version_checker.run_command(ansible_command)
         print(f"PIP PACKAGE INSTALL SUCCESSFUL\n{version_info}")
 
+    # Optionally install pip package from file
+    if  bool(pip_pkg_txt):
+        ansible_command = ["pip", "install", "--upgrade", "-r",  f"{pip_pkg_txt}"]
+        version_info = ansible_version_checker.run_command(ansible_command)
+        print(f"PIP PACKAGE.TXT INSTALL SUCCESSFUL\n{version_info}")
+
     # run ansible lint
     ansible_command = ["ansible-lint", f"{target}"]
     linter_run = ansible_version_checker.run_command(ansible_command)