Making progress in resolving issues for modules depends upon your interaction! Please be sure to respond to requests or additional information as needed.
If at any time you think this bot is misbehaving (not for test failures), please leave a comment containing the keyword bot_broken and an Ansible staff member will intervene.
- Overview
- For issue submitters
- For pull request submitters
- For community maintainers
- For anyone else
- Commands
- Labels
The Ansibull Triage Bot serves many functions:
- Responds quickly to issue and pull request submitters to thank them;
- Identifies the maintainers responsible for reviewing pull requests for any files affected;
- Tracks the current status of pull requests;
- Pings responsible parties to remind them of any actions that they may be responsible for;
- Provides maintainers with the ability to move pull requests through our workflow;
- Identifies issues and pull requests abandoned by their authors so that we can close them;
- Identifies modules abandoned by their maintainers so that we can find new maintainers;
- Automatically labels issues and pull requests based on keywords or affected files.
Please note that if you have a question about how to use this feature or module with Ansible, that's probably something you should ask on the ansible-project mailing list, rather than submitting a bug report. For more details, please see I’ve Got A Question.
If the feature/module maintainer or ansibullbot needs further information, please respond to the request, so that you can help the devs to help you!
The bot requires a minimal subset of information from the issue template:
- issue type
- component name
- ansible version
- summary
If any of those items are missing or empty, ansibullbot will keep the issue in a needs_info state until the data is provided in the issue's description. The bot is expecting an issue description styled after the default issue template, so please use that whenever possible.
Expect the bot to do a few things:
-
Add common labels such as
needs_triage,bug_report,feature_idea, etc.These labels are determined by templated data in the description. Please fill out the templates as accurately as possible so that the appropriate labels are used.
-
Notify and assign the maintainer(s) of the relevant file(s) or module(s).
Notifications will happen via a comment with the
@NAMEsyntax. If you know of other interested parties, feel free to ping them in a comment or in your issue description.
If you are not sure who the issue is waiting on, please use the bot_status command.
Expect the bot to do a few things:
-
All of the items described in the for issue submitters section.
-
Add labels indicating the status of the pull request.
Please prefix your pull request's title with WIP if you are not yet finished making changes. This will tell the bot to ignore the needs_rebase and shipit workflows until you remove it from the title.
If you are finished committing to your pull request or have made changes due to a request, please use the ready_for_review command.
If you are not sure who the pull request is waiting on, please use the bot_status command.
ℹ️ Approve pull request status is ignored, shipit command is used by maintainer to approve a pull request. The bot automatically adds a shipit label to the pull request when the required number of shipit commands has been reached.
The bot will label a pull request with shipit when at least two [shipit] commands are issued, the following rules describe how shipit commands are count:
shipitissued by a module maintainer or a maintainer of a module in the same namespace are always taken in account- when the submitter is a module maintainer or a maintainer of a module in the same namespace, their
shipitis automatically counted shipitissued by anyone else is taken in account when both conditions are met:
Once the pull request labeled with shipit, the module will be merged once a member of the Ansible organization has reviewed it and decided to include it.
ℹ️ If you are a maintainer of a module in the same namespace, only one shipit is required.
Existing community modules are developed, maintained and supported by the community. If you are a module maintainer, a maintainer of a module in the same namespace, use the shipit command to approve the pull request. The bot will wait for the pull request being labeled with shipit, then automerge.
ℹ️ If you are maintainer of the module or maintainer of a module in the same namespace, only one shipit is required.
The collection maintainers approve these pull requests and it may take some time for them to get to your request.
ℹ️ Approve pull request status is ignored, shipit command must be used in order to approve a pull request.
Thanks in advance for taking a look at issues and pull requests and for your ongoing maintenance. If you are unable to troubleshoot or review this issue/pull request with the information provided, please ping the submitter of the issue in a comment to let them know.
If you wish to stop receiving notifications from Ansibullbot to issues and pull requests you need to add your github name into the ignored key under plugin you are no longer insterested in in the BOTMETA.yml file and send a pull request against the ansible/ansible repository. See an example below:
...
$modules/cloud/amazon/:
ignored: erydo seiffert simplesteph nadirollo tedder joshsouza defionscode
maintainers: $team_aws
...If the plugin was migrated to a collection you also need to add an ignore entry into BOTMETA.yml in the collection repository as well.
Reactions help us determine how many people are interested in a pull request or have run across a similar bug. Please leave a +1 reaction (:+1:) if that applies to you. Any additional details you can provide, such as your usecase, environment, steps to reproduce, or workarounds you have found, can help out with resolving issues or getting pull requests merged.
To streamline the maintenance process, we've added some commands to Ansibullbot that you can use to help direct the work flow. Using the automation is simply a matter of adding one of the following commands in your comments:
| Command | Scope | Allowed | Description |
|---|---|---|---|
| bot_broken | issues pull requests | anyone | Use this command if you think the bot is misbehaving (not for test failures), and an Ansible staff member will investigate. |
| !bot_broken | issues pull requests | anyone | Clear bot_broken command. |
| bot_skip | issues pull requests | staff | Ansible staff members use this to have the bot skip triaging an issue. |
| !bot_skip | issues pull requests | staff | Clear bot_skip command. |
| bot_status | pull requests | submitters maintainers | Use this command if you would like the bot to comment with some helpful metadata about the issue. |
| needs_info | issues pull requests | maintainers past committers | Use this command if you need more information from the submitter. We will notify the submitter and apply the needs_info label. |
| !needs_info | issues pull requests | maintainers past committers | If you do not need any more information and just need time to work the issue, leave a comment that contains the command !needs_info and the needs_info label will be replaced with waiting_on_maintainer. |
| needs_revision | pull requests | maintainers | Use this command if you would like the submitter to make changes. |
| !needs_revision | pull requests | maintainers | If you want to clear the needs_revision label, use this command. |
| needs_rebase | pull requests | maintainers | Use this command if the submitters branch is out of date. The bot should automatically apply this label, so you may never need to use it. |
| !needs_rebase | pull requests | maintainers | Clear the needs_rebase label. |
| notabug | issues | maintainers | If you believe this is not a bug, please leave a comment stating notabug, along with any additional information as to why it is not, and we will close this issue. |
| bug_resolved | issues | maintainers | If you believe this issue is resolved, please leave a comment stating bug_resolved, and we will close this issue. |
| resolved_by_pr | issues | maintainers | If you believe this issue has been resolved by a pull request, please leave a comment stating resolved_by_pr followed by the pull request number. |
| wontfix | issues | maintainers | If this is a bug that you can't or won't fix, please leave a comment including the word wontfix, along with an explanation for why it won't be fixed. |
| needs_contributor | issues | maintainers | If this bug or feature request is something that you want implemented but do not have the time or expertise to do, comment with needs_contributor, and the issue will be put into a waiting_on_contributor state. |
| duplicate_of | issues | maintainers | If this bug or feature request is a duplicate of another issue, comment with duplicate_of followed by the issue number that it duplicates, and the issue will be closed. |
| close_me | issues | maintainers | If the issue can be closed for a reason you will specify in the comment, use this command. |
| ready_for_review | pull requests | submitters | If you are finished making commits to your pull request or have made changes due to a request, please use this command to trigger a review from the maintainer(s). |
| shipit | pull requests | maintainers | If you approve the code in this pull request, use this command to have it merged. Note that Github Approve pull request status is ignored. Nonetheless shipit in review summary of commented or approved review is taken in account. In place of shipit, +1 and LGTM can be used too. Note that these commands must not be surrounded by any character, spaces excepted. |
| +label | issues pull requests | staff maintainers | Add a supported label. See When to use label commands. |
| -label | issues pull requests | staff maintainers | Remove a supported label. See When to use label commands. |
| rebuild_merge | pull requests | staff | Allow collection maintainers to trigger CI, then the pull request is automatically merged if CI results are successful. |
| /rebuild | pull requests | anyone | Allows anyone to re-trigger CI. |
| /rebuild_failed | pull requests | anyone | Allows anyone to re-trigger CI only on failed jobs [this is usually much faster than /rebuild]. |
| !component | issues | anyone | Set, append or remove a file from the matched components. To set, use !component =lib/ansible/foo/bar. To add, use !component +lib/ansible/foo/bar. To remove, use !component -lib/ansible/foo/bar. |
| !waffling | all | maintainers | Disable waffling detection on a label. To use !waffling <labelname> on a separate line in a comment. |
The bot adds many labels on issues and pull requests.
| Label | Scope | Prevent automerge | Description |
|---|---|---|---|
| automerge | pull requests | no | Identify pull requests automatically merged by the bot. |
| backport | pull requests | yes | Added to pull requests which don't target devel branch. |
| bot_broken | pull requests | yes | Allow to identify pull requests for which bot_broken had been used. |
| bug | issues pull requests | no | Added to issues or pull requests reporting/fixing bugs. |
| c:name | issues pull requests | no | Categorize issues or pull requests by their relevant source code files. |
| ci_verified | pull requests | yes | Identify pull requests for which CI failed. A pull request must successfully pass CI in order to be merged. |
| committer_review | pull requests | no | In order to be merged, these pull requests must follow the certified review workflow. |
| community_review | pull requests | no | In order to be merged, these pull requests must follow the community review workflow. |
| core_review | pull requests | no | In order to be merged, these pull requests must follow the core review workflow (deprecated). |
| docs | issues pull requests | no | Identify issues or pull requests related to documentation. |
| docsite_pr | pull requests | no | Identify pull requests created through documentation's "Edit on GitHub" link |
| easyfix | issue or pull requests | no | Identify easy entrance point for people who are looking to start contributing. |
| feature | issues pull requests | no | Added to issues or pull requests requesting/adding new features. |
| filament | pull requests | no | Identify pull requests related to Ansible Lightbulb project. |
| merge_commit | pull requests | no | Added to pull requests containing at least one merge commit. Pull requests must not contain merge commit. |
| module | pull requests | no | Identify pull requests updating existing modules. |
| needs_ci | pull requests | no | Identify pull requests for which CI status is missing. When a pull request is closed and reopened or when new commits are updated, the CI is triggered again. |
| needs_collection_redirect | issue or pull requests | no | Collection Migration Docs |
| needs_info | issues | yes | Identify issues for which reviewer requested further information. |
| needs_maintainer | pull requests | no | Ansibullbot is unable to identify authors or maintainers of the related module. Check author field format in DOCUMENTATION block. |
| needs_rebase | pull requests | yes | Pull requests which are out of sync with ansible/ansible's devel branch. Please review the rebase guide for further information. |
| needs_revision | pull requests | yes | Used for pull request which fail continuous integration tests or if a maintainer has requested a review/revision of the code. This label can be cleared by fixing any failed tests or by commenting ready_for_review. |
| needs_template | issues pull requests | no | Label added when description is incomplete. See issue templates or pull request template. |
| needs_triage | issues pull requests | no | This label will be added if your issue is being labeled for the first time. We (ansible staff and maintainers) use this label to find issues that need a human first touch. We'll remove it once we've given the issue a quick look for any labeling problems or missing data. |
| needs_verified | issues | no | This label implies a maintainer needs to check if the issue can be reproduced in the latest version. |
| new_module | pull requests | yes | Identify pull requests adding new module. |
| owner_pr | pull requests | no | Identify pull requests made by module maintainers. |
| shipit | pull requests | no | Identify pull requests for which the required number of shipit has been reached. For community reviewed pull requests, if automerge workflow applies, then pull request should be automatically merged. For all other cases, merge should be performed by a collection maintainer. If your pull request gets no comment and becomes tagged with stale_review, search the collection contributing documentation for how to reach out to the collection maintainers to receive more comments. |
| stale_ci | pull requests | yes | Added when the last CI result is older than one week. When a pull request is closed and reopened, the CI is triggered again. In some case, the bot will automatically trigger the CI when a pull request is labeled with both shipit and stale_ci. |
| stale_review | pull requests | no | Added when submitter made some updates after a reviewer requested some changes, if the submitter updates are older than seven days and the reviewer didn't update their review. |
| test | pull requests | no | Identify pull requests related to tests. |
| waiting_on_contributor | issues pull requests | no | The feature or fix would be accepted, but there are no plans to actively work on it. |
| WIP | pull requests | yes | Identify pull requests which are not ready (from the submitter point of view) to be merged. |
Some labels are used to categorize issues and pull requests:
-
Pull requests related to test:
test
-
Namespace labels:
aciaviawsazurecloudcloudstackdigital_oceandockerf5gceinfobloxjbossmerakinetappnetworkingnxosopenstackovirtucsvmwarewindows
-
Module labels:
m:unarchivem:xml
The +label and -label commands are restricted to a subset of available labels and are not meant to replace the other bot commands:
affects_X.Y-- indicates that the issue is relevant to a particular ansible major.minor version.c:...-- these labels categorize issues or pull requests by their relevant source code files.easyfix-- indicates that the issue an easy entrance point for people who are looking to start contributing.m:...-- these labels categorize issues or pull requests by their module name.module-- classifies the issue as a module related issue.needs_triage-- a human being still needs to validate the issue is properly labeled and has all the information required.testand namespace labels
To use the commands, please type the command and label on one line each in a comment. Example:
-label needs_triage
+label cloud
+label gce