Integrate with GitHub

You can integrate with a GitHub repository and run PulseUno chains to send results to GitHub.

GitHub integration overview

This integration publishes the results of PulseUno continuous integration (CI) chains to GitHub using the GitHub commit checks API.

You can collaborate on code changes in GitHub, build and test your changes in PulseUno, and send build results to your GitHub repository. PulseUno delivers chain results to GitHub as a check on a commit and annotates the commit with chain findings.

The following information is published to GitHub:

  • General build details such as the chain number, the user that ran the chain, the state and duration of the chain run, and the commit link.

  • Execution summary for each chain step.

  • The number of discovered findings.

  • The number of recorded artifacts.

  • A summary of passed and failed unit tests, including a list of the first 10 failed tests.

  • (Optional) Findings converted to code-level annotations.

GitHub integration guidelines:

  • You can integrate with repositories hosted on GitHub.com or GitHub Enterprise.

  • PulseUno uses GitHub Apps to authenticate with GitHub. You need to create a GitHub App and generate a private key for the app in GitHub.

  • You can publish to GitHub only from a mirror of your GitHub repository in PulseUno.

Back to top

GitHub integration steps

To set up the integration with GitHub, complete the following steps.

Step 1

In GitHub: Create a GitHub App for PulseUno and install it on one or more GitHub user or organization accounts containing the repositories to integrate with.

When creating a GitHub App, set the following options as specified:

  • Homepage URL. Enter the URL of your PulseUno instance, for example:

    http://pulseuno:8080/pulse

  • Webhook. Disable webhook events by clearing the Active option.

  • Permissions. Select Repository permissions > Checks and set the access level to Read and write.

    Mandatory repository permissions such as Metadata are set by GitHub.

For details about creating GitHub Apps, see the GitHub documentation.

Step 2

In GitHub: Generate a private key for the PulseUno GitHub App. You need a private key to sign access token requests.

For details about managing private keys for GitHub Apps, see the GitHub documentation.

Step 3 In PulseUno: Add a connection to GitHub. For details, see Add GitHub connection.
Step 4 In PulseUno: Add a mirror of your GitHub repository. For details, see Mirror a Git repository.
Step 5 In PulseUno: Verify that the GitHub connection is enabled for the mirrored GitHub repository. For details, see Verify GitHub connection.
Step 6 In PulseUno: In your mirrored repository, set up a chain to publish results to GitHub. For details, see Create a chain to publish to GitHub.

Back to top

Add GitHub connection

To integrate with GitHub, configure a connection to GitHub.com or GitHub Enterprise in PulseUno.

Note: Administrator permissions required.

To set up a GitHub connection:

  1. In PulseUno, navigate to Administration > Connections.

  2. On the Connections page, click New Connection and select GitHub from the list.

  3. On the new connection page, provide the GitHub authentication details:

    Field Description
    Title Enter the name for the GitHub connection.
    GitHub server URL

    Enter the GitHub URL:

    • To use the connection for all repositories in a GitHub instance, enter a GitHub instance URL:

      https://github.com

    • To use the connection for all repositories in a GitHub user or organization account, enter:

      https://github.com/<owner>

    • To connect to a specific GitHub repository, enter: 

      https://github.com/<owner>/<repo>

      where <repo> is the name of your GitHub repository without the .git extension.

    GitHub Application ID

    Enter the ID of the GitHub App installed on your GitHub repository, for example, 123456.

    You can find the GitHub App ID on the settings page of your app in GitHub.

    GitHub Application Private Key

    Enter the private key you generated for the GitHub App.

    If the private key is a PEM file, copy the contents of the file and paste them into this field.

  4. Click Save.

    A working connection is displayed with the Connected status.

After adding a GitHub connection, create a mirror of the GitHub repository to which you want to send chain results. For details, see Mirror a Git repository.

Back to top

Verify GitHub connection

After you have added a GitHub connection and created a mirror of your GitHub repository, PulseUno maps the connection to the mirror repository automatically. Verify that the setup is correct and the connection is enabled.

Note: Administrator permissions required.

To verify the connection to GitHub:

  1. In PulseUno, on the top navigation bar, select a space from the spaces list.

  2. On the Products page, open the Git repository you have set up as a GitHub mirror.

  3. On the sidebar, select Settings > Integrations.

  4. On the Integrations page, in the GitHub section, verify that the correct GitHub connection is displayed.

    Click the connection link to view the GitHub connection details.

After verifying the GitHub connection, configure a chain to send results to GitHub.

Back to top

Create a chain to publish to GitHub

When you have verified that the GitHub connection is enabled for the mirrored GitHub repository, you can run chains from the mirrored repository to publish results to your repository on GitHub.

Note: Administrator, owner, or maintainer permissions required.

To configure a chain to publish results to GitHub:

  1. In PulseUno, on the top navigation bar, select a space from the spaces list.

  2. On the Products page, open the Git repository you have set up as a GitHub mirror.

  3. On the sidebar, select Chains.

  4. Open the chain you want to use for the integration, and click Edit.

    Or create a new chain, as described in Create chains.

  5. In the Steps tab, click Add Step to Chain next to the chain title.

  6. From the Add Step list, add the Publish results to GitHub step.

  7. Click the step and enter the following configuration details:

    Field Description
    Title (Optional) Rename the plugin step.
    Send findings to a GitHub commit

    By default, PulseUno sends findings and converts them into annotations on a GitHub commit.

    Clear this option to send only a build summary.

    Control options

    (Optional) Define the control options for the plugin step:

    • Enable step. By default, the step is enabled to run. Clear this option if you need to deactivate the step.

      Disabled steps are skipped when the chain runs.

    • Fail the step. Specify the conditions for failing the step, such as unit test failures, findings criteria, and/or console log entries.

    • Mark step as unstable. Specify the conditions for making the step unstable, such as unit test failures, findings criteria, and/or console log entries.

    Output variables (Optional) Specify the output variables to be passed to other steps down the chain. For details, see Publish output variables.
  8. To specify the schedule or the conditions for running the chain, select the Triggers tab and set the Run chain option. For details, see Schedule chain runs.

  9. Click Save & Continue.

Back to top

See also: