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

After you install the Ansible code bot, 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

7.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 that displays all your repositories that have the Ansible code bot installed along with their scan status. If you did not set up a scan schedule earlier, the dashboard displays the repositories without any associated scan history. You can scan your Git repository by starting a manual scan, or configure a schedule to scan your repository at regular intervals. You can also add a repository for scanning or remove an existing repository from being scanned. For more information, see Managing repository scans.

7.1.1. Uninstalling the Ansible code bot

If you no longer want to use the Ansible code bot, you can uninstall it from GitHub. Once 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.

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

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

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

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

7.2.2. Configuring the Ansible code bot to scan your repository at regular intervals

You can schedule the Ansible code bot to scan your repositories at daily, weekly, or monthly intervals. To specify a scan schedule for your repository, create a configuration file ansible-code-bot.yml within your repository and specify your scan schedule in the .yml 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. By default, this is on Monday.
  • 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 interval parameter. You can specify the interval parameter as daily, weekly, or monthly. For example:

    schedule:
      interval: "<daily | weekly | monthly>"
  4. Commit your changes.

The Ansible code bot starts scanning your repository per the schedule you configured at 9 AM UTC time.

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

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

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