Chapter 8. Installing and configuring the Ansible code bot
The Ansible code bot scans existing content collections, roles, and playbooks hosted in GitHub repositories, and proactively creates pull requests whenever best practices or quality improvement recommendations are available.
Ansible code bot scans your code repositories to recommend code quality improvements. It promotes Ansible best practices while avoiding common errors that can lead to bugs or make code harder to maintain. The bot automatically submits pull requests to the repository, which proactively alerts the repository owner to a recommended change to their content. You can configure Ansible code bot to scan your existing Git repositories (both public and private).
Your organization must have an active subscription to Red Hat Ansible Automation Platform to use the Ansible code bot. However, IBM watsonx Code Assistant is not required to use the Ansible code bot.
After the Ansible code bot is installed, it automatically scans the selected repositories that are in Jinja format. Once the scanning is complete, the code bot generates an initial PR for each repository; the initial PR also contains the scan schedule configured to run weekly. You must review the initial PR for the suggested changes and merge the PR. Once the initial PR is merged, the scan schedule is triggered, and the subsequent repository scans are performed weekly. If required, you can change the scan schedule to a daily or monthly cadence.
You can access the Ansible code bot dashboard that displays all your repositories that have the bot installed along with their scan status. From the dashboard, you can start a manual scan, view the scan history, and view the repository. From GitHub, you can configure a schedule to scan your repository at regular intervals, and add or remove a repository from being scanned. For more information, see Managing repository scans.
Ansible code bot is supported on the following GitHub versions:
- GitHub.com
GitHub Enterprise Cloud
Ansible code bot is not supported on GitHub Enterprise Server. For more information, see GitHub’s plans in the GitHub documentation.
The following examples are code recommendations that the Ansible code bot can suggest:
- Available alternatives for deprecated legacy syntax or implementation patterns
Module version changes and updates, such as:
- Adding any new required parameters
- Flagging deprecated parameters
- Removing unused parameters
- Applying YAML best practices
- Adding comment blocks
- Fixing casing issues in name fields
8.1. Installing the Ansible code bot
Install the Ansible code bot to get code recommendations for your repositories, and then log in to the Ansible code bot dashboard to monitor and manage your repository scans.
Procedure
- Log in to GitHub by using the account associated with your organization.
- Go to the Ansible code bot GitHub app.
Select the Ansible repositories that you want the app to access:
- All repositories: Provides access to read the metadata of all repositories.
- Only select repositories: Provides access to read the metadata of only the repositories that you select.
- Optional: If you selected Only select repositories in the previous step, select the repositories that you want the Ansible code bot to access from the Select repositories list.
Click Install & Authorize. A message is displayed that specifies the following permissions are granted automatically to the bot during installation:
- Read access to metadata
- Read and write access to code and pull requests
- When prompted, log in to your Red Hat Single Sign-On account as an organization administrator.
Log in to the Ansible code bot dashboard:
- On the Authorize Ansible code bot page, verify your account and repository permissions.
Click Authorize Ansible.
From the Authorize Ansible code bot page, the following actions occur:
- Ansible code bot verifies that you are a part of an organization that has an active subscription to Red Hat Ansible Automation Platform.
- GitHub requests read permissions to access the repositories associated with your account.
On successful authorization, you are logged in to Ansible code bot dashboard. The dashboard displays all your repositories that have the Ansible code bot installed along with their scan status.
8.1.1. Post-installation tasks
After the Ansible code bot is installed, it automatically scans the selected repositories that are in Jinja format. When the scanning is complete, the code bot generates an initial PR for each repository; the initial PR also contains the scan schedule configured to run weekly.
Procedure
Review the initial PR for the suggested changes, and merge the PR.
After you merge the initial PR, the configured scan schedule is triggered, and the subsequent repository scans are performed weekly.
NoteIf you do not merge the initial PR, the weekly scan schedule is not triggered and the Ansible code bot dashboard displays the repositories without any associated scan history.
The following illustration is an example of an initial PR being created:
- Optional: If required, you can manually scan your repositories or change the scan schedule to a daily or monthly cadence.
- Modify scanned repositories by adding repositories or removing existing repositories from being scanned.
Additional resources
8.1.2. Uninstalling the Ansible code bot
If you no longer want to use the Ansible code bot, you can uninstall it from GitHub. After the code bot is uninstalled, you can still access the Ansible code bot dashboard but you cannot see the repositories on the dashboard or scan your repositories.
Procedure
- Log in to GitHub by using the account associated with your organization.
- In GitHub, click your profile photo > Settings.
- Under Integrations, click Applications > Installed GitHub Apps.
- Click Configure beside the Ansible code bot app.
Under the Danger zone area, click Uninstall.
The Ansible code bot app is uninstalled from your GitHub account.
8.2. Managing repository scans
The Ansible code bot dashboard displays a list of your repositories where the code bot is installed, and indicates if the scan schedule is not set, or is set to manual or scheduled scan.
You can scan your Git repository by starting a manual scan, or configure a schedule to scan your repository at regular intervals. After the scan is completed, you can view the scan history (start time, status, type of scan, link to the pull request if it was created, and the log message if the scan failed). You can also add new repositories for scanning or remove existing repositories from being scanned.
8.2.1. Manually scanning your Git repositories
You can manually scan your Git repositories if you did not set up a scanning schedule for your Ansible code bot or if you do not want to wait for the next scheduled scan. If you manually scan your repository, and no pull request was created, it is likely so because a duplicate pull request already exists. You can scan your repository from both the Ansible code bot dashboard and GitHub.
8.2.1.1. Manually scanning the repository from the Ansible code bot dashboard
Procedure
Log in to the Ansible code bot dashboard.
The Repositories list displays a list of repositories that you selected for scanning.
NoteIf you do not see your repository in the Repositories list, you can add it for scanning. For more information, see Adding or removing repositories from the Ansible code bot.
- To start a manual scan of your repository, click the Ellipsis icon ( ) beside the repository that you want to scan and select Scan now.
- Click Refresh to view the status of the scan job.
To view more details about your repository scans, click the Ellipsis icon ( ) beside the repository and select View scan history.
The repository’s scan history is displayed along with the scan start time, scan status, type of scan (scheduled or manual), link to the pull request if it was created, and the log message if the scan failed.
- To view your repository on GitHub, click the Ellipsis icon ( ) beside the repository and select View repository.
8.2.1.2. Manually scanning the repository from GitHub
Procedure
- In GitHub, go to the main page of the repository that you want to scan.
- To modify the repository settings, click the Settings icon beside the About area.
In the Topics field, enter the keyword topic ansible-code-bot-scan to the repository.
The following illustration shows the keyword topic for starting a manual scan:
Click Save changes.
Based on the repository webhook event, Ansible code bot starts a manual scan of your repository. If the avoid duplicate pull requests condition is not met, then the manual scan results in a new pull request with all the necessary Ansible code bot recommendations.
Additional resources
8.2.2. Configuring the Ansible code bot to scan your repository at regular intervals
After installing the Ansible code bot, it automatically scans the selected repositories that are in Jinja format. Once the scanning is complete, the code bot generates an initial PR for each repository; the initial PR also contains the scan schedule configured to run weekly. You must review the initial PR for the suggested changes and merge the PR. Once the initial PR is merged, the scan schedule is triggered, and the subsequent repository scans are performed weekly. If required, you can change the scan schedule to a daily or monthly cadence.
If you do not merge the initial PR, the weekly scan schedule is not triggered and the Ansible code bot dashboard displays the repositories without any associated scan history. In such a scenario, you must manually create a configuration file ansible-code-bot.yml
and specify your scan schedule within the file.
You can specify one of following interval cadence to scan your Git repositories:
- Daily: Runs every day from Monday to Sunday.
- Weekly: Runs once a week on Monday. Per the initial configuration PR, the Ansible code bot is set to scan your repositories weekly until you change the schedule to daily or monthly.
- Monthly: Runs on the first day of the month, once each month.
For each interval cadence, Ansible code bot starts scanning your Git repositories at 9 AM UTC.
Procedure
- In GitHub, navigate to the repository that you want to scan.
-
Create a
.yml
configuration file namedansible-code-bot.yml
in your repository.github
folder.
For example,.github/ansible-code-bot.yml
. In the configuration file, specify the scan schedule in the
interval
parameter. You can specify theinterval
parameter asdaily
,weekly
, ormonthly
. For example:schedule: interval: daily
- Commit your changes.
The Ansible code bot starts scanning your repository per the schedule you configured at 9 AM UTC time.
8.2.3. Viewing your repository’s scan history
Use the Ansible code bot dashboard to see a list of your repositories and their scan history.
Procedure
Log in to the Ansible code bot dashboard.
The Ansible code bot dashboard displays a list of your repositories where the code bot is installed, and indicates if the scan schedule is not set, or is set to manual or scheduled scan.
To view the history of your repository’s scans, click the Ellipsis icon ( ) beside the repository and select View scan history.
The repository’s scan history is displayed along with the scan start time, scan status, type of scan (scheduled or manual), link to the pull request if it was created, and the log message if the scan failed.
- To view your repository on GitHub, click the Ellipsis icon ( ) beside the repository and select View repository.
8.2.4. Adding or removing repositories from the Ansible code bot
You can enable the Ansible code bot for a repository, or remove repositories that you no longer want to manage.
Procedure
- Log in to the Ansible code bot dashboard.
- Click Manage Code Bot on GitHub.
- In GitHub, click your profile photo > Settings.
- Under Integrations, click Applications.
From the Repository access area, perform one of the following tasks:
- Add a new repository: From the Select repositories list, select the repository that you want to add. The newly-added repository is displayed on the Ansible code bot dashboard.
- Remove an existing repository: From the Select repositories list, click the Cross icon beside the repository that you want to delete. The deleted repository details are no longer visible on the Ansible code bot dashboard.
- Click Save.
8.3. How Ansible code bot handles duplicate pull requests
- If Ansible code bot has created a pull request on the latest commit default branch, it does not scan the repository. The bot skips scanning the repository because the pull request was committed on the latest default branch, and no new commit was made after that pull request.
If there is an existing pull request that is not on the latest commit default branch, the Ansible code bot does a pull request difference to compare the changes in both branches. The following scenarios are possible:
- There is no difference in the existing and new scan results: Ansible code bot does not push the scan results as a new pull request.
- There are differences found in the existing and the new scan results: the Ansible code bot creates a new pull request. The newly-created pull request does not close the existing pull request, against which the pull request difference was noted. This behavior makes it easier for the repository administrator to review only the latest pull request created by the Ansible code bot, and the administrator can avoid reviewing the older pull requests created by the bot. If required, the administrator can close the older pull requests.