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 view bot activity and download archives and product builds. (Products contain only the app, and archives contain the Xcode project.)

To specify who can view and use the bots website

  1. In the Services list in the Server app sidebar, select Xcode.

  2. Click the Settings tab.

    ../art/SettingsTab_2x.png../art/SettingsTab_2x.png

     

  3. Click the Edit button for Permissions.

  4. In the dialog that appears, specify who can create and view bots and download their archives and products.

    ../art/BotPermissions_2x.png
    • If you choose “all users” from the pop-up menu, any visitor to the site can view bots and download items.

    • If you choose “logged in users” or “only some users,” an unauthenticated user sees a bots homepage that has no data. A Log In button in the top-left corner of the webpage allows the user to log in with a valid user name and password. (See Set Up Xcode Server for Team Members for information about creating user accounts on the server.)

    • If you choose “only some users,” you are presented with a table of users and groups. Add and remove users and groups to suit your needs.

  5. To allow or restrict view-only access to the website, use the “Also allow view-only access for” and “Allow connections from” pop-up menus.

    Users with view-only access can view the website, but they can’t create bots, manage bots, or initiate integrations in Xcode. 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, navigate to the address hostname/xcode/ in a web browser, where hostname is the Internet domain name for the server (such as server.mycompany.com) or its local hostname (such as server.local).

Depending on the viewing permissions configured in Xcode Server, you may be prompted to log in with their local or Open Directory account credentials.

The bots homepage displays a summarized list of most recent integrations for the bots running on the server.

../art/bots_website_summary_2x.png

The bots website can also be accessed from the OS X Server app on your server.

To access the bots website from the OS X Server app

  1. In the Services list in OS X Server, click Xcode.

  2. Click the Settings tab.

  3. Beneath the Devices table, click the “View bots” button.

    A web browser opens to the bots website.

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

To access the bots website from the report navigator

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

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

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

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

    A web browser opens to the bots website.

To log out of the bots website

Monitor Bots from the Bots Website

You can view the most recent integration summary for a bot or integration by tapping or clicking a bot or integration name on the bots homepage.

To filter the list of bot integrations

  1. Click the filter button in the center of the header of the bots homepage.

  2. In the filter pop-up menu, click the desired criteria to filter the list.

    • Latest displays the most recent complete integrations for each bot.

    • Failed displays the most recent failed integrations for each bot.

    • Succeeded displays the most recent successful integrations for each bot.

    • Flagged displays the most recent flagged integrations for each bot.

    After you make a selection, the title of the bots homepage displays the active filter criteria.

../art/bots_website_filtering_2x.png

To view integration results for a bot

Click the name of any bot or integration in the list on the bots homepage.

A summary of the the most recent integration performed by the bot, along with commits, is displayed.

../art/bots_website_integration_detail_2x.png

You can click the Flag button to flag a specific integration to identify it, for example, as a release candidate. What the flag means is up to you and your organization.

Open Bot in Xcode from the Bots Website

The bots website provides a mechanism for quickly opening bots in Xcode on your development Mac.

To open a bot in Xcode

  1. While viewing the bots website on your development Mac, click the name of any bot or integration in the list on the bots homepage.

    Your browser window displays a summary of the most recent integration performed by the bot.

  2. Click the “Open in Xcode” link.

    Xcode opens the bot.

Download Integration Assets from the Bots Website

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

To download an integration’s logs and assets in OS X

  1. Click the name of any bot or integration in the list on the bots homepage.

    Your browser window displays a summary of the most recent integration performed by the bot.

  2. Click the Download link to download the logs and assets for the integration.

To download an integration’s archive in OS X

  1. Click the name of any bot or integration in the list on the bots homepage.

    Your browser window displays a summary of the most recent integration performed by the bot.

  2. Click the Archive link, if available, to download an archive (the Xcode project) of the product.

If an integration does not contain an Archive link, an archive does not exist for the integration.

To download an integration’s product in OS X

  1. Click the name of any bot or integration in the list on the bots homepage.

    Your browser window displays a summary of the most recent integration performed by the bot.

  2. Click the Product link, if available, to download the product (the app) for the integration.

If an integration does not contain a Product link, a product does not exist for the integration.

Install iOS Products from the Bots Website

For iOS products, the bots website allows a profile necessary for Over The Air product installation to be installed for an integration, as well as a product (the app) itself. If a bot is an iOS project and the integration contains a product, a blue or green Install button appears on the integration summary screen. A blue Install button indicates that an Xcode Server Over The Air installation profile must be installed, and a green Install button indicates that the product can be installed.

To install an integration’s Over the Air installation profile in iOS

  1. Tap the name of any bot or integration in the list on the bots homepage.

    Your browser window displays a summary of the most recent integration performed by the bot.

  2. Tap the blue Install link to install the app for the integration.

../art/bots_website_integration_detail_ios_2x.png../art/bots_website_integration_detail_ios_2x.png

After you have installed the profile, the Install link color changes from blue to green, indicating that the product is now ready for installation.

To install an integration’s product (app) in iOS

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. A list of bots and the results of their most recent completed integration are displayed on the left. For the actively cycling bot, the number of errors, warnings, commits, and tests is displayed. Values preceded by a plus (+) or minus (-) sign indicate an increase or decrease from the prior integration.

For a bot’s integration, committer initials are displayed and enclosed within a white circle. This circle indicates the total code contribution for the committer among all commits for the current integration. A colored circle indicates the committer’s code contribution that introduced an issue, if applicable. Red represents errors, yellow represents warnings, and blue represents static analysis issues.

../art/big_screen_2x.png