.ansible-lint

@@ -1,6 +0,0 @@
-# .ansible-lint
-warn_list:
-  - '204' # Lines should be less than 160 characters
-  - '701' # meta/main.yml should contain relevant info
-skip_list:
-  - '106' # Role name must match ^[a-z][a-z0-9_]+$ pattern

.gitignore

@@ -1,7 +0,0 @@
-inventory
-roles/*
-collections/*
-!roles/README.md
-!roles/requirements.yml
-!collections/README.md
-!collections/requirements.yml

.yamllint

@@ -1,7 +0,0 @@
----
-extends: default
-
-rules:
-  line-length:
-    max: 140
-    level: warning

README.md

@@ -29,4 +29,93 @@ This repository is for AWX templates.
 
 ## Guidelines
 
-These guidelines are on the Core Wiki.
+These are the general guidelines for creating and maintaining these repositories. Please read carefully to ensure that you are meeting the criteria.
+
+1. Copy this template into a new repository with the format `ansible-type-usage`. For example, if this is for ipa management, you could use a name like `ansible-ipa-management`.
+2. Change the top of the `README.md` from "Template" to an appropriate name for your repo.
+3. Modify the `README.md` file at the Provides/Information section of what these tasks do. Please be descriptive and list all of the playbooks and accompanying tasks (see the example). Hint: Use the `tree` command.
+4. List any requirements to run the playbooks, such as vars, mandatory or optional in playbooks. Optionally, you may list them in the `README.md` here.
+5. Run `pre-commit install` - There is already a provided `.pre-commit-config.yaml` with some default settings.
+6. (Optional) Remove everything starting at "Guidelines" in this README to reduce clutter.
+
+## GitLab Steps
+
+1. Create a new project
+2. Click "import project"
+3. Click "Repo by URL"
+4. Put in the URL: https://git.rockylinux.org/infrastructure/public/ansible/ansible-awx-template.git
+5. Type in the project name as outlined in `Guidelines` above
+6. Ensure your project URL and slug are appropriate
+
+## Designing Playbooks
+
+Generally, your playbooks should be doing the following:
+
+1. Checking if ansible can be ran on a specific host
+2. Asserting if variables are filled and are correctly formed
+3. Importing tasks from the `./tasks` directory
+4. Importing roles, if necessary
+5. Post tasks, if necessary
+
+**Note**: At no point should you be using `./tasks/main.yml`
+
+### Pre-flight and Post-flight tasks
+
+```
+  pre_tasks:
+    - name: Check if ansible cannot be run here
+      stat:
+        path: /etc/no-ansible
+      register: no_ansible
+
+    - name: Verify if we can run ansible
+      assert:
+        that:
+          - "not no_ansible.stat.exists"
+        success_msg: "We are able to run on this node"
+        fail_msg: "/etc/no-ansible exists - skipping run on this node"
+
+    # Assertions and other checks here
+
+  # Import roles/tasks here
+
+  post_tasks:
+    - name: Touching run file that ansible has ran here
+      file:
+        path: /var/log/ansible.run
+        state: touch
+        mode: '0644'
+        owner: root
+        group: root
+```
+
+### Comments
+
+Each playbook should have comments or a name descriptor that explains what the playbook does or how it is used. If not available, README-... files can be used in place, especially in the case of adhoc playbooks that take input. Documentation for each playbook/role does not have to be on this wiki. Comments or README's should be sufficient.
+
+### Tags
+
+Ensure that you use relevant tags where necessary for your tasks.
+
+### Playbook naming
+
+```
+init-* -> Starting infrastructure playbooks that run solo or import other
+          playbooks that start with import-
+adhoc  -> These playbooks are one-off playbooks that can be used on the CLI or
+          in AWX. These are typically for basic tasks.
+import -> Playbooks that should be imported from the top level playbooks
+role-* -> These playbooks call roles specifically for infrastructure tasks.
+          Playbooks that do not call a role should be named init or adhoc based
+          on their usage.
+```
+
+### Pre-commits / linting
+
+When pushing to your own forked version of this repository, pre-commit must run to verify your changes. They must be passing to be pushed up. This is an absolute requirement, even for roles.
+
+When the linter passes, the push will complete and you will be able to open a PR.
+
+## How are these repositories used?
+
+These repositories are generally cloned/pulled into AWX for the latest version, so they can be called within AWX either by hand or at a scheduled time.