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.
- Submit JSON in the
manifestform field tohttps://github.com/settings/apps/new, with randomstate. Organization apps use/organizations/ORG/settings/apps/new. - Validate the returned
statebefore accepting the callback'scode. - Within one hour, exchange the code through
POST https://api.github.com/app-manifests/{code}/conversions. - 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.