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).

Note

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.

Important

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

  1. Log in to GitHub by using the account associated with your organization.
  2. Go to the Ansible code bot GitHub app.
  3. 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.
  4. 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.
  5. 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
  6. When prompted, log in to your Red Hat Single Sign-On account as an organization administrator.
  7. Log in to the Ansible code bot dashboard:

    1. On the Authorize Ansible code bot page, verify your account and repository permissions.
    2. 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

  1. 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.

    Note

    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.

    The following illustration is an example of an initial PR being created:

    Ansible code bot settings
  2. Optional: If required, you can manually scan your repositories or change the scan schedule to a daily or monthly cadence.
  3. Modify scanned repositories by adding repositories or removing existing repositories from being scanned.

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

  1. Log in to GitHub by using the account associated with your organization.
  2. In GitHub, click your profile photo > Settings.
  3. Under Integrations, click Applications > Installed GitHub Apps.
  4. Click Configure beside the Ansible code bot app.
  5. 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

  1. Log in to the Ansible code bot dashboard.

    The Repositories list displays a list of repositories that you selected for scanning.

    Note

    If 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.

  2. To start a manual scan of your repository, click the Ellipsis icon ( Ellipsis icon ) beside the repository that you want to scan and select Scan now.
  3. Click Refresh to view the status of the scan job.
  4. To view more details about your repository scans, click the Ellipsis icon ( 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.

  5. To view your repository on GitHub, click the Ellipsis icon ( Ellipsis icon ) beside the repository and select View repository.

8.2.1.2. Manually scanning the repository from GitHub

Procedure

  1. In GitHub, go to the main page of the repository that you want to scan.
  2. To modify the repository settings, click the Settings icon beside the About area.
  3. 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:

    Ansible code bot settings
  4. 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.

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.

Note

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

  1. In GitHub, navigate to the repository that you want to scan.
  2. Create a .yml configuration file named ansible-code-bot.yml in your repository .github folder.
    For example, .github/ansible-code-bot.yml.
  3. In the configuration file, specify the scan schedule in the interval parameter. You can specify the interval parameter as daily, weekly, or monthly. For example:

    schedule:
      interval: daily
  4. 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

  1. 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.

  2. To view the history of your repository’s scans, click the Ellipsis icon ( 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.

  3. To view your repository on GitHub, click the Ellipsis icon ( 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

  1. Log in to the Ansible code bot dashboard.
  2. Click Manage Code Bot on GitHub.
  3. In GitHub, click your profile photo > Settings.
  4. Under Integrations, click Applications.
  5. 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.
  6. 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.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.