Integrate Nx Cloud with your source control platform to access run results, logs, and build insights directly from your pull requests or merge requests.
The Nx Cloud GitHub App lets you access the result of every run—with all its logs and build insights—straight from your PR.
Install the App
Section titled “Install the App”For the best experience, install the Nx Cloud GitHub App. Using the app provides the most seamless authentication experience. This is not required if you wish to authenticate with a personal access token that you generate yourself.
Connecting Your Workspace
Section titled “Connecting Your Workspace”Once you have installed the Nx Cloud GitHub App, you must link your workspace to the installation. To do this, sign in to Nx Cloud and navigate to the VCS Integrations setup page. This page can be found in your workspace settings, you need to be admin of the organization in order to access it. Once on the VCS Integrations setup page, you can choose what VCS you want to connect to your workspace.
Choosing an Authentication Method
Section titled “Choosing an Authentication Method”It is easier to configure the Nx Cloud GitHub Integration to use its GitHub App to authenticate, and this method should be preferred for users on Nx Public Cloud. Advanced users or Nx Enterprise clients may instead wish to generate a personal access token instead.
Using the GitHub App
Section titled “Using the GitHub App”To use the Nx Cloud GitHub App for authentication, select the radio button and then click "Connect". This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved. Check the "CI Platform Considerations" section below and if there are no additional instructions for your platform of choice, setup is complete.
Using a Personal Access Token
Section titled “Using a Personal Access Token”Github supports two Personal Access Token types: Classic and Fine-grained.
To use a Personal Access Token for authentication, one must be generated with proper permissions. The minimum required permissions are shown in the screenshot below.
Classic Token personal access token
Section titled “Classic Token personal access token”
Fine-grained personal access token
Section titled “Fine-grained personal access token”
Once this token is created, select the radio button for providing a personal access token, paste the value, and then click "Connect". This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved. Check the "CI Platform Considerations" section below, and if there are no additional instructions for your platform of choice, setup is complete.
Advanced Configuration
Section titled “Advanced Configuration”If your company runs a self-hosted GitHub installation, you may need to override the default URL that Nx Cloud uses to connect to the GitHub API. To do so, check the box labeled "Override GitHub API URL" and enter the correct URL for your organization.
CI Platform Considerations
Section titled “CI Platform Considerations”If you are using CircleCI, TravisCI, GitHub Actions or GitHub, there is nothing else you need to do. If you are using other CI providers, you need to set the NX_BRANCH environment variable in your CI configuration. The variable has to be set to a PR number.
For instance, this is an example of doing it in Azure pipelines.
Azure Pipelines
Section titled “Azure Pipelines”variables: NX_BRANCH: $(System.PullRequest.PullRequestNumber)CircleCI
Section titled “CircleCI”Make sure GitHub checks are enabled.
Jenkins
Section titled “Jenkins”Ensure this step from the plugin instructions is followed:
Prerequisite: only GitHub App with proper permissions can publish checks, this guide helps you authenticate your Jenkins as a GitHub App.
Github Status Checks
Section titled “Github Status Checks”The Nx Cloud GitHub Integration updates your PR with commit statuses that reflect the real-time progress of your runs. These statuses are generated dynamically based on your running commands. Enforcing these dynamically-named checks within your branch protection rules is not recommended, as it can result in stuck checks displaying Waiting for status to be reported.
From your repository, go to Settings -> Branches -> Protect matching branches and ensure that no Nx Cloud status checks are listed in the Require status checks to pass before merging list. Enforcing that status checks pass on your default branch is sufficient. 
The Nx Cloud + Bitbucket Integration lets you access the result of every run—with all its logs and build insights—straight from your PR.
Using an App Password
Section titled “Using an App Password”If you are using BitBucket Cloud (bitbucket.org) and are not self-hosting it, you can enable an "app password" for authentication.
The minimum required permissions are write access to PRs:
Once the app password is created, save it in a secure location and then head back to your workspace settings on NxCloud and let's set up a BitBucket integration:
- Fill-in all the required fields for selecting your Bitbucket repository
- Username is found on the account settings screen (it is not your email address)
- Paste your app password created earlier into the Access Token box
- That's it!
Using an HTTP Access Tokens
Section titled “Using an HTTP Access Tokens”If you are using BitBucket Data Center (on-prem) you need to enable "HTTP Access Tokens" for authentication.
The minimum required permissions are write access to the repository:
Once the token is created, save it in a secure location and then head back to your workspace settings on NxCloud and let's set up a BitBucket integration:
- Fill-in all the required fields for selecting your Bitbucket repository
- Username is found on the account settings screen (it is not your email address)
- Paste your access token created earlier into the Access Token box
- Make sure you give NxCloud the URL of your BitBucket instance (this can be in the simple form of
https://your-bitbucket-instance.com) - That's it!
The Nx Cloud GitLab Integration lets you access the result of every run—with all its logs and build insights—straight from your Merge Requests.
Connecting Your Workspace
Section titled “Connecting Your Workspace”
Once on the VCS Integrations setup page, select "GitLab". You will be prompted to enter your project's ID.
To locate the ID for your project, visit the home page of your repository on GitLab. The value can be found underneath the name of your project, and has a clickable button to copy to your clipboard.
Using a Personal Access Token
Section titled “Using a Personal Access Token”To use a Personal Access Token for authentication, one must be generated with proper permissions. The minimum required permissions are shown in the screenshot below.
Once this token is created, select the radio button for providing a personal access token, paste the value, and then click "Connect".
This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved, and setup is complete.
Advanced Configuration
Section titled “Advanced Configuration”If your company runs a self-hosted GitLab installation, you may need to override the default URL that Nx Cloud uses to connect to the GitLab API. To do so, check the box labeled "Override GitLab API URL" and enter the correct URL for your organization.
The Nx Cloud + Azure Devops Integration lets you access the result of every run—with all its logs and build insights—straight from your PR.
Connecting Your Workspace
Section titled “Connecting Your Workspace”
Once on the VCS Integrations setup page, select "Azure DevOps". You will be prompted to enter the name of your organization and project.
Identifying your organization and project can be done by looking at the URL of your project summary page.
// URL formathttps://dev.azure.com/[organization]/[project]For example, the url https://dev.azure.com/nrwl/my-monorepo-project has an organization name of "nrwl", and a project name of "large-monorepo".
You will also need to provide the id of your Azure Git repository, this can either be the internal GUID identifier, if known, or you can use the name of the repository from the URL you use to access it.
For example, a URL of https://dev.azure.com/nrwl/_git/large-monorepo has the repository id of "large-monorepo".
Configuring Authentication
Section titled “Configuring Authentication”Using a Personal Access Token
Section titled “Using a Personal Access Token”To use a Personal Access Token for authentication, one must be generated with proper permissions. The minimum required permissions are shown in the screenshot below.
Once this token is created paste the value and then click "Connect".
This will verify that Nx Cloud can connect to your repo. Upon a successful test, your configuration is saved, and setup is complete.
Please note that Azure DevOps will impose rate limits which can degrade the performance of the integration leading to missing data or functionality. To mitigate the impact, we recommend you assign the Basic + Test plan to the user whose token you utilise for this integration.
Advanced Configuration
Section titled “Advanced Configuration”If your company runs a self-hosted Azure DevOps installation, you may need to override the default URL that Nx Cloud uses to connect to the Azure Devops API. To do so, check the box labeled "Override Azure DevOps API URL" and enter the correct URL for your organization.