Manage and Monitor Bots from a Web Browser

The bots website hosted on your server provides summaries of its bots’ activities along with details about their integrations. From the bots website, you and your team can edit, delete, and create bots; initiate any of their integrations; and download archives and product builds. (Products contain just the app, and archives contain the Xcode project.)

To specify who can view and use the bots website

  1. In the Server app sidebar, select the Xcode service.

  2. Click Settings.

    ../art/SettingsTab_2x.png
  3. Click the Edit button for Permissions.

  4. Use the upper pop-up menu to specify who can create and manage bots as well as download their archives and products.

    ../art/BotPermissions_2x.png

    If you choose “anyone” from the upper pop-up menu, any visitor to the site can view bots, create, edit and delete bots, and download items.

    If you choose “logged in users” or “only some users” from the upper pop-up menu, an unauthenticated user sees a Bots homepage devoid of data. The lock icon (../art/LogOutLogInIcon_2x.png) in the top-right corner of the webpage allows the user to log in with a valid user name and password. (See “Set Up the Xcode Service for Team Members” for information about creating user accounts on the server.)

    If you choose “only some users” from the upper pop-up menu, you are presented with a table of users and groups. Add and remove users and groups to suit your needs.

  5. Use the checkbox and the lower pop-up menu to allow or restrict view-only access to the website.

    Users with view-only access can view the website, but they can’t create bots, manage bots, or initiate integrations. People who particularly benefit from having view-only access to bot activity are software testers, project managers, and seed coordinators.

View the Bots Website

To view the bots website, use the address hostname/xcode/bots, where hostname is the Internet domain name for the server (such as server.mycompany.com) or its local hostname (such as server.local).

The Bots homepage displays the status of all of the bots on the server. The page shows a summary of the last integration, the amount of time before the next integration begins, links to the downloads from the last integration, and a list of the bots running on the server.

../art/bots_page_2x.png

From this page you can further select information to view by clicking:

You can perform tasks on the page by clicking:

You can also access the bots website from the log navigator on your development Mac.

To access the bots website from the log navigator

  1. In Xcode on your development Mac, choose View > Navigators > Show Log Navigator.

  2. Click By Group at the top of the log navigator.

    All integrations for a bot are grouped under the bot name.

  3. Control-click a bot in the log navigator, and choose “View Bot in Browser” from the shortcut menu.

    A web browser opens to the status page for the selected bot.

  4. Click Bots in the navigation bar at the top of the webpage to see the bots homepage.

Manage and Monitor Bots from the Bots Homepage

You can view summaries of a bot’s integrations by selecting the bot name on the bots homepage.

To view a summary of integration results for a bot in a web browser

  1. Display the bots website (hostname/xcode/bots).

    Hostname is the Internet domain name for the server (such as server.mycompany.com) or its local hostname (such as server.local).

  2. Click the name of any bot in the table.

    The browser window displays a summary of the integrations performed by the bot along with any build errors and warnings, static analyzer problems, and unit test failures. The results of the most recent integration appear near the top of the window.

../art/bot_page-summary_2x.png

The Summary pane displays these elements:

From this page you can click:

You can also access the webpages for a bot from the log navigator on your development Mac.

To access the webpages for a bot from the log navigator

  1. In Xcode on your development Mac, choose View > Navigators > Show Log Navigator.

  2. Click By Group at the top of the log navigator.

    All integrations for a bot are grouped under the bot name.

  3. Control-click a bot in the log navigator, and choose “View Bot in Browser” from the shortcut menu.

    A web browser opens to the summary page for the selected bot.

Review Integration Details in a Web Browser

You can view details about an integration by selecting it from a bot webpage.

To view details about an integration in a web browser

  1. Display the bots website (hostname/xcode/bots).

  2. Click the name of any bot in the table.

    Your browser window displays a summary of the integrations performed by the bot. The results of the most recent integration appear near the top of the window.

  3. Select any integration listed in the bot page sidebar.

    When you select an integration, a Summary pane shows the status of the integration, any integration issues, and links to download the integration’s archive and build. If there are errors, warnings, static analysis issues, or test failures, use the Tests and Logs panes to find out more about them.

    ../art/integration_page-summary_2x.png
  4. Click Tests to view the list of the integration’s tests and their pass or fail status.

    If you have multiple test devices, you can compare their results across columns.

    ../art/integration_page-tests_2x.png
  5. Click Commits to view the new commits that integration includes.

  6. Click Logs to view the logs of the actions that are part of the integration. The logs are helpful for troubleshooting integration issues.

    You can also download the logs to your development Mac. Click ../art/BotActionIcon_2x.png in the top-right corner of the page, and choose Download Logs. A list of checkboxes appears for the various logs available for download. Select one or more logs, and click Download.

  7. Click Archives to view a list of the products and archives that the bot has generated.

    ../art/integration_page-archives_2x.png
  8. Click the Product or Archive link to download the item, or click the Trash icon to delete the integration’s archives.

In the top-right corner of this page you can click:

You can also access the integration details webpage from the log navigator on your development Mac.

To access the integration webpages from the log navigator

  1. In Xcode on your development Mac, choose View > Navigators > Show Log Navigator.

  2. Click By Group at the top of the log navigator.

    All integrations for a bot are grouped under the bot name.

  3. If necessary, click the disclosure triangle for a bot to display a list of all of its integrations.

  4. Control-click an integration in the log navigator, and choose “View Integration in Browser” from the shortcut menu.

    A web browser opens to the status page for the selected integration.

Download Products and Archives from a Web Browser

The bots website facilitates the distribution of product builds and archives to testers and other team members. Products contain just the app, and archives contain the Xcode project.

To download a bot’s recent archives from a web browser

  1. Display the bots website (hostname/xcode/bots).

  2. Click the name of any bot in the list.

    Your browser window displays a summary of the integrations performed by the bot.

  3. Click Archives to display the bot’s Archives pane.

  4. Click a download link for any integration.

You can flag the archives of a specific integration to identify them, for example, as release candidates. What the flag means is up to you and your organization.

../art/bot_page-archives_2x.png

Watch Your Bots on Big Screen

To keep apprised of your bots’ status on a large or dedicated display, view them on big screen.

To view bots on big screen

Do one of the following:

The webpage can be made full screen, and it can be displayed using AirPlay mirroring. Big screen cycles among all of the server’s bots, displaying the most pertinent status information for each bot.

../art/bots_scoreboard_2x.png