Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction
Introduction

Configure the GitHub-Checks plugin

5 minute readExtensibilityDeveloper productivity

To configure the GitHub-Checks plugin as a GitHub App, perform the following steps:

  1. Create a GitHub Checks webhook trigger in your CloudBees CD/RO pipeline.

    You are not required to create a webhook trigger for the GitHub-Checks plugin in your pipeline. However, the GitHub Checks webhook trigger was designed to work specifically with the GitHub Checks API, and returns runtime properties for GitHub-related Input Parameters needed by the plugin. This method makes automating the Create or Update Check Runs procedure within your pipelines much more practical.

    If you choose not to configure a webhook trigger for the GitHub-Checks plugin, you can also manually enter all Input Parameters or configure a combination of properties piped in from other plugins, such as EC-GitHub and EC-Git, along with manually entered parameters.

  2. Register the GitHub-Checks plugin as a GitHub App using the CloudBees CD/RO webhook trigger information.

  3. Generate a private key for your GitHub App in GitHub.

  4. Install your GitHub App in your repositories in GitHub.

  5. Create GitHub-Checks plugin configurations within CloudBees CD/RO using the GitHub App information.

  6. When configuring the plugin parameters in your pipeline, Provide the GitHub App Installation ID.

Create a GitHub Checks webhook trigger

Creating a webhook trigger specifically for the GitHub-Checks plugin:

  • Allows automated triggers for your CloudBees CD/RO pipeline based on GitHub events.

  • Generates specific GitHub Checks runtime properties for multiple required Input Parameters.

  • Prevents overburdening and creating unneeded dependencies on other plugins or webhooks.

To create pipeline webhooks, you must have permission to view service account details. If you don’t have sufficient permissions to create webhooks, you will receive an error message when trying to create one, and must contact your system administrator.

To create a webhook in your CloudBees CD/RO pipeline:

  1. Navigate to Release Orchestration  Pipelines.

  2. Open the pipeline you want to use the plugin with.

  3. Open the pipeline context menu, and select Triggers.

  4. Select Add to create a new trigger.

  5. Provide the webhook details:

    • For Plugin, select GitHub-Checks.

    • For Trigger Type, select Webhook.

    • Select Use secret token, and provide a webhook secret token.

      You must use this webhook secret token when registering the GitHub App.

    • For Repositories, Include branches, and Exclude branches, follow the UI help tips, and ensure your entries are formatted as described.

  6. Once you have provided the webhook details, select Next.

  7. The Select Service Account page appears. Select the service account for your webhook, and select Next.

  8. The Run Pipeline page appears. Select OK.

If your webhook was successully created, the Webhook Trigger Successfully Created page appears. This page contains the GitHub Webhook URL needed to configure your GitHub App.

You must have the webhook secret token and URL to register the GitHub-Checks plugin as a GitHub App.

If you receive an error, fix any recommendations, and navigate back to the Triggers menu. From there, select your trigger, and confirm the information is correct.

Register the GitHub-Checks plugin as a GitHub App

Registering the GitHub-Checks plugin as a GitHub App allows it to access your GitHub repositories when specified events happen with specific permissions.

If you plan to use a webhook trigger specifically for the GitHub-Checks plugin, you must create it prior to registering the plugin as GitHub App. You will need the webhook secret token and Webhook URL from that process to complete this one. For more information, refer to Create a GitHub Checks webhook trigger.

For general instructions on registering a GitHub App, refer to the Registering a GitHub App documentation on GitHub. While following those instructions, ensure the following:

If you did not configure a webhook trigger specifically for the GitHub-Checks plugin, in the GitHub App configuration page, under the Webhook section, deselect the Active checkbox. From the following items, only follow the instructions for Permissions and Subscribe to events.

  • For Webhook URL, provide the Webhook URL of the webhook trigger you created in CloudBees CD/RO.

  • For Webhook secret (optional), provide the webhook secret token you created in CloudBees CD/RO. When using this plugin, this is not optional.

  • For Permissions, select Repository permissions  Checks  Read and write, and select Repository permissions  Metadata  Read-only.

  • For Subscribe to events select Check suite and Check run.

    The Subscribe to events selection options are based on granted permissions. If Check suite or Check run are not available, ensure you granted the permissions as described in the previous step.

  • For Where can this GitHub App be installed?, select either Only on this account or Any account.

    This field determines the availability of the GitHub App as public or private, and may depend on organizational standards. For more information, refer to the Making a GitHub App public or private documentation on GitHub.

    After providing project-specific GitHub App details, select Create GitHub App. If any errors are returned, follow the GitHub instructions to correct them. Once the GitHub App is successfully registered, a page opens with its details. From this page, you need the App ID for the GitHub-Checks plugin configuration.

After you have created a GitHub App, you must generate a private key to use in the plugin configuration. For more information, refer to Generate a private key for your GitHub App.

Generate a private key for your GitHub App

You must generate a private key for the GitHub App. To do so:

  1. Navigate to Settings  Developer settings  GitHub Apps and select Edit next to your GitHub App. This opens the General settings page.

  2. Navigate to the Private keys section.

  3. Select Generate a private key.

This downloads your GitHub App private key in PEM format. Save your GitHub App private key to a secure location. It is required for the GitHub-Checks plugin configuration.

To configure the GitHub-Checks plugin, you must have the GitHub App ID and private key in PEM format.

After you have created a GitHub App and private key, you must install the GitHub App in your repositories. For more information, refer to Install your GitHub App in your repositories.

Install your GitHub App in your repositories

To use the GitHub-Checks plugin in a repository, you must install the corresponding GitHub App in the repositories it will be used. To do so:

  1. Navigate to Settings  Developer settings  GitHub Apps and select Edit next to your GitHub App. This opens the General settings page.

  2. Select Install App from the navigation menu.

  3. Select the account you want to use to install the GitHub App, and select Install. The repository installation page opens.

  4. Select the repositories where you want to install the GitHub App.

  5. Confirm the permissions for repositories where you are installing the GitHub App. These must be:

    • Checks: Read and write

    • Metadata: Read-only

  6. Once finished, select Install.

After installing the GitHub App associated with the GitHub-Checks plugin in your repositories, next integrate the GitHub App within your Create GitHub-Checks plugin configurations.

Provide the GitHub App Installation ID

When configuring the plugin parameters in a pipeline, you must provide the GitHub App Installation ID. To find the Installation ID:

  1. On GitHub, go to Settings  Applications.

  2. For your GitHub App, select Configure. This opens the GitHub App Configure page.

  3. Find and copy the Installation ID shown in the page URL. Examples:

    • https://github.com/organizations/<your-organization-name>/settings/installations/<Installation-ID>

    • https://github.com/settings/installations/<Installation-ID>

  4. Enter the Installation ID in the plugin parameters.

Create GitHub Checks plugin procedures
GitHub-Checks plugin use cases