ohioit · jacobeicher · Mar 26, 2022
diff --git a/.github/workflows/ansible-test.yml b/.github/workflows/ansible-test.yml
@@ -0,0 +1,42 @@
+name: ansible-test
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ansible_collections/ohioit/github
+
+    steps:
+      - name: Clone the repo
+        uses: actions/checkout@v2
+        with:
+          path: ansible_collections/ohioit/github
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: Install Ansible
+        run: pip install ansible==5.5
+
+      - name: Install PyGithub
+        run: pip install PyGithub==1.55
+
+      - name: Perform sanity testing with ansible-test on module files
+        run: ansible-test sanity --python 3.9 --skip-test import --skip-test ansible-doc --skip-test validate-modules plugins/modules/*
+
+      - name: Perform unit testing with ansible-test
+        uses: ansible-community/ansible-test-gh-action@release/v1
+        with:
+          ansible-core-version: stable-2.12
+          pre-test-cmd: echo This runs before the ansible-test invocation
+          python-version: 3.9
+          target-python-version: 3.9
+          testing-type: units
+          test-deps: >-
+            ansible.netcommon
+            ansible.utils
diff --git a/README.md b/README.md
@@ -1,2 +1,150 @@
 # Ansible Collection for GitHub
-The OHIO IT collection of Ansible modules for GitHub.
+
+### The OHIO IT collection of Ansible modules for GitHub.
+
+The collection includes a variety of Ansible modules to help automate the management of organizations, repositories, and user permissions in GitHub.
+
+---
+
+## Version Compatibility
+
+Tested against:
+`Ansible Version >=2.11`
+`Python >=3.8`
+`PyGitHub >=1.55`
+
+## Installation
+
+Install this collection via [Ansible Galaxy](https://galaxy.ansible.com/ohioit/github):
+
+```bash
+ansible-galaxy collection install ohioit.github
+```
+
+Content in this collection requires the [PyGitHub package](https://github.com/PyGithub/PyGithub) to interact with [GitHub REST API](https://docs.github.com/en/rest). You can install it with:
+
+```bash
+pip install PyGithub
+```
+
+## Included Content
+
+### Modules
+
+| Name                                                                                                                                             | Description                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| [repository_information](https://github.com/ohioit/ansible-collection-github/blob/main/docs/repository_information.rst) | Output repositories along with vital information from an (user specified) organization |
+| [collaborator_information](https://github.com/ohioit/ansible-collection-github/blob/main/docs/collaborator_information.rst) | View and manage repository collaborators |
+| [repository_webhooks](https://github.com/ohioit/ansible-collection-github/blob/main/docs/repository_webhooks.rst) | A module that manages a repository's webhooks |
+| [branch_protection](https://github.com/ohioit/ansible-collection-github/blob/main/docs/branch_protection.rst) | A module that allows the modification of branch protections. |
+| [general_repository](https://github.com/ohioit/ansible-collection-github/blob/main/docs/general_repository.rst) | A module that manages a repository in an organization. |
+
+## Usage
+
+### Repository Information
+
+```
+  - name: "List GitHub repositories within a non-enterprise organization"
+    ohioit.github.repository_information:
+      token: "<API TOKEN>"
+      organization_name: "<ORGANIZATION NAME>"
+    register: result
+
+  - name: "List GitHub repositories within an enterprise organization"
+    ohioit.github.repository_information:
+      token: "<TOKEN>"
+      organization_name: "<ORGANIZATION NAME>"
+      enterprise_url: "https://github.<ENTERPRISE DOMAIN>/api/v3/"
+    register: result    
+```
+### Collaborator Information
+
+```
+    - name: "List the collaborators of a repository"
+      ohioit.github.collaborator_information:
+        access_token: "<API TOKEN>"
+        organization: "<ORGANIZATION NAME>"
+        api_url: "https://github.<ENTERPRISE DOMAIN>/api/v3/"
+        repository: "<REPOSITORY NAME>"
+        collaborator: "<VALID GITHUB USERNAME>"
+        permission: <pull, push, or admin>
+        state: <present or absent> 
+```
+### Webhook
+```
+    - name: "Manage webhooks of a GitHub repository"
+      ohioit.github.repository_webhooks:
+        state: <present or absent> 
+        access_token: "<API TOKEN>"
+        organization: "<ORGANIZATION NAME>"
+        api_url: "https://github.<ENTERPRISE DOMAIN>/api/v3/"
+        repository: "<REPOSITORY NAME>"
+        url: "<RECEIVING URL>"
+        events:
+          - "<LIST EVENT 1>"
+          - "<LIST EVENT 2>"
+        content_type: <json or form>
+```
+### Branch Protection
+
+```
+    - name: "Manage the branch protections rules of a branch"
+      ohioit.github.branch_protection:
+        access_token: "<API TOKEN>"
+        organization: "<ORGANIZATION NAME>"
+        api_url: "https://github.<ENTERPRISE DOMAIN>/api/v3/"
+        repository: "<REPOSITORY NAME>"
+        branch: "<BRANCH NAME>"
+        state: "<present or absent>"
+        branch_protections:
+          strict: <true or false>
+          contexts: ["<EXAMPLE: default or ci-test>", ...]
+          enforce_admins: <true or false>
+          dismissal_users: ["<GITHUB USERNAMES>", ...]
+          dismissal_teams: ["<GITHUB TEAMS>", ...]
+          dismiss_stale_reviews: <true or false>
+          require_code_owner_reviews: <true or false>
+          required_approving_review_count: <INTEGER>
+          user_push_restrictions: ["<GITHUB USERNAMES>", ...]
+          team_push_restrictions: ["<GITHUB TEAMS>", ...]
+```
+### General Repository
+
+```
+    - name: "Manage a repository within an enterprise organization"
+      ohioit.github.general_repository:
+        access_token: "<API TOKEN>"
+        organization: "<ORGANIZATION NAME>"
+        api_url: "https://github.<ENTERPRISE DOMAIN>/api/v3/"
+        repository: "<REPOSITORY NAME>"
+        private: <true or false>
+        description: "<DESCRIPTION OF REPOSITORY>"
+        homepage: "<HOMEPAGE NAME>"
+        has_issues: <true or false>
+        has_wiki: <true or false>
+        has_downloads: <true or false>
+        has_projects: <true or false>
+        team_id: <INTEGER>
+        auto_init: <true or false>
+        license_template: "<LICENSING GUIDLINES example: gpl-3.0>"
+        gitignore_template: "<SUPPORTED PROGRAMMING LANGUAGE>"
+        allow_squash_merge: <true or false>
+        allow_merge_commit: <true or false>
+        allow_rebase_merge: <true or false>
+        delete_branch_on_merge: <true or false>
+        state: <present or absent>
+```
+
+###### _**NOTE**: Tokens should be encrypted and only decrypted at runtime_
+
+## Testing with 'ansible-test'
+
+Testing has been made available using the [ansible-test](https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html). These tests include [unit](https://github.com/senior-design-21-22/ansible-collection-github/blob/development/docs/unit_testing.rst), [sanity](https://github.com/senior-design-21-22/ansible-collection-github/tree/repo-information-module/unit/sanity), [integration](https://github.com/senior-design-21-22/ansible-collection-github/blob/development/docs/integration_testing.rst).
+
+The tests are runnable using the following commands:
+
+```bash
+ansible-test units --python 3.<YOUR PYTHON VERSION> --venv
+ansible-test sanity --python 3.<YOUR PYTHON VERSION> plugins/modules/*
+ansible-test integration --python 3.<YOUR PYTHON VERSION>
+```
diff --git a/docs/integration_testing.rst b/docs/integration_testing.rst
@@ -0,0 +1,58 @@
+.. _Integration_Testing:
+
+
+********************
+Integration Testing
+********************
+
+**These steps may be taken to complete integration testing of ansible-collection-github modules**
+
+
+Version added: 0.0.1
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- This article contains the necessary requirements and steps to successfully run integration tests against the ansible-collection-github modules
+
+Requirements
+------------
+- Regular Github token
+- Enterprise Github token
+- Organization name
+- Directory ``/tests/integration/vars/args.yaml`` needs to be populated with:
+
+.. code-block:: yaml
+
+   ---
+   token: "[regular_github_token]"
+   organization_name: "[regular_github_name]"
+   enterprise_token: "[enterprise_github_token]"
+   enterprise_organization_name: "[enterprise_organization_name]"
+   enterprise_url: "[enterprise_url]"
+
+
+Running Integration Tests
+----------
+
+.. note::
+As of now, running the integration tests takes the same arguments needed to run the complete module
+
+#. Locally running the playbook with the command ``ansible-playbook integration_test.yaml``
+
+
+Status
+------
+
+
+Authors
+~~~~~~~
+
+- Brad Golski (@bgolski)
+- Jacob Eicher (@jacobeicher)
+- Nolan Khounborin (@khounborinn)
+- Tyler Zwolenik (@TylerZwolenik)