Merge pull request #5 from KB-perByte/add_docs

Add readme and docs

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Community Code of Conduct
+
+Please see the official [Ansible Community Code of Conduct](https://docs.ansible.com/ansible/latest/community/code_of_conduct.html).

.github/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported Versions
+
+Ansible applies security fixes according to the 3-versions-back support
+policy. Please find more information in [our docs].
+
+## Reporting a Vulnerability
+
+We encourage responsible disclosure practices for security
+vulnerabilities. Please read our [policies for reporting bugs](https://docs.ansible.com/ansible/devel/community/reporting_bugs_and_features.html#reporting-a-bug)
+if you want to report a security issue that might affect Ansible.
+
+[our docs]: https://docs.ansible.com/ansible-core/devel/reference_appendices/release_and_maintenance.html#ansible-core-release-cycle

.github/workflows/ansible_lint.yaml

@@ -6,22 +6,64 @@ name: Lint
       - main
       - stable
       - release/v*
-  workflow_call: null
+  workflow_call:
+    inputs:
+      args:
+        description: Arguments to be passed to ansible-lint command.
+        required: false
+        default: ""
+        type: string
+      setup_python:
+        description: If false, this action will not setup python and will instead rely on the already installed python.
+        required: false
+        default: true
+        type: boolean
+      working_directory:
+        description: The directory where to run ansible-lint from. Default is `github.workspace`.
+        required: false
+        default: ""
+        type: string
 jobs:
   build:
     name: Ansible Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - name: Process inputs
+        id: inputs
+        shell: bash
+        run: |
+          if [[ -n "${{ inputs.working_directory }}" ]]; then
+            echo "working_directory=${{ inputs.working_directory }}" >> $GITHUB_OUTPUT
+          else
+            echo "working_directory=${{ github.workspace }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Generate .git/ansible-lint-requirements.txt
+        shell: bash
+        env:
+          GH_ACTION_REF: ${{ github.action_ref || 'main' }}
+        working-directory: ${{ steps.inputs.outputs.working_directory }}
+        run: |
+          wget --output-document=.git/ansible-lint-requirements.txt https://raw.githubusercontent.com/ansible/ansible-lint/$GH_ACTION_REF/.config/lock-requirements.txt
+
       - name: Set up Python
-        uses: actions/setup-python@v4
+        if: inputs.setup_python == 'true'
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.x
-      - name: Install ansible-lint and dependencies
+          cache: pip
+          cache-dependency-path: ${{ steps.inputs.outputs.working_directory }}/.git/ansible-lint-requirements.txt
+          python-version: "3.11"
+
+      - name: Install ansible-lint
         shell: bash
+        env:
+          GH_ACTION_REF: ${{ github.action_ref || 'main' }}
         run: |
-          python -m pip install --upgrade pip
-          pip install ansible ansible-lint
-      - name: Run Ansible-lint
+          cd $GITHUB_ACTION_PATH
+          pip install "ansible-lint[lock] @ git+https://github.com/ansible/ansible-lint@$GH_ACTION_REF"
+          ansible-lint --version
+
+      - name: Run ansible-lint
         shell: bash
-        run: ansible-lint
+        working-directory: ${{ steps.inputs.outputs.working_directory }}
+        run: ansible-lint ${{ inputs.args }}

README.md

@@ -1,6 +1,16 @@
+[![🧪 GitHub Actions CI/CD workflow tests badge]][GHA workflow runs list]
+[![pre-commit.ci status badge]][pre-commit.ci results page]
+
 # ansible-github-action
 
-test.yaml
+Combine GitHub Actions to create a streamlined workflow for testing Ansible collection repositories on GitHub.
+
+## Usage
+
+To use the action add the following step to your workflow file (e.g.
+`ansible/ansible-github-actions/.github/workflows/sanity.yaml@main`)
+
+Filename: `test.yaml`
 
 ```
 ---
@@ -10,7 +20,7 @@ concurrency:
   group: ${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
-on:  # yamllint disable-line rule:truthy
+on:
   pull_request:
     branches: [main]
   workflow_dispatch:
@@ -22,16 +32,19 @@ jobs:
     uses: ansible/ansible-github-actions/.github/workflows/changelog.yaml@main
     if: github.event_name == 'pull_request'
   ansible-lint:
-    uses: ansible/ansible-github-actions/.github/workflows/lint.yaml@main
+    uses: ansible/ansible-github-actions/.github/workflows/ansible_lint.yaml@main
   sanity:
     uses: ansible/ansible-github-actions/.github/workflows/sanity.yaml@main
   unit-galaxy:
     uses: ansible/ansible-github-actions/.github/workflows/unit.yaml@main
+  integration:
+    uses: ansible/ansible-github-actions/.github/workflows/integration.yaml@main
   all_green:
     if: ${{ always() }}
     needs:
       - changelog
       - sanity
+      - integration
       - unit-galaxy
       - ansible-lint
     runs-on: ubuntu-latest
@@ -40,70 +53,36 @@ jobs:
           python -c "assert 'failure' not in
           set([
           '${{ needs.changelog.result }}',
+          '${{ needs.integration.result }}',
           '${{ needs.sanity.result }}',
           '${{ needs.unit-galaxy.result }}'
           '${{ needs.ansible-lint.result }}'
           ])"
-
 ```
 
-release.yaml
+## Scope
 
-```
----
-name: "Release collection"
-on:  # yamllint disable-line rule:truthy
-  release:
-    types: [published]
+This combined GitHub Action covers the following action workflows:
 
-jobs:
-  release:
-    uses: ansible/ansible-github-actions/.github/workflows/release.yaml@main
-    with:
-      environment: release
-    secrets:
-      ah_token: ${{ secrets.AH_TOKEN }}
-      ansible_galaxy_api_key: ${{ secrets.ANSIBLE_GALAXY_API_KEY }}
+- Ansible-lint - checks playbooks for practices and behavior that could potentially be improved.
+- Sanity - Uses tox-ansible generates a testing matrix and runs sanity checks.
+- Unit - Installs the collection and all its dependencies from Galaxy and runs unit tests against a matrix generated via tox-ansible.
+- Integration - Installs the collection and all its dependencies from Galaxy and runs integration tests against a matrix generated via tox-ansible.
+- Changelog - Checks for a changelog entry with the PR, fails if missing or invalid.
+- Release - Push release to Automation Hub and Ansible Galaxy, requires (token/secrets).
+- Release Galaxy - Push a release to Ansible Galaxy only.
+- Release Automation Hub - Push a release to Ansible Automation Hub only.
+- Draft Release - Generates changelog entries for release, also raises a PR with changelog and galaxy file updated.
+- Check Label - Check if a valid label added to the PR is required by the release drafter.
 
-```
+# Contributing
 
-draft_release.yaml
+Please read [Contribution guidelines] if you wish to contribute.
 
-```
----
-name: "Draft release"
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-on:  # yamllint disable-line rule:truthy
-  workflow_dispatch:
-env:
-  NAMESPACE: ${{ github.repository_owner }}
-  COLLECTION_NAME: utils
-  ANSIBLE_COLLECTIONS_PATHS: ./
-jobs:
-  update_release_draft:
-    uses: ansible/ansible-github-actions/.github/workflows/draft_release.yaml@main
-    with:
-      repo: ${{ github.event.pull_request.head.repo.full_name }}
-    secrets:
-      BOT_PAT: ${{ secrets.BOT_PAT }}
+# Licensing
 
-```
+The ansible-github-actions project is distributed as [MIT License].
 
-check_label.yaml
+# Authors
 
-```
----
-name: "Check label"
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
-on:  # yamllint disable-line rule:truthy
-  pull_request_target:
-    types: [opened, labeled, unlabeled, synchronize]
-jobs:
-  check_label:
-    uses: ansible/ansible-github-actions/.github/workflows/check_label.yaml@main
-
-```
+ansible-github-actions is owned by [Ansible] by [Red Hat] project.