APIZ guide

GitHub Adapter

Use the GitHub Adapter when an agent needs GitHub REST or GraphQL access with repository-aware Policy actions. The GitHub token stays in the API Instance; the agent uses a generated APIZ bearer credential with its normal HTTP or SDK configuration.

What This Adapter Supports

GitHub REST endpoints and the /graphql endpoint.
Fine-grained or classic bearer tokens.
Repository, issue, pull-request, branch, and Actions-secret resources.
Official API endpoint and version header defaults.
Path/domain routing, semantic connection tests, and a read-only template.

Credential Boundary

The upstream GitHub token is write-only API Instance credential material. The agent receives a separate APIZ credential, normally with a ghp_apiz_ prefix. APIZ overwrites caller authentication after an allow decision and never returns the GitHub token in setup output or request evidence.

allowed_owners and allowed_repos are intent hints for review and Policy templates. They are not a GitHub repository allowlist until a Policy enforces the normalized resource.

Prepare The Upstream Credential

Prefer a fine-grained token restricted to selected repositories. Grant only the provider permissions the agent's approved actions require. For a read-only first test, repository metadata and contents read access are usually enough; issues, pull requests, workflows, packages, or secret management require their own GitHub permissions.

Record the intended owner/repo pairs before writing APIZ Policy. Never store the token in allowed_repos, tags, fixtures, or Policy source.

Web Console

Open API Instances → Create API Instance → GitHub.
Enter a name and the token only under GitHub credential.
Add optional owner and repository hints in owner/repo form.
Choose Current user for the first connection test, or Repository information with explicit owner and repository parameters.
Attach Allow GitHub reads when the agent must be read-only.
Test, confirm that no token value appears, and save.

The official endpoint and API version normally require no changes.

CLI

apiz adapter explain github

read -rsp "GitHub token: " GITHUB_TOKEN && printf '\n'
printf '%s' "$GITHUB_TOKEN" | jq -Rs '{credential: .}' |
apiz -o json api create \
  --adapter github \
  --name engineering-github \
  --config-json '{"allowed_owners":["acme"],"allowed_repos":["acme/demo"]}' \
  --test-config-json '{"preset":"get_repo_info","parameters":{"owner":"acme","repo":"demo"}}' \
  --credential-stdin
unset GITHUB_TOKEN

The names above are synthetic. Substitute a repository visible to the token.

Give An Agent Access

apiz -o json client create --name release-agent
apiz client bind <client-id> --api-instance <api-instance-id> --alias github
apiz client credentials create <client-id> --binding github --ttl 1h --format curl

In the Web Console use Clients → Add Binding, select the GitHub API Instance, optionally attach the repository Policy, then create a one-time Temporary Credential for that Binding.

Use It From The Agent

GitHub REST request:

curl -fsS \
  -H "Authorization: Bearer $APIZ_TEMPORARY_CREDENTIAL" \
  -H "Accept: application/vnd.github+json" \
  "$APIZ_GITHUB_ENDPOINT/repos/acme/demo/issues"

GraphQL request:

curl -fsS \
  -H "Authorization: Bearer $APIZ_TEMPORARY_CREDENTIAL" \
  -H "Content-Type: application/json" \
  --data '{"query":"query { viewer { login } }"}' \
  "$APIZ_GITHUB_ENDPOINT/graphql"

Use the generated endpoint as the GitHub API base URL when an SDK permits an endpoint override. The agent must not receive the upstream GitHub token.

Policy Actions And Resources

Resource	Read	Write	Dangerous
Repository or fallback endpoint	`github:repo:read`	`github:repo:write`	`github:repo:delete`
Issue	`github:issue:read`	`github:issue:write`	`github:issue:delete`
Pull request	`github:pull_request:read`	`github:pull_request:write`	`github:pull_request:delete`
Branch	`github:branch:read`	`github:branch:write`	`github:branch:delete`
Actions secret	`github:actions_secret:read`	`github:actions_secret:write`	`github:actions_secret:delete`

All Actions-secret operations are classified as dangerous, including metadata reads. The Allow GitHub reads template includes common repository, issue, pull-request, and branch reads but excludes Actions secrets. Add owner and repo resource conditions to create an enforced repository allowlist.

Connection Tests

Preset	Required parameters	Behavior
`get_user_info`	none	Reads `GET /user`
`get_repo_info`	`owner`, `repo`	Reads one repository
`list_packages`	`owner`; optional `owner_type`, `package_type`	Lists user or organization packages
`graphql_viewer`	none	Runs `query { viewer { login } }`

package_type defaults to container. Set owner_type to org or organization for organization packages.

Evidence And Troubleshooting

github_connection_unauthorized: the token is invalid, expired, or lacks access to the tested resource.
Repository test returns not found: verify both provider permission and the exact owner/repo parameter; GitHub may hide inaccessible private resources.
Repository hint did not block another repo: attach a Policy; hints alone do not enforce scope.
Actions-secret request denied: inspect the dangerous normalized action before changing Policy or provider permissions.

Use request evidence to separate APIZ denial from a GitHub status returned after the service was reached.

Current Limitations

Unknown or future REST paths may normalize to the coarser repository/fallback action rather than a new semantic resource.
The adapter does not create, refresh, or revoke GitHub tokens.
Provider repository scope and APIZ Policy are independent boundaries; use both when either one alone is broader than the task.