GitHub Setup

The GitHub plugin lets Nitejar respond to issue comments, triage new issues, and monitor CI check results. It posts once after a run completes, so you get a single visible reply per event instead of streaming output.

Plugin type: github | Category: code | Response mode: final

Authentication model

Nitejar uses GitHub App credentials for GitHub integration. This gives per-installation tokens, granular permissions, and webhook delivery managed by GitHub.

A separate OAuth flow (clientId + clientSecret) is available for manifest-based registration metadata, but runtime API access is still GitHub App-based.

GitHub App setup

1. Create a GitHub App

Go to GitHub > Settings > Developer settings > GitHub Apps > New GitHub App.

Fill in:

• App name -- anything you like (for example, nitejar-prod)
• Homepage URL -- your Nitejar instance URL
• Webhook URL -- leave blank for now; you will set this after creating the plugin instance
• Webhook secret -- generate a strong random string and save it somewhere safe

openssl rand -hex 32

2. Set permissions

Under Permissions & events, grant:

3. Subscribe to events

Subscribe to:

• issue_comment
• issues
• check_run

The plugin also handles installation and installation_repositories events automatically for lifecycle management.

4. Download the private key

After creating the app, click Generate a private key. GitHub downloads a .pem file. Keep this file safe.

5. Add credentials

Set appId and privateKey directly in the plugin instance config. Both fields are stored encrypted at rest.

Create a plugin instance

1. Open the dashboard at /.
2. Go to Plugins in the sidebar.
3. Find the GitHub plugin and click New Instance.
4. Fill in the configuration:
   • Auth fields -- appId + privateKey
   • Webhook secret -- the secret you generated earlier
   • Allowed repos (allowedRepos) -- optional; if set, only those repos create inbound work
5. Assign an agent to the instance.
6. Save.

Note the Instance ID shown after saving. You need it for the webhook URL.

Configure webhooks

The webhook URL pattern is:

https://YOUR_NITEJAR_URL/api/webhooks/plugins/github/INSTANCE_ID

Replace YOUR_NITEJAR_URL with your public base URL and INSTANCE_ID with the ID from the previous step.

Go back to your GitHub App settings, set the Webhook URL, and paste the webhook secret you generated earlier.

Understand GitHub access layers

On this branch, GitHub access is intentionally layered:

1. Plugin assignment connects an agent to the GitHub channel so it can receive inbound work from that instance.
2. Comment policy and allowed repos decide which inbound events create work.
3. Role defaults and policy posture decide what outbound GitHub operations an agent should be allowed to perform once it is working.

This separation matters. An agent being assigned to the GitHub plugin does not automatically mean it should be able to act broadly across every repository workflow.

Configure comment policy

The commentPolicy setting controls which issue comments trigger the agent:

Set this in the plugin instance config. The default mention handle is @nitejar.

Configure role-based GitHub repo defaults

GitHub repo capabilities are modeled as reusable defaults through Company > Roles. Use roles when multiple agents should share the same outbound GitHub posture.

Typical capabilities include:

• read repository contents
• create or push branches
• open PRs
• comment on issues and PRs
• request review, review PRs, apply labels, or merge

Use role defaults when you want consistency across a team of agents. Use per-agent configuration when one agent should diverge from the role's usual posture.

What events does the plugin handle?

Two additional config flags control event processing:

• trackIssueOpen (default: true) -- set to false to ignore new or reopened issues
• trackCheckRun (default: true) -- set to false to ignore CI check completions

Inbound handling creates work. Outbound GitHub actions during a run still depend on the agent's granted posture and repo capabilities.

Test it

1. Go to a repo where the app is installed.
2. Create a new issue with a title like "Test Nitejar" and mention the bot in the body: @nitejar what can you do?
3. Wait for the agent to process the work item and post a response comment.
4. Open Command Center first to see whether the event created an attention item, then open Activity. You should see the work item with a full receipt trail.

If using the mentions comment policy, make sure the mention handle matches the bot's GitHub username.

Troubleshooting

Webhook not delivering

• Verify the webhook URL is correct and publicly reachable.
• Check the Recent Deliveries tab in your GitHub webhook settings.
• Make sure the content type is set to application/json.

401 or signature mismatch

• The webhookSecret in the plugin instance config must exactly match the secret configured in GitHub.
• If you rotated the secret, update both sides.

Bot not responding to comments

• Check the commentPolicy setting.
• Confirm the repo is in allowedRepos if that field is set.
• Verify the plugin instance has an agent assigned.
• If the agent needs to take outbound repo actions, confirm the agent's role defaults and policy posture are broad enough for the required GitHub capability.

Wrong permissions

• The GitHub App must have Issues: read & write to post comments.
• For check run monitoring, Checks: read is sufficient.

Configuration reference