Add ansible-github-actions docs

.config/dictionary.txt

@@ -2,3 +2,6 @@ devel
 libera
 testenv
 Uninstallation
+netcommon
+Ansibuddy
+antsibull

docs/user-guide/ci-setup.md

@@ -0,0 +1,65 @@
+# Using the CI workflow
+
+The following GitHub Actions are to be placed added under `.github/workflows` directory as `{filename}.yaml`
+This GitHub Actions workflow automates a range of tasks integral to Ansible content development, encompassing changelog generation, linting, integration, sanity checks, and unit tests. The all_green job serves the purpose of verifying the successful completion of all preceding tasks.
+
+Filename: `test.yaml`
+
+```
+---
+name: "CI"
+
+concurrency:
+  group: ${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *'
+
+jobs:
+  changelog:
+    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/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
+    steps:
+      - run: >-
+          python -c "assert 'failure' not in
+          set([
+          '${{ needs.changelog.result }}',
+          '${{ needs.integration.result }}',
+          '${{ needs.sanity.result }}',
+          '${{ needs.unit-galaxy.result }}',
+          '${{ needs.ansible-lint.result }}'
+          ])"
+```
+
+The workflow run results in -
+
+![Alt text](./images/ci.png?raw=true "CI Run")
+
+The workflow uses tox-ansible, pytest-ansible to generate the matrix, which is used to run unit, sanity and integration tests.
+
+Refer to the [tox-ansible documentation] to see more options.
+
+[pytest-ansible]: https://ansible.readthedocs.io/projects/pytest-ansible/
+[tox-ansible documentation]: https://ansible.readthedocs.io/projects/tox-ansible/

docs/user-guide/content-release.md

@@ -0,0 +1,96 @@
+# Using the Release workflow
+
+The following GitHub Actions are to be placed added under `.github/workflows` directory as `{filename}.yaml`
+This GitHub action releases the collection in Ansible Automation Hub and Ansible Galaxy, it is dependent on the environment `release` which must contain the following secrets.
+
+`AH_TOKEN`: The Automation Hub token required for to interact with Ansible Automation Hub.
+`ANSIBLE_GALAXY_API_KEY`: A Galaxy token required to interact with Ansible Galaxy.
+
+Note - ansible-github-actions/release.yaml uses release_ah.yaml and release_galaxy.yaml internally.
+
+Filename: `release.yaml`
+
+```
+---
+name: "Release collection"
+on:
+  release:
+    types: [published]
+
+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 }}
+```
+
+The workflow run results in -
+
+![Alt text](./images/release.png?raw=true "Release collection")
+
+The release works in two parts, Automation hub release and then Ansible Galaxy release. If the Automation hub release fails, the Galaxy job is skipped.
+
+Example showing how only Automation hub release can be made, only `ah_token` would be required in those cases.
+
+### The release on AH workflow
+
+Filename: `release.yaml`
+
+```
+---
+name: "Release collection"
+on:
+  release:
+    types: [published]
+
+jobs:
+  release_automation_hub:
+    uses: ansible/ansible-github-actions/.github/workflows/release_ah.yaml@main
+    with:
+      environment: release
+    secrets:
+      ah_token: ${{ secrets.AH_TOKEN }}
+```
+
+Same for galaxy releases only, please refer to the `release_galaxy.yaml` and specify `ansible_galaxy_api_key` secret.
+
+## Detailed release process
+
+### Things to make sure of before release:
+
+#### Environments:
+
+The repo that is being released must have the following environments created:
+
+- **Name: release**
+
+  - `AH_TOKEN`
+  - `ANSIBLE_GALAXY_API_KEY`
+
+- **Name: push**
+
+  - `BOT_PAT`
+
+- `refresh_ah_token`: Make sure this workflow in netcommon has run successfully in the previous run. If not, it must be triggered to re-run and ensure it is successfully executed.
+
+#### Prepare the repo for release (draft_release workflow only uses BOT_PAT, i.e., Ansibuddy):
+
+This step is to be substituted by a manual run of the push workflow, which is currently not recommended as the behavior is unstable. In terms of generating a changelog.
+
+1. Start preparing the repo for release: Run `antsibull-changelog` on the repo locally, make a PR, and get it merged.
+2. Now we are set to release.
+
+Make sure `galaxy.yml` is in sync with the release version. The version pushed in Galaxy and AH is referenced from `version:` in `galaxy.yml`.
+
+#### Release process through GitHub:
+
+1. Go to the releases page in GitHub UI and create a new release.
+2. Create a new tag and name it in this format - `v[version_num]` - e.g., `v5.2.1`.
+   - Note: The `v` prefix exists in the GH tag and is redacted in AH and Galaxy releases.
+3. Name the title the same as the tag.
+4. Put in the changelog - which can be found in `CHANGELOG.rst` (RAW).
+5. Push the release button, and it will release the collection.
+6. Look out for the release action in the Actions tab. The AH release happens first, followed by the Galaxy release. If the AH release fails, the Galaxy release fails too.