Pull Request Workflow in Holistics

Open Beta

PR Workflow is in open beta and currently supports GitHub only

Introduction

In a typical development process, when you make changes in the development branch, you need to create a Pull Request (in GitHub) or a Merge Request (in GitLab) before publishing to production. This allows other users to review your changes and triggers the CI workflow for testing and validation.

This step is essential to ensure no downtime and maintain code quality in the production environment.

How PR Workflow works in Holistics

The PR Workflow in Holistics seamlessly integrates with your GitHub repository to enforce code review practices. Here's how it works:

1. Create PR from Holistics: When you've made changes and committed them in your Development workspace, Holistics provides a "Create PR" button that takes you directly to GitHub with a pre-filled pull request for your branch.

2. Track PR status: Once created, Holistics displays the PR status right in your workspace. You can continue making commits, and they'll automatically update the existing PR.

3. Auto-publish on merge: When your PR is approved and merged to master branch in GitHub, Holistics automatically detects this and publishes your changes to production. Your dashboards and reports become immediately available to end users - no manual publish step required.

4. Error handling: If there are any errors during the auto-publish process, Holistics will notify you and provide options to resolve them before the changes go live.

This workflow ensures that all production changes go through proper review while maintaining a smooth, automated deployment process.

How to setup PR Workflow in Holistics

Notes

Holistics uses a GitHub Personal Access Token to:

• Create Pull Requests in your repository
• Monitor PR status (open, closed, or merged)
• Enable necessary actions based on PR status (for e.g., auto trigger publish when the PR is merged to master branch)

Prerequisites

• You have connected to your GitHub repository to Holistics.
• You have admin permission to the repository that you have connected to Holistics.

Step 1: Enable PR workflow for your organization

1. Navigate to Settings > Project Settings > Enable PR Workflow.
2. Toggle on Enable PR Workflow button.
3. You will then be prompted to add the GitHub Access Token.

Step 2: Create GitHub access token

If your repository belongs to an organization, the organization owner must allow access via Personal Access Token.

You can use either Personal Access Token (Classic) or Fine-grained Access Token

• Personal Access Token (Classic) - recommended: Use this option for most cases. Classic tokens work with personal repositories and most organization repositories.
• Fine-grained Personal Access Token: Only required if your repository belongs to an organization that has disabled classic tokens and only accepts fine-grained tokens.

Tokens (classic) - Recommended

1. Go to GitHub Settings > Developer settings > Personal access tokens > Token (Classic) and create new token (or you can visit this link from GitHub)

   

2. Set the expiration date for your token (we recommend 90 days):

   • 
   • Holistics PR Workflow cannot function properly if the token is expired. So make sure to set the expiration date for your token to be far enough in the future.
   • 5 days before the token expires, you will see the inapp warning banner in Holistics.
     

3. Select scopes for your token

   • repo
   • admin:repo_hook
   

4. Click on Generate token

5. Copy the token and paste it in the Holistics dialog

Fine-grained Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens and create new token (or you can visit this link from GitHub)
   
2. Select the correct resource owner of your repository
   • 
3. Set the expiration date for your token (we recommend 90 days):
   • 
   • Holistics PR Workflow cannot function properly if the token is expired. So make sure to set the expiration date for your token to be far enough in the future.
   • 5 days before the token expires, you will see the inapp warning banner in Holistics.
     
4. Select the Repository that you have connected to Holistics
   
5. Set up Repository permissions:
   • Pull requests: Read only -> this is necessary for Holistics to create Pull Request in your repository from Holistics
   • Webhooks: Read and Write -> this is necessary for Holistics to check PR Status and set up Auto-Publish workflow
6. Click on Generate token
7. Copy the token and paste it in the Holistics dialog

Important Information

If your organization requires approval, an organization owner must approve this token before it can access private resources.

After pasting the token in Holistics, you may need to wait for approval before the integration becomes active

Set up PR is required or optional

