esp.bitbucket Ansible Collection

This Bitbucket Ansible Collection provides an easy way to manage Bitbucket Server resources / assets using Ansible.

Building collection

This section is intended for collection developers. If you only use the collection, check Installation section instead.

To build a collection, set version: x.y.z in your galaxy.yml file and run ansible-galaxy collection build from inside the root directory of the collection:

ansible-galaxy collection build --force --ignore-certs --no-deps

Alternatively, run build_collection.sh script from tools directory:

./tools/build_collection.sh

This creates a tarball of the built collection in the current directory which can be used to install the collection, e.g.:

ansible-galaxy collection install esp-bitbucket-1.3.1.tar.gz --force --ignore-certs --no-deps

Collection versions

Check the Frequently Asked Questions page.

Creating Git Tags with versions

You must create a git tag with new collection version and push this to Bitbucket. This way it will be possible to install required versions with ansible-galaxy command.

git commit -am "Commit message"
git tag -a 1.4.0 -m "version 1.4.0"
git push -u origin 1.4.0
git push

Installation

Preferred installation method is installing a collection from a git repository.

Create requirements.yml file and provide required version of the collection(s), e.g.:

collections:
  - name: https://bitbucket.example.com/scm/PROJECT/esp.bitbucket.git
    type: git
    version: 1.1.0
    #version: master    

Next, run ansible-galaxy command with requirements.yml file as argument:

ansible-galaxy collection install -r requirements.yml --force --ignore-certs --no-deps

Alternatively, you may provide a repository URL in ansible-galaxy command:

# Install a collection from a repository using the latest commit on the branch 'master'
ansible-galaxy collection install git+https://bitbucket.example.com/scm/PROJECT/esp.bitbucket.git --force --ignore-certs --no-deps

# Install a collection from a repository using version 1.1.0
ansible-galaxy collection install git+https://bitbucket.example.com/scm/PROJECT/esp.bitbucket.git,1.1.0 --force --ignore-certs --no-deps

For more info about installation and troubleshooting check the Frequently Asked Questions page

Samples

The project includes a catalog of ESP Ansible module samples that illustrate using the modules and roles to carry out common tasks.

The samples are organized in groups under the samples directory. Begin by reviewing the Readme.md file that you will find in each sample's root directory.

Documentation

To view the module documentation, use this command:

ansible-doc esp.bitbucket.[module_name]

Ansible Tower and AWX

esp.bitbucket Ansible Collection supports Ansible Tower and AWX.

Simply add a reference to the collection in your ${PROJECT_NAME}/collections/requirements.yml file explicitly providing required version, e.g.:

collections:
  - name: https://bitbucket.example.com/scm/PROJECT/esp.bitbucket.git
    type: git
    version: 1.1.0
    #version: master    

AWX automatically installs dependencies from the requirements.yml file. You don't need to take any action on AWX.

Note: you need ansible >= 2.10 on AWX to properly install ansible collections from requirements.yml file. Please select appriopriate custom virtual env in either project or job template definition.

Help

• For FAQs, check the Frequently Asked Questions page.
• To file bugs or feature requests, contact authors or contribute.

Changes

See CHANGELOG.

License

GPLv3 - GNU General Public License v3.0

Authors

• Krzysztof Lewandowski
• Pawel Smolarz