Skip to content

GitHub integration

Pulse integrates with GitHub Cloud to receive data about changes and deployments, necessary to calculate the metrics:

Setting up the GitHub integration

To set up the GitHub integration:

  1. On Pulse, expand Integrations and select GitHub.

  2. Click Install GitHub App and follow the instructions on the GitHub UI to install the app on your organization.

    Important

    You can only install the Pulse GitHub App on an organization and not on your personal account.

    Installing the Pulse GitHub App

  3. Wait until you get a confirmation that Pulse successfully created the integration and the webhook on GitHub.

    Pulse GitHub integration set up successfully

    If there was an error please contact support.

  4. Choose the strategy to detect deployments that best fits your workflows, or turn off the automatic deployment detection. See the section below for a detailed description of each option.

    Choosing a deployment detection strategy

Automatic deployment detection strategies

The following is a detailed description of how the Pulse GitHub integration automatically detects deployment using each detection strategy:

Use merged pull requests (default)

  • Pulse considers a deployment every merged pull request that targets the default branch of the repository.
  • The deployment date is the timestamp when the corresponding pull request is merged.
  • The set of changes in a deployment is the list of commits in the corresponding pull request. Pulse correctly tracks your changes even if you squash or rebase the commits when merging the pull request, since Pulse processes all the original commits before any changes to the Git history.
  • Pulse associates all GitHub teams of the author of a merged pull request with the corresponding deployment, excluding teams with less than two members. Pulse only takes changes to GitHub teams into account on pull requests merged after those changes.

Use semantic versioning tags

  • Pulse considers a deployment every Git tag that follows the SemVer convention, excluding pre-release versions but allowing release prefixes. For example, the following are valid tags: 1.0.0, v2.3.4.

    To use this strategy, make sure that you're creating Git tags on your repositories for each successful deployment to production, or whenever you make a new release available to any user of your application:

    git tag -a MAJOR.MINOR.PATCH -m "<Deployment or release message>"
    

    Where MAJOR.MINOR.PATCH must be a valid SemVer version without pre-release information. Check if your versioning syntax is valid.

  • The deployment date is either the creation date of annotated tags or the timestamp when Pulse receives the webhook calls for lightweight tags.

    Keep in mind that since webhook calls can be delayed, the deployment date on Pulse could be imprecise and impact the metric Lead time for changes.

  • The set of changes that belong to a deployment is the list of commits between the tag of that deployment and the previous tag. Because of this, Pulse discards:

    • The first SemVer tag in the repository since there is no previous tag to compare with.
    • Any tag that does not have a common ancestor (commit) with its previous tag, since Pulse cannot obtain the changes between them.
  • Pulse associates all GitHub teams of the person who creates a Git tag with the corresponding deployment, excluding teams with less than two members. Pulse only takes changes to GitHub teams into account on Git tags created after those changes.

Don't detect deployments automatically

  • If the option Detect deployments using GitHub is turned off, Pulse doesn't detect deployments automatically using GitHub events.

    This is useful if none of the automatic deployment detection strategies match your workflow and you must have control over the way Pulse tracks your deployments.

  • In this case, you must send to Pulse the information about your deployments and the corresponding changes using the Pulse CLI or the Ingestion API.

Collected data

The table below lists the data that the GitHub integration collects from your GitHub organization, together with:

  • The mapping between the data collected from GitHub and the Pulse data model
  • The metrics that Pulse calculates from the data to display on the dashboards
Data collected from GitHub Mapping to Pulse data model Used in
Pull request commits

Changes:

  • change_id: commit UUID
  • time_created: commit author date1
  • system: repository name
Lead time for changes on the Accelerate Overview dashboard
Pull requests, git tags, or none (configurable)

Deployments:

  • deploy_id: pull request ID
  • system: repository name
Deployment frequency and Change failure rate on the Accelerate Overview dashboard
Pull requests - Changes & Reviews dashboard,
Work in Progress dashboard
Teams

Deployments:

  • teams: GitHub teams of the author of a deployment2
Filters the Accelerate Overview dashboard, Changes & Reviews dashboard, and Work in Progress dashboard by the contributions made by the team

1: Pulse uses the commit author's date since it is more accurate. The committer date can be changed (e.g.: rebases) and stop reflecting the real creation date of the change.

2: Adding a new team or changing the composition of a team on GitHub only affects new data from that moment onwards and doesn't have an immediate impact on the dashboards. Also, deleted teams on GitHub will continue to show in Pulse.

See also