From 60b68140fb5c650c47019f5db238c0864dbd43ed Mon Sep 17 00:00:00 2001
From: Sorin Sbarnea <ssbarnea@redhat.com>
Date: Tue, 23 Mar 2021 10:20:53 +0000
Subject: [PATCH] Adding Azure Pipelines CI Documentation (#3081)

* Adding Azure Pipelines CI Documentation

##### SUMMARY
Adding Azure Pipelines documentation, tested within my own organisation.


##### ISSUE TYPE
- Docs Pull Request

+label: docsite_pr

* Trying to get the code block to show

* Inline code markdown fixed, textual improvement.

* Fixed whitespaces

Co-authored-by: Jim Speir <jimbo80982@gmail.com>
---
 docs/ci.rst | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/ci.rst b/docs/ci.rst
index fe24bc38a..a9d502ca3 100644
--- a/docs/ci.rst
+++ b/docs/ci.rst
@@ -159,6 +159,45 @@ Here is another example using Docker, virtualenv and tags on Centos 7.
       script:
         - molecule test
 
+Azure Pipelines
+^^^^^^^^^^^^^^^
+`Azure Pipelines`_ projects rely on the ``azure-pipelines.yml`` file within the root folder of a repository. There are a number of pre-requisites for running CI/CD within Azure on self-hosted runners if you intend on using the ``UsePythonVersion`` task. Details of this can be found in the `Use Python Version Task`_ documentation.
+
+.. code-block:: yaml
+
+  ---
+  trigger:
+  - master
+
+  pool:
+    vmImage: ubuntu-16.04
+
+  steps:
+
+  - checkout: git://project-name/role-name
+    path: role-name
+
+  - task: UsePythonVersion@0
+    inputs:
+      versionSpec: '3.8'
+
+  - script: python -m pip install "molecule[lint]" "python-vagrant" "molecule-vagrant" "ansible"
+    displayName: Install dependencies
+
+  - script: python -m pip install "python-tss-sdk"
+    displayName: Role-specific dependencies
+
+  - script: |
+      export PATH="$PATH:/home/<user>/.local/bin/"
+      cd $(Agent.BuildDirectory)/role-name
+      molecule test
+    displayName: Test relevant platforms
+
+Whilst the pipeline checks out your code initially as part of the pipeline task, by default, it checks it out into a directory named ``s`` within ``$(Agent.BuildDirectory)``. If you checkout one other repository, the ``s`` is substituted with the path provided in that checkout. If you checkout multiple roles (e.g. some private roles within your Azure organisation) then the ``s`` structure is used, hence the importance of the ``cd $(Agent.BuildDirectory)/role-name`` which ensures you are in the correct directory regardless of format. Check the `Azure Build Variables`_ documentation for more detailed information on these.
+
+The ``export PATH`` is required to ensure you can use the ``molecule``/``ansible`` shell scripts. Azure doesn't add these by default.
+
+
 Jenkins Pipeline
 ^^^^^^^^^^^^^^^^
 
@@ -356,5 +395,8 @@ conflict.
 .. _`Jenkins`: https://jenkins.io/doc/book/pipeline/jenkinsfile
 .. _`Gitlab`: https://gitlab.com
 .. _`Tox`: https://tox.readthedocs.io/en/latest
+.. _`Azure Pipelines`: https://azure.microsoft.com/en-gb/services/devops/pipelines/
 .. _`--parallel functionality`: https://tox.readthedocs.io/en/latest/config.html#cmdoption-tox-p
 .. _`issue1567_comment`: https://github.com/ansible-community/molecule/issues/1567#issuecomment-436876722
+.. _`Use Python Version Task`: https://docs.microsoft.com/en-us/azure/devops/pipelines/tasks/tool/use-python-version?view=azure-devops
+.. _`Azure Build Variables`: https://docs.microsoft.com/en-us/azure/devops/pipelines/build/variables?view=azure-devops&tabs=yaml#build-variables-devops-services