Skip to content

GitHub and Slack trial

Humagen owns clients (which Slack apps and GitHub installations a workspace answers through), agent definitions, review and command policy, and the run history shown in its console. Fiber supplies signed webhooks, API capabilities, routing and execution. Humagen internal/presentation/github supplies the review and guide Markdown. The same repository contains the shared web and Slack components.

Local setup

The external Go modules are pinned in go.mod, to released versions apart from anchor's Postgres adapter, which has no release yet and is pinned to a commit, so the server builds from this checkout alone. Use go test ./... -race to verify the composition. Run go run ./examples/github-review for a token-free preview.

Provide ANTHROPIC_API_KEY and HUMAGEN_AGENT_MODEL for a model available to your Anthropic account. The example specs use the supported anthropic provider. Startup replaces the YOUR_MODEL_ID placeholder using HUMAGEN_AGENT_MODEL. An offline test is not evidence that a paid model has been exercised.

go run ./cmd/humagen serve -auth=dev -tenant=trial \
  -webhook-addr=127.0.0.1:8383 \
  -agent-specs=examples/github-review/agent.json,examples/github-review/fixer.json
# In another terminal:
make web

The console uses localhost:5173 and the API localhost:8080. External runs appear on the same Runs page as console runs. The variables below create one default client per surface in tenant trial. Only that tenant can see or use it; inbound payloads cannot choose a tenant. Further clients, such as a second Slack app that answers as another agent, are created through POST /api/clients. See clients. Stores are in memory unless the server runs with -state=postgres, the default when HUMAGEN_POSTGRES_URL is set.

Forward only port 8383, whose handler exposes signed webhook endpoints and readiness. /api, /auth and the console are absent there. Never forward the dev-auth console/API listener. Stop the forwarder and process after the trial.

One credential item

Keep the GitHub, Slack and model credentials together in one 1Password Secure Note named Warp integrations (its name from before the product was renamed; references below name it), with concealed custom fields. Reuse an existing item when one exists. Copy values through 1Password's UI or CLI input, not command-line arguments, source files, terminal output or chat.

Field Runtime use
anthropic_api_key ANTHROPIC_API_KEY
github_app_id, github_installation_id, github_private_key Mint a repository-scoped installation access token
github_token HUMAGEN_GITHUB_TOKEN, a current installation token
github_webhook_secret HUMAGEN_GITHUB_WEBHOOK_SECRET
slack_bot_token HUMAGEN_SLACK_TOKEN
slack_signing_secret HUMAGEN_SLACK_SIGNING_SECRET
slack_team_id, slack_bot_user_id Workspace and agent routing

The server accepts a token per client. For GitHub that token is either a current installation token, which you refresh before it expires, or the App's private key PEM. Given the private key with the client's identity.app_id and identity.installation, the server mints installation tokens and refreshes them before they expire (clients.md). Keep non-secret model, repository, bot mappings and forwarding URLs alongside the item's instructions. No credentials were created or consolidated by this migration; a live trial needs the actual item and targets.

Use 1Password op run --env-file with a local reference-only environment file:

ANTHROPIC_API_KEY=op://Private/Warp integrations/anthropic_api_key
HUMAGEN_GITHUB_TOKEN=op://Private/Warp integrations/github_token
HUMAGEN_GITHUB_WEBHOOK_SECRET=op://Private/Warp integrations/github_webhook_secret
HUMAGEN_SLACK_TOKEN=op://Private/Warp integrations/slack_bot_token
HUMAGEN_SLACK_SIGNING_SECRET=op://Private/Warp integrations/slack_signing_secret

Then start the command above through op run --env-file=<local-reference-file> --. Do not commit that local file or capture the injected environment in logs. The default clients record only the names of these variables, and only the server's -tenant may reference them. A client created through the API can reference a variable of its own only if the server was started with -secret-refs '<tenant>=HUMAGEN_NAME,...' listing it for that tenant. With no list, write the secret as a value. See clients.

GitHub installation

Use GitHub's manifest registration flow with humagen's manifest. Replace its app name, webhook URL and callback URL.

  1. Submit JSON in the manifest form field to https://github.com/settings/apps/new, with random state. Organization apps use /organizations/ORG/settings/apps/new.
  2. Validate the returned state before accepting the callback's code.
  3. Within one hour, exchange the code through POST https://api.github.com/app-manifests/{code}/conversions.
  4. Save the returned credentials into the consolidated 1Password item, preserving Slack/Anthropic fields, then install the app on the selected repository.

The callback receiver must keep credentials out of browser responses and logs. The template's localhost callback is a placeholder, not a receiver started by humagen serve. Registration callback and 1Password-writing automation are not implemented here. The transcript's temporary setup page is not bundled, and its passkey prompt does not establish that an app was created.

Setting Value
Webhook URL Your forwarder's public URL, targeting /connectors/github on port 8383
Events issues, issue_comment, pull_request, pull_request_review, pull_request_review_comment
Review permissions Issues write, Pull requests write, Checks write, Contents read, Metadata read
Optional fix/check permissions Contents write and Actions write; Actions read for observing CI

A public third-party relay such as smee receives the webhook payload. Use an approved sandbox repository for a trial and relay only GitHub deliveries to the GitHub endpoint. Slack URL verification requires a request/response-capable forwarder, not a GitHub-style asynchronous relay.

export HUMAGEN_GITHUB_OWNERS='your-account'
export HUMAGEN_GITHUB_BOTS='your-app[bot]=github-agent'
export HUMAGEN_GITHUB_DEFAULT_AGENT=github-agent
export HUMAGEN_GITHUB_CHECKS=true
export HUMAGEN_GITHUB_GUIDES=true

A pull request that opens ready for review, leaves draft or gets a push is reviewed by the default agent, once per commit; labels start nothing (see Automatic review). Mention the app for questions. For writes, map the app to github-fixer and enable HUMAGEN_GITHUB_MUTATIONS=true. Only explicit /fix or /check <run-id> requests from repository writers receive a run-bound grant. See GitHub.

Slack installation

Create or update the app using the manifest, replace YOUR_HOST with the forwarder URL, install it, and invite its bot to the trial channel. Configure the bot token/signing secret through the credential item. Set HUMAGEN_SLACK_TEAM, HUMAGEN_SLACK_BOTS (bot-user-id=agent-name) and HUMAGEN_SLACK_DEFAULT_AGENT. Team is required; a request for a team no client serves is a 404. Set HUMAGEN_SLACK_APP to the app id when more than one Slack app will be installed in the team.

HUMAGEN_SLACK_SESSIONS=true enables agent-session progress. Optional HUMAGEN_SLACK_COMMANDS is a JSON array of command names, descriptions and argument hints. Advertise only tasks supported by the chosen agent; registering create-pr does not itself add a PR-creation tool. GitHub mutations cannot be authorized by a Slack command. Cross-source GitHub reads require exact repository grants in HUMAGEN_GITHUB_READ_REPOSITORIES.

Session and code-channel availability depends on Slack's workspace features. Permanent feature/permission refusals are logged; normal threaded answers remain usable. No code-channel creation or native streaming is advertised. See Slack for status/error behavior and the remaining limitations.

Acceptance evidence

The automated suite checks signed ingress, routing to the right client among several, isolation between workspaces, correct tenant visibility in the console API, guide updates, distinct reviews, thread replies, atomic fix commits, workflow reruns and pending states, and Slack lifecycle/command policy using fake or in-process APIs. A live trial additionally needs a real bot reply, the same run in the console, actual model usage, and observed GitHub/Slack status. Do not call it live-validated until those results have been collected.