Set up Pull Request Workflow (for GitHub)

Introduction

This guide walks you through setting up the Pull Request (PR) Workflow in Holistics for GitHub repositories.

How to set up

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

Step 3: Configure PR required or optional

Admin can control whether Pull Requests are mandatory or optional for all changes. For detailed configuration instructions, see configure PR workflow required or optional in the main workflow documentation.

Using the PR Workflow

Once configured, you can start using the PR workflow to manage code changes:

1. Create a PR: After committing changes in Development, click Create PR in the top-right corner. This opens GitHub with a pre-filled pull request for your branch.

2. Track PR status: Holistics displays your PR status (Open, Closed, Merged) directly in the workspace. Continue making commits - they'll automatically update the existing PR.

3. Auto-publish on merge: When your PR is approved and merged to master, Holistics automatically publishes changes to production. No manual intervention needed.

For more details about the overall workflow, see Pull Request Workflow in Holistics.

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.