Documentation Index
Fetch the complete documentation index at: https://docs.blocks.team/llms.txt
Use this file to discover all available pages before exploring further.
Overview
GitHub Enterprise (MU) connects Blocks to a GitHub Enterprise managed user tenant by using a GitHub App that you create and own in your enterprise organization.
This guide uses CubeOrgSquaredApp as an example app name. You can choose any unique, descriptive name for your own app.
This setup creates fresh credentials for your GitHub App. Do not copy app IDs, client IDs, private keys, webhook secrets, or client secrets from another app.
Prerequisites
- Organization owner or admin access in your GitHub Enterprise managed user tenant
- Admin access to your Blocks workspace
- Your enterprise web host URL, such as
https://cubeorg.ghe.com
- Your enterprise API host URL, such as
https://api.cubeorg.ghe.com
- A secure place to store the generated webhook secret, client secret, and private key
For GitHub’s own setup references, see Registering a GitHub App, Choosing permissions for a GitHub App, and Managing private keys for GitHub Apps.
Step 1: Create a GitHub App
In your enterprise organization, open:
https://<your-enterprise-web-host>/organizations/<your-org>/settings/apps/new
https://cubeorg.ghe.com and your org is CubeOrgSquared, open:
https://cubeorg.ghe.com/organizations/CubeOrgSquared/settings/apps/new
Step 2: Enter basic app details
Use these values when creating the app:
| Field | Value |
|---|
| GitHub App name | A unique name, such as CubeOrgSquaredApp |
| Description | Optional |
| Homepage URL | https://blocks.team |
https://api.blocks.team/v1/webhooks/github/completion
https://api.blocks.team/v1/webhooks/github/redirect
https://api.blocks.team/v1/webhooks/github/redirect?is_onboarding=true
| Option | Setting |
|---|
| Request user authorization (OAuth) during installation | Checked |
| Enable Device Flow | Unchecked |
| Field | Value |
|---|
| Active | Checked |
| Webhook URL | https://api.blocks.team/v1/webhooks/github/events |
| Secret | Generate a new strong secret and save it securely |
| SSL verification | Enable SSL verification |
Step 4: Set repository permissions
Under Repository permissions, set only the permissions Blocks needs:
| Permission | Access |
|---|
| Actions | Read-only |
| Administration | Read & write |
| Checks | Read & write |
| Contents | Read & write |
| Deployments | Read & write |
| Discussions | Read & write |
| Environments | Read & write |
| Issues | Read & write |
| Metadata | Read-only |
| Pull requests | Read & write |
| Webhooks | Read & write |
| Workflows | Read & write |
Step 5: Set organization permissions
Under Organization permissions, set:
| Permission | Access |
|---|
| Administration | Read & write |
| Members | Read-only |
| Personal access token requests | Read & write |
| Webhooks | Read-only |
Step 6: Subscribe to events
Subscribe to exactly these events:
- Commit comment
- Create
- Delete
- Issue comment
- Issues
- Label
- Pull request
- Pull request review
- Pull request review comment
- Pull request review thread
- Push
- Repository
- Sub issues
- Workflow dispatch
- Workflow run
Leave all other events unchecked.
Step 7: Choose app visibility
Under Where can this GitHub App be installed?, choose the option that matches your enterprise policy:
- Only on this account if the app should only be installed in the organization where you created it
- Any account if your enterprise admins want the same app to be installable by other accounts on the tenant
If you are recreating an existing app, match the original app’s visibility and any optional feature settings before finishing.
Step 8: Generate app credentials
After you create the GitHub App:
- Copy the new App ID.
- Copy the new Client ID.
- Generate a new client secret and save it securely.
- Generate a new private key, download the
.pem file, and save it securely.
- Keep the webhook secret you generated in Step 3 available for the Blocks configuration form.
Private keys, client secrets, and webhook secrets are sensitive credentials. Store them in your normal secrets manager and avoid pasting them into tickets, chat messages, or documentation.
Step 9: Select the GitHub Enterprise (MU) integration
In Blocks, go to Settings > Integrations > GitHub. In the GitHub organization row, choose GitHub Enterprise (MU) from the dropdown, then click Configure.
Fill in the values from your GitHub App in the configuration dialog.
| Blocks field | Value |
|---|
| Web host URL | Your enterprise web host, such as https://cubeorg.ghe.com |
| API host URL | Your enterprise API host, such as https://api.cubeorg.ghe.com |
| GitHub App ID | The App ID from the GitHub App settings page |
| GitHub App name | The app slug/name you created, such as CubeOrgSquaredApp |
| Client ID | The Client ID from the GitHub App settings page |
| Client secret | The client secret you generated after app creation |
| Private key | The full contents of the downloaded .pem private key |
| Webhook secret | The webhook secret you created in Step 3 |
Step 11: Install the app
Install the GitHub App on the organization and repositories Blocks should access. You can install it on all repositories or choose a selected set, depending on your team’s policy.
After installation, you can mention @blocks in issues, pull requests, and pull request review comments in connected repositories.
Troubleshooting
- OAuth redirect fails: Confirm the callback URLs are present and ordered exactly as shown in Step 2.
- Webhook deliveries fail: Confirm the webhook URL, webhook secret, and SSL verification setting match Step 3.
- Blocks cannot read or write repository data: Recheck the repository and organization permissions, then reinstall or update the GitHub App installation.
- Private key errors: Generate a fresh private key in GitHub, update the Blocks configuration, and make sure the pasted value includes the full
BEGIN and END lines.
