The community.windows collection includes the community plugins supported by Ansible community to help the management of Windows hosts.

This collection has been tested against following Ansible versions: >=2.10.

Plugins and modules within a collection may be tested with only specific Ansible versions. A collection may contain metadata that identifies these versions. PEP440 is the schema used to describe the versions of Ansible.

Before using the Windows collection, you need to install it with the ansible-galaxy CLI:

ansible-galaxy collection install community.windows

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml using the format:

collections:
- name: community.windows

We welcome community contributions to this collection. If you find problems, please open an issue or create a PR against the Community Windows collection repository. See Contributing to Ansible-maintained collections for details.

See Developing modules for Windows for specifics on Windows modules.

You can also join us on:

IRC - #ansible-windows irc.libera.chat channel

See the Ansible Community Guide for details on contributing to Ansible.

This collection follows the Ansible project's Code of Conduct. Please read and familiarize yourself with this document.

Currently module documentation is generated manually using add_docs.py. This should be run whenever there are any major doc changes or additional plugins have been added to ensure a docpage is viewable online in this repo. The following commands will run the doc generator and create the updated doc pages under docs.

# This is the path to the ansible.windows checkout
COLLECTION_PATH=~/ansible_collections/community/windows

cd /tmp
git clone https://github.com/ansible-network/collection_prep.git
cd collection_prep
python add_docs.py -p "${COLLECTION_PATH}"

The tests directory contains configuration for running sanity and integration tests using ansible-test.

You can run the collection's test suites with the commands:

ansible-test sanity --docker
ansible-test windows-integration --docker

The current process for publishing new versions of the Windows Community Collection is manual, and requires a user who has access to the community namespace on Ansible Galaxy to publish the build artifact.

• Update galaxy.yml with the new version for the collection.
• Rebuild the plugin docs:

  pip install git+https://github.com/ansible-network/collection_prep
  collection_prep_add_docs --path ./ --branch-name main

• Update the CHANGELOG:
  • Make sure you have antsibull-changelog installed pip install antsibull-changelog.
  • Make sure there are fragments for all known changes in changelogs/fragments.
  • Add a new fragment with the header release_summary to give a summary on the release.
  • Run antsibull-changelog release.
• Commit the changes and wait for CI to be green
• Build and publish the collection to Galaxy:

  git clone https://github.com/ansible-collections/community.windows.git /tmp/community.windows
  ansible-galaxy collection build /tmp/community.windows --output-path /tmp/community.windows
  ansible-galaxy collection publish $(find /tmp/community.windows -maxdepth 1 -name 'community-windows-*.tar.gz') --token <API_KEY> -vv
  

After the version is published, verify it exists on the Windows Community Collection Galaxy page.

For more information about Ansible's Windows integration, join the #ansible-windows channel on libera.chat IRC, and browse the resources in the Windows Working Group Community wiki page.

• Ansible Collection overview
• Ansible User guide
• Ansible Developer guide
• Ansible Community code of conduct

GNU General Public License v3.0 or later

See COPYING to see the full text.