Core concepts
Connectors
GitHub, Slack and Jira ingestion for self-hosted deployments.
A connector ingests a GitHub repository, a Slack channel, or a Jira project into a namespace. Once a workspace owner has connected the provider from Settings → Integrations, anyone with access to a namespace can subscribe it to a source from the namespace's Sources tab; polling and webhooks then keep the namespace current, and everything ingested meters as retain.
Connectors need provider credentials on both the API and the worker processes.
The hosted app at app.illumina.sh does not ship them, so Settings →
Integrations shows every provider as Unavailable there. The tables below are
what a self-hosted deployment sets; the docs/runbooks/ directory in the
repository walks through creating each provider app.
GitHub
Register one GitHub App for the deployment. Each workspace installs it on the repositories it wants to sync.
| Variable | Required | Notes |
|---|---|---|
GITHUB_APP_ID | Yes | Numeric App id. Needed on the API and the worker. |
GITHUB_APP_PRIVATE_KEY | Yes | Full PEM, PKCS#1 or PKCS#8. Needed on the API and the worker. |
GITHUB_APP_CLIENT_ID | Yes | Client id of the App's OAuth flow. |
GITHUB_APP_CLIENT_SECRET | Yes | Client secret of the App's OAuth flow. |
GITHUB_APP_SLUG | Yes | Drives the Install button; alphanumerics and hyphens only. |
GITHUB_OAUTH_REDIRECT_URI | Yes | Must equal the App's Callback URL. The Install button does not render without it. |
GITHUB_WEBHOOK_SECRET | Yes | Must equal the App's webhook secret; deliveries with a bad signature are rejected. |
Without GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY on the worker, Integrations
reads Connected but nothing ever syncs.
Slack
Register one Slack app for the deployment. Each workspace connects its own Slack team through the app's OAuth flow, and the resulting bot token is sealed per workspace.
| Variable | Required | Notes |
|---|---|---|
SLACK_CLIENT_ID | Yes | Client id of the app's OAuth flow. |
SLACK_CLIENT_SECRET | Yes | Client secret of the app's OAuth flow. |
SLACK_SIGNING_SECRET | Yes | Verifies inbound events. Unset, the webhook answers 503 and Slack never verifies the Request URL. |
SLACK_OAUTH_REDIRECT_URI | Yes | Must equal the app's Redirect URL; Slack rejects a mismatch at code exchange. |
SLACK_BOT_TOKEN | No | An xoxb-… token from your own install. Counts toward the provider being reported as configured; polling and delivery always use the workspace's sealed token from the OAuth flow. |
Sealing a workspace's token uses the key derived from ILLUMINA_INTERNAL_SECRET,
which the worker also needs. Rotating that secret makes every stored Slack and
Jira credential unopenable and forces each workspace to reconnect.
Jira
Register one Atlassian OAuth 2.0 app for the deployment. Each workspace links the Jira site it administers through the consent flow, and the token pair is sealed per workspace.
| Variable | Required | Notes |
|---|---|---|
JIRA_CLIENT_ID | Yes | OAuth app client id. |
JIRA_CLIENT_SECRET | Yes | OAuth app client secret. |
JIRA_OAUTH_REDIRECT_URI | Yes | Must equal the app's Callback URL. |
With any of the three unset, Jira reports configured: false and the Connect
button does not appear.
A legacy single-site mode reads JIRA_CLOUD_ID, JIRA_EMAIL, and
JIRA_API_TOKEN instead. It only serves a workspace that already has an
installation and has linked no credentials of its own; a workspace that connects
through OAuth never falls back to it.