Document VCS integration in foreman_ansible plugin

guides/common/assembly_getting-started-with-ansible.adoc

@@ -6,6 +6,10 @@ include::modules/proc_configuring-your-project-to-run-ansible-roles.adoc[levelof
 
 include::modules/proc_enabling-ansible-integration-with-project.adoc[leveloffset=+1]
 
+include::modules/proc_setting-up-ansible-vcs-integration.adoc[leveloffset=+1]
+
+include::modules/proc_cloning-ansible-roles-from-vcs.adoc[leveloffset=+1]
+
 include::modules/proc_importing-ansible-roles-and-variables.adoc[leveloffset=+1]
 
 include::modules/proc_overriding-ansible-variables-in-project.adoc[leveloffset=+1]

guides/common/modules/proc_cloning-ansible-roles-from-vcs.adoc

@@ -0,0 +1,24 @@
+[id="cloning-ansible-roles-from-vcs-{context}"]
+= Cloning Ansible roles from VCS
+
+You can clone Ansible roles to your {SmartProxy} from the {ProjectWebUI}.
+
+.Prerequisites
+* A {SmartProxy} with VSC integration for Ansible.
+For more information, see xref:setting-up-vsc-integration-for-ansible_{context}[].
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Configure* > *Ansible* > *Roles*
+. Click on *Clone from VCS* in the toolbar.
+Follow the wizard to clone an Ansible role from VCS.
+
+Note that you can only clone Ansible roles through `http` and `https`.
+
+* Click *Examine* to select a git revision from the list of branches and tags.
+* Toggle between *Skipping existing* and *Update existing* to allow {Project} to override a given role if it is already present on the {SmartProxy}.
+. Click *Confirm* to clone Ansible roles from VCS to your {SmartProxy}.
+
+.Next steps
+* {Project} starts a task called `Clone Ansible role from VCS`.
+For more information, see {AdministeringDocURL}Managing_Tasks_admin[Managing Tasks] in _{AdministeringDocTitle}_.
+* Proceed with xref:Importing_Ansible_Roles_and_Variables_{context}[] after the task has finished successfully.

guides/common/modules/proc_configuring-your-project-to-run-ansible-roles.adoc

@@ -18,6 +18,7 @@ endif::[]
 * `/usr/share/ansible/roles`
 * `/etc/ansible/collections`
 * `/usr/share/ansible/collections`
+* `(optional) VCS_INTEGRATION_PATH/ansible/roles`
 
 Roles and collections from installed packages are placed under `/usr/share/ansible`.
 If you want to add custom roles or collections, place them under `/etc/ansible`.

guides/common/modules/proc_setting-up-ansible-vcs-integration.adoc

@@ -0,0 +1,46 @@
+[id="setting-up-vsc-integration-for-ansible_{context}"]
+= Setting up VCS integration for Ansible
+
+With VCS integration, you can clone Ansible roles from any remote git repository directly from the {ProjectWebUI}.
+
+.Procedure
+. Create the default directory:
++
+----
+# mkdir -p /var/lib/foreman-proxy/ansible/roles
+----
+. Assign the correct permissions:
++
+----
+# chmod -R 060 /var/lib/foreman-proxy/ansible/roles
+----
+. Add the directory to the group `foreman-proxy`:
++
+----
+# chgrp -R foreman-proxy /var/lib/foreman-proxy/ansible/roles
+----
+
+.Optional
+You may also choose a different directory to clone the roles into:
+
+* Create the directory:
++
+----
+mkdir -p CUSTOM_DIRECTORY/ansible/roles
+----
+* Assign the correct permissions and group as above
+* Pass `CUSTOM_DIRECTORY` to your {SmartProxy} via the environment variable `STATE_DIR`
++
+----
+STATE_DIR=CUSTOM_DIRECTORY
+----
+
+Finally, you need to enable `vcs_integration` in the {SmartProxy} settings
+
+.Procedure
+* Append the following line `/etc/foreman-proxy/settings.d/ansible.yml`:
++
+[source, yaml, options="nowrap", subs="verbatim,quotes,attributes"]
+----
+:vcs_integration: true
+----