BuildTools is a collection of scripts that support the University of Oregon's Network and Telecom Services team (NTS)
continuous integration and deployment solutions. E.g. this solution is used in Jenkinsfile pipelines.
[](https://badge.fury.io/py/ntsbuildtools)
# Install BuildTools
BuildTools is packaged as `ntsbuildtools` and provided in the Python Package Index (PyPI).
So, simply use pip to install BuildTools.
pip install ntsbuildtools
# BuildTools Usage
With BuildTools installed, the `buildtools` CLI utility should now be available in your shell.
$ buildtools --version
BuildTools Version: 1.3.5
Below is an example of posting a comment onto an existing BitBucket Pull Request.
$ buildtools post bitbucket pr-comment \
--bitbucket-url https://git.uoregon.edu \
--user rleonar7 \
--password SuperSecretPassword \
--project ISN \
--repo buildtools \
--pull-request-id 2 \
--message "Hello, world! I am BuildTools!"
## BuildTools Capabilities
BuildTools has many capabilities. These capabilities are provided as subcommands.
To discover the subcommands available in your version of BuildTools, use the `--help` argument anywhere in the CLI.
> BuildTools capabilities can discovered much more easily when using tab completion -- **how to enable tab completion via `argcomplete` is discussed below.**
In the example below, we see how the `--help` flag informs us that the `buildtools post bitbucket pr-comment` command is available and how to run it!
$ buildtools --help
usage: buildtools [-h] [--version] [--bitbucket-url BITBUCKET_URL] {post,parse} ...
positional arguments:
{post,parse}
post Make an HTTP POST to a target.
parse Parse some input (typically from a file).
$ buildtools post --help
usage: buildtools post [-h] {bitbucket,teams,github} ...
positional arguments:
{bitbucket,teams,github}
bitbucket Target Bitbucket.
teams Target Microsoft Teams.
github Target GitHub.
$ buildtools post bitbucket --help
usage: buildtools post bitbucket [-h] {build-status,pr-comment} ...
positional arguments:
{build-status,pr-comment}
build-status Set the "Build Status" in Bitbucket for a particular git commit.
pr-comment Posts a comment to a Bitbucket pull request, with optional arguments for 'Jenkins build
annotations', indicating build status, encasing content in 'diff markdown', and more!
$ buildtools post bitbucket pr-comment --help
usage: buildtools post bitbucket pr-comment [-h] [--version] [--bitbucket-url BITBUCKET_URL]
(--message COMMENT_MESSAGE | --file COMMENT_FILE | --json JSON_OUTPUT | --json-file JSON_FILE)
--user USER --password PASSWORD --project PROJECT
--repo REPO --pull-request-id PULL_REQUEST_ID
[--diff-markdown]
[--code-markdown]
[--max-comment-size MAX_COMMENT_SIZE] [--tail TAIL]
[--build-annotation]
[--playbook-limit PLAYBOOK_LIMIT]
[--build-id BUILD_ID] [--build-url BUILD_URL]
[--build-status {SUCCESS,UNSTABLE,FAILURE,NOT_BUILD,ABORTED}]
optional arguments:
-h, --help show this help message and exit
--version show program's version number and exit
--bitbucket-url BITBUCKET_URL
URL for Bitbucket. [env var: BITBUCKET_URL]
--message COMMENT_MESSAGE, -m COMMENT_MESSAGE
Provide the comment as a message on the command line.
--file COMMENT_FILE, -f COMMENT_FILE
Provide the comment in a file.
--json JSON_OUTPUT, -j JSON_OUTPUT
Provide ansible JSON output as a message on the command line (which will
be parsed to extract build-status info). NOTE: Additional 'formatting'
arguments, such as '--code-markdown', are ignored when using json input.
--json-file JSON_FILE
Provide ansible JSON output as a file (which will be parsed to extract
build-status info). NOTE: Additional 'formatting' arguments, such as '--
code-markdown', are ignored when using json input.
--user USER Bitbucket user that will be used to authenticate to Bitbucket. [env var:
BITBUCKET_USER]
--password PASSWORD Bitbucket password (or Personal Access Token) for the Bitbucket user.
[env var: BITBUCKET_PASSWORD]
--project PROJECT The Bitbucket project key for the project where the pull request exists.
[env var: BITBUCKET_PROJECT]
--repo REPO The Bitbucket repository slug for the repository where the pull request
exists. [env var: BITBUCKET_REPO]
--pull-request-id PULL_REQUEST_ID
The ID of the Bitbucket pull request to be commented on. [env var: PR_ID]
formatting:
--diff-markdown Wrap the provided comment in diff markdown. E.g. ```diff \{comment\}) ```
--code-markdown Wrap the provided comment in code markdown. E.g. ``` \{comment\}) ```
--max-comment-size MAX_COMMENT_SIZE
Fragment the comment into based on the maximum comment size.
--trim TRIM Only print the last `TRIM` lines of the provided message/file.
### Tab Completion? Yes, please!
BuildTools works as a CLI by default, and can support tab completion via the [`argcomplete` module](https://kislyuk.github.io/argcomplete/).
$ buildtools (double press 'tab' to see possible commands)
--bitbucket-url --help --version -h parse post
$ buildtools post (double press 'tab')
--help -h bitbucket github teams
$ buildtools post bitbucket (double press 'tab')
--help -h build-status pr-comment
$ buildtools post bitbucket pr-comment
Unfortunately, this does not work 'out of the box' without doing some 'bash configuration.'
So, run the following commands to enable argcomplete in your bash session:
pip install argcomplete
eval "$(register-python-argcomplete buildtools)"
#### Tab Completion for *all* bash sessions
If you want `buildtools` tab completion to work for *all* your bash sessions, we just need to install argcomplete for your user and add a line to your `bashrc` file.
Install argcomplete to your Python user site-package:
deactivate # (if currently in a Python venv)
pip3 install --user argcomplete
Add the following to your `~/.bashrc`:
if [ -x "register-python-argcomplete" ] ; then
eval "$(register-python-argcomplete buildtools)"
fi
Changelog
=========
This is our project [Changelog](https://keepachangelog.com/en/1.1.0/)
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
> We started tracking this changelog as of version 3.0.0.
## [4.0.11] - Apr 9, 2024
* Internal-only change: Update CICD workflow to use [`ntsjenkins` shared library](https://confluence.uoregon.edu/x/TQRaGw)
## [4.0.10] - Dec 19, 2023
### Changed
* Fix `infer ansible playbook-limit` when Ansible group_vars or host_vars has nested folders.
* The fix: Always use the filepath-token that comes just after 'group_vars' or 'host_vars'
* Test `buildtools infer ansible playbook-limit` using Ansible group names with underscores
* Enable code coverage on NTS Jenkins.
## [4.0.9] - Oct 5, 2023
### Changed
* `buildtools post teams card pull-request` has changed some arguments to optional (instead of 'required').
* pull_request_author
* pull_request_title
* `buildtools parse ansible json` will now display all "failures" before displaying any "diffs"
## [4.0.7]
* Update "`infer ansible playbook-limit`" CLI endpoint.
* Handle for Ansible's range syntax in loaded inventory/hosts files. Ex. `test[01:99].com` will now work!
## [4.0.6]
* Update "`infer ansible playbook-limit`" CLI endpoint.
* Ignore any 'vars' section that exist in provided 'inventory (hosts) .ini-style file'
## [4.0.5]
* Refactor "`infer ansible playbook-limit`" CLI endpoint.
* Rewrite and simplify the 'infer playbook limit' algorithm.
* Collapse entire `ansible.PlaybookLimit` class to become just the
`ansible.InventoryTree.infer_playbook_limit` method.
* Ensure that usage message (e.g. `--help`) is properly filled in.
## [4.0.4]
* Refactor internal `ansible.InventoryTree` data structure.
* Adding unit testing.
* Simplifying internal building and searching algorithms.
## [4.0.2]
* `parse ansible json` CLI endpoint can now parse Ansible *loop* results (recursively).
## [4.0.1]
* Fix Python 3.6 support.
## [4.0.0]
> Yanked from PyPI due to continued Python 3.6 incompatibility.
* Added support for Python 3.6
* Adding release notes and improve `docs/`.
* **Backwards incompatible change:** Removed buggy '--tail' argument and code from `post teams card` CLI endpoint.
* Replaced '--tail' with '--trim'
* 'trim' cuts off the end of the message instead of the beginning.
## [3.0.2]
* Fixed Source Distribution, to include all `docs/` and other required dependencies.
* Rewrite of the CLI framework.
* Rewrite of 'Parsing Ansible JSON' modules/packages, to capture more error messages successfully.
* Added `--crucial-task` and `--crucial-task-type` filter parameters to `parse ansible json`.
* Addition of `docs/` directory (driven via mkdocs).
## [3.0.1]
> Yanked from PyPI due to Broken Source Distribution.
## [3.0.0]
> Yanked from PyPI due to Broken Source Distribution.
Raw data
{
"_id": null,
"home_page": "https://git.uoregon.edu/projects/ISN/repos/buildtools/browse",
"name": "ntsbuildtools",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Jenkins, NTS, UO, CLI, Integrations, API",
"author": "Network & Telecom Svcs (University of Oregon)",
"author_email": "rleonar7@uoregon.edu",
"download_url": null,
"platform": null,
"description": "BuildTools is a collection of scripts that support the University of Oregon's Network and Telecom Services team (NTS) \ncontinuous integration and deployment solutions. E.g. this solution is used in Jenkinsfile pipelines.\n\n[](https://badge.fury.io/py/ntsbuildtools)\n\n# Install BuildTools\n\nBuildTools is packaged as `ntsbuildtools` and provided in the Python Package Index (PyPI).\nSo, simply use pip to install BuildTools.\n\n pip install ntsbuildtools\n\n# BuildTools Usage\n\nWith BuildTools installed, the `buildtools` CLI utility should now be available in your shell.\n\n $ buildtools --version\n BuildTools Version: 1.3.5\n\nBelow is an example of posting a comment onto an existing BitBucket Pull Request.\n\n $ buildtools post bitbucket pr-comment \\\n --bitbucket-url https://git.uoregon.edu \\\n --user rleonar7 \\ \n --password SuperSecretPassword \\ \n --project ISN \\\n --repo buildtools \\\n --pull-request-id 2 \\ \n --message \"Hello, world! I am BuildTools!\"\n\n\n\n## BuildTools Capabilities\n\nBuildTools has many capabilities. These capabilities are provided as subcommands. \nTo discover the subcommands available in your version of BuildTools, use the `--help` argument anywhere in the CLI. \n\n> BuildTools capabilities can discovered much more easily when using tab completion -- **how to enable tab completion via `argcomplete` is discussed below.**\n\nIn the example below, we see how the `--help` flag informs us that the `buildtools post bitbucket pr-comment` command is available and how to run it!\n\n $ buildtools --help\n usage: buildtools [-h] [--version] [--bitbucket-url BITBUCKET_URL] {post,parse} ...\n \n positional arguments:\n {post,parse}\n post Make an HTTP POST to a target.\n parse Parse some input (typically from a file).\n\n $ buildtools post --help\n usage: buildtools post [-h] {bitbucket,teams,github} ...\n \n positional arguments:\n {bitbucket,teams,github}\n bitbucket Target Bitbucket.\n teams Target Microsoft Teams.\n github Target GitHub.\n\n $ buildtools post bitbucket --help\n usage: buildtools post bitbucket [-h] {build-status,pr-comment} ...\n \n positional arguments:\n {build-status,pr-comment}\n build-status Set the \"Build Status\" in Bitbucket for a particular git commit.\n pr-comment Posts a comment to a Bitbucket pull request, with optional arguments for 'Jenkins build \n annotations', indicating build status, encasing content in 'diff markdown', and more!\n\n $ buildtools post bitbucket pr-comment --help\n usage: buildtools post bitbucket pr-comment [-h] [--version] [--bitbucket-url BITBUCKET_URL]\n (--message COMMENT_MESSAGE | --file COMMENT_FILE | --json JSON_OUTPUT | --json-file JSON_FILE)\n --user USER --password PASSWORD --project PROJECT\n --repo REPO --pull-request-id PULL_REQUEST_ID\n [--diff-markdown]\n [--code-markdown]\n [--max-comment-size MAX_COMMENT_SIZE] [--tail TAIL]\n [--build-annotation]\n [--playbook-limit PLAYBOOK_LIMIT]\n [--build-id BUILD_ID] [--build-url BUILD_URL]\n [--build-status {SUCCESS,UNSTABLE,FAILURE,NOT_BUILD,ABORTED}]\n \n optional arguments:\n -h, --help show this help message and exit\n --version show program's version number and exit\n --bitbucket-url BITBUCKET_URL\n URL for Bitbucket. [env var: BITBUCKET_URL]\n --message COMMENT_MESSAGE, -m COMMENT_MESSAGE\n Provide the comment as a message on the command line.\n --file COMMENT_FILE, -f COMMENT_FILE\n Provide the comment in a file.\n --json JSON_OUTPUT, -j JSON_OUTPUT\n Provide ansible JSON output as a message on the command line (which will\n be parsed to extract build-status info). NOTE: Additional 'formatting'\n arguments, such as '--code-markdown', are ignored when using json input.\n --json-file JSON_FILE\n Provide ansible JSON output as a file (which will be parsed to extract\n build-status info). NOTE: Additional 'formatting' arguments, such as '--\n code-markdown', are ignored when using json input.\n --user USER Bitbucket user that will be used to authenticate to Bitbucket. [env var:\n BITBUCKET_USER]\n --password PASSWORD Bitbucket password (or Personal Access Token) for the Bitbucket user.\n [env var: BITBUCKET_PASSWORD]\n --project PROJECT The Bitbucket project key for the project where the pull request exists.\n [env var: BITBUCKET_PROJECT]\n --repo REPO The Bitbucket repository slug for the repository where the pull request\n exists. [env var: BITBUCKET_REPO]\n --pull-request-id PULL_REQUEST_ID\n The ID of the Bitbucket pull request to be commented on. [env var: PR_ID]\n \n formatting:\n --diff-markdown Wrap the provided comment in diff markdown. E.g. ```diff \\{comment\\}) ```\n --code-markdown Wrap the provided comment in code markdown. E.g. ``` \\{comment\\}) ```\n --max-comment-size MAX_COMMENT_SIZE\n Fragment the comment into based on the maximum comment size.\n --trim TRIM Only print the last `TRIM` lines of the provided message/file.\n\n### Tab Completion? Yes, please!\n\nBuildTools works as a CLI by default, and can support tab completion via the [`argcomplete` module](https://kislyuk.github.io/argcomplete/).\n\n $ buildtools (double press 'tab' to see possible commands) \n --bitbucket-url --help --version -h parse post \n $ buildtools post (double press 'tab')\n --help -h bitbucket github teams \n $ buildtools post bitbucket (double press 'tab')\n --help -h build-status pr-comment \n $ buildtools post bitbucket pr-comment\n\nUnfortunately, this does not work 'out of the box' without doing some 'bash configuration.'\nSo, run the following commands to enable argcomplete in your bash session:\n \n pip install argcomplete\n eval \"$(register-python-argcomplete buildtools)\"\n\n#### Tab Completion for *all* bash sessions\n\nIf you want `buildtools` tab completion to work for *all* your bash sessions, we just need to install argcomplete for your user and add a line to your `bashrc` file.\n\nInstall argcomplete to your Python user site-package:\n\n deactivate # (if currently in a Python venv)\n pip3 install --user argcomplete\n\nAdd the following to your `~/.bashrc`:\n\n if [ -x \"register-python-argcomplete\" ] ; then\n eval \"$(register-python-argcomplete buildtools)\"\n fi\n\n\nChangelog\n=========\n\nThis is our project [Changelog](https://keepachangelog.com/en/1.1.0/)\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n> We started tracking this changelog as of version 3.0.0.\n\n## [4.0.11] - Apr 9, 2024\n\n* Internal-only change: Update CICD workflow to use [`ntsjenkins` shared library](https://confluence.uoregon.edu/x/TQRaGw)\n\n## [4.0.10] - Dec 19, 2023\n\n### Changed\n\n* Fix `infer ansible playbook-limit` when Ansible group_vars or host_vars has nested folders.\n * The fix: Always use the filepath-token that comes just after 'group_vars' or 'host_vars'\n* Test `buildtools infer ansible playbook-limit` using Ansible group names with underscores\n* Enable code coverage on NTS Jenkins.\n\n## [4.0.9] - Oct 5, 2023\n\n### Changed\n\n* `buildtools post teams card pull-request` has changed some arguments to optional (instead of 'required').\n * pull_request_author\n * pull_request_title\n* `buildtools parse ansible json` will now display all \"failures\" before displaying any \"diffs\" \n\n## [4.0.7]\n\n* Update \"`infer ansible playbook-limit`\" CLI endpoint.\n * Handle for Ansible's range syntax in loaded inventory/hosts files. Ex. `test[01:99].com` will now work!\n\n## [4.0.6]\n\n* Update \"`infer ansible playbook-limit`\" CLI endpoint.\n * Ignore any 'vars' section that exist in provided 'inventory (hosts) .ini-style file' \n\n## [4.0.5]\n\n* Refactor \"`infer ansible playbook-limit`\" CLI endpoint.\n * Rewrite and simplify the 'infer playbook limit' algorithm.\n * Collapse entire `ansible.PlaybookLimit` class to become just the \n `ansible.InventoryTree.infer_playbook_limit` method.\n* Ensure that usage message (e.g. `--help`) is properly filled in.\n\n## [4.0.4]\n\n* Refactor internal `ansible.InventoryTree` data structure.\n * Adding unit testing.\n * Simplifying internal building and searching algorithms.\n\n## [4.0.2]\n\n* `parse ansible json` CLI endpoint can now parse Ansible *loop* results (recursively).\n\n## [4.0.1]\n\n* Fix Python 3.6 support.\n\n## [4.0.0]\n\n> Yanked from PyPI due to continued Python 3.6 incompatibility.\n\n* Added support for Python 3.6\n* Adding release notes and improve `docs/`. \n* **Backwards incompatible change:** Removed buggy '--tail' argument and code from `post teams card` CLI endpoint.\n * Replaced '--tail' with '--trim'\n * 'trim' cuts off the end of the message instead of the beginning.\n\n## [3.0.2]\n\n* Fixed Source Distribution, to include all `docs/` and other required dependencies.\n* Rewrite of the CLI framework.\n* Rewrite of 'Parsing Ansible JSON' modules/packages, to capture more error messages successfully. \n* Added `--crucial-task` and `--crucial-task-type` filter parameters to `parse ansible json`.\n* Addition of `docs/` directory (driven via mkdocs).\n\n## [3.0.1]\n\n> Yanked from PyPI due to Broken Source Distribution.\n\n## [3.0.0]\n\n> Yanked from PyPI due to Broken Source Distribution.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "CLI toolset that supports CICD processes.",
"version": "4.0.11",
"project_urls": {
"Homepage": "https://git.uoregon.edu/projects/ISN/repos/buildtools/browse"
},
"split_keywords": [
"jenkins",
" nts",
" uo",
" cli",
" integrations",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a8bc286a12f16a6453d9d037e971931d8fa277922c982598f77e01a0ca262d3",
"md5": "9e1926a1e5fa0a06e4895b9e66f72d5e",
"sha256": "dcf5ad14fc9e1e57ba7c72d5933b1fcda8c45446294abee8c6ccf946b6936987"
},
"downloads": -1,
"filename": "ntsbuildtools-4.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e1926a1e5fa0a06e4895b9e66f72d5e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 41499,
"upload_time": "2024-04-11T21:42:18",
"upload_time_iso_8601": "2024-04-11T21:42:18.551730Z",
"url": "https://files.pythonhosted.org/packages/5a/8b/c286a12f16a6453d9d037e971931d8fa277922c982598f77e01a0ca262d3/ntsbuildtools-4.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-11 21:42:18",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ntsbuildtools"
}
JSON