Admin can control whether Pull Requests are mandatory for all changes or if analysts can publish small changes directly. This gives teams flexibility to balance between strict code review processes and allowing quick fixes.

How it works

1. Default behavior: By default, PR is not required. Users can publish changes directly from Development to Production without creating a Pull Request.

   

2. Enabling PR requirement: When you toggle on "Require PR for all changes", every change must go through a Pull Request before it can be published to production. This ensures all code modifications are reviewed before going live.

   

Configuration steps

1. Navigate to Settings > Project Settings > Git Integration
2. Under the PR Workflow section, locate the "Require PR for all changes" toggle
3. Toggle it ON to require PRs for every change, or leave it OFF to allow direct publishing

Impact on workflow

When PR is NOT required (default):

• Users can publish changes directly using the "Publish" button
• Suitable for teams that trust analysts to make small, low-risk changes
• Faster deployment for urgent fixes

When PR is required:

• The "Publish" button is disabled
• Users must create a PR for every change, regardless of size
• All changes go through review process
• Better for teams requiring strict change control

Best Practice

Consider your team's needs when deciding whether to require PRs:

• Require PRs if you have strict compliance requirements or want to ensure all changes are reviewed
• Keep optional if you trust your team to use PRs for significant changes while allowing quick fixes to go through directly

Using the PR Workflow

Once you have set up the PR workflow, here's how to use it:

Step 1: Make changes and create a PR

• Make changes to your files in Development Workspace. And then Commit
• Click on Create PR button in the top right corner
• After that, you will be redirected to GitHub to create a PR.
• Once the PR is created, back in Holistics, you will see the PR status has been updated in Holistics with Open status.

Step 2: Review, update, and approve the PR

• Once the PR is created, other people can review your PR and make comments.
• In the meantime, you can make changes to your PR in Holistics.

Step 3: Publish the PR

• Once the PR is approved and merged to master branch, the changes will be published to production automatically.
• If somehow the Publish process failed, you can try to publish it manually by clicking on Publish button in Holistics.
• In case you want to customize the Publish logic (for e.g., don't publish to production in weekend), you can use our Publish API instead of our normal Auto-Publish workflow.

Best Practices and Additional Tips

To enhance your PR workflow experience, consider implementing these recommended practices:

Customize PR templates

You can standardize pull request information by creating a PR template. Add a PULL_REQUEST_TEMPLATE.md file inside the .github/ directory in your repository. This template automatically populates when team members create new PRs, ensuring consistent documentation and review processes.

project-name (root)
    |- .github
        |   |- PULL_REQUEST_TEMPLATE.md
    |- models
    |- datasets
    |- dashboards

Here's an example structure for your PR template:

PULL_REQUEST_TEMPLATE.md

## Summary
Brief description of what this PR does

## Changes Made
- List the main changes
- Include any new models, datasets, or dashboards
- Mention any schema changes

## Testing
- [ ] Tested locally in development environment
- [ ] Verified data accuracy
- [ ] Checked performance impact
- [ ] Reviewed security implications

## Screenshots (if applicable)
Add screenshots of dashboard changes or new visualizations

## Related Issues
Closes #(issue number)

## Checklist
- [ ] Code follows team conventions
- [ ] Documentation updated
- [ ] No sensitive data exposed
- [ ] Breaking changes documented

Enable branch protection rules

Branch protection rules are essential for maintaining code quality and preventing accidental changes to your production branch. They ensure all changes go through proper review before merging.

Here's how to set up branch protection for your repository:

1. Go to your GitHub repository and navigate to Settings → Branches → Add branch protection rule

   

2. In the Branch name pattern field, enter master (or your main branch name)

   

3. Enable Require a pull request before merging - this ensures all changes must go through a PR and cannot be pushed directly to master

   

4. Select Do not allow bypassing the above settings - this applies the rules to everyone, including repository administrators

   

5. Click Create to save your branch protection rules

With these settings in place, your team must create pull requests for all changes, ensuring proper review and maintaining code quality standards.