GitHub tools | answer.cloud Docs

GitHub tools connect a repository to a site for push-to-deploy. They require the appropriate plan and access to the selected organization's GitHub App installation. A repository can be linked to only one non-deleted site.

All tools accept organization_id when required. Use the exact site slug and the owner/name repository returned through the intended installation.

Connection and linking#

Tool	Required arguments	Optional arguments	Returns
`github_get_connection`	None beyond organization selection	—	Connection status, accessible repositories, linked-site information, and an `install_url` when available.
`github_link_repo`	`site_slug` string, `repo` string	`branch`, `dir`, `output_dir`, `build`, `workflow`	`site`, `repo`, `branch`, `dir`, `output_dir`, `build`, next steps; workflow when requested for Actions.
`github_get_workflow`	`site_slug` string	—	`path`, `content` for the generated workflow.
`github_trigger_deploy`	`site_slug`, `environment`	`ref` string	`site`, resolved `sha`, `status: queued`, `environment`, next steps.
`github_unlink_repo`	`site_slug` string	—	`site`, `github: null`, `unlinked: true`.

branch defaults to the repository's default branch. dir is the project folder, default /. output_dir is relative to that folder, default dist for Actions builds. build accepts actions or none. workflow defaults to true and controls whether link results include workflow content.

{
  "site_slug": "example-site",
  "repo": "example/company-website",
  "branch": "main",
  "dir": "/",
  "output_dir": "dist",
  "build": "actions",
  "workflow": true
}

Send this to github_link_repo after the installation can access the repository. Relinking is idempotent for the intended site and updates settings, but inspect the existing link before replacing its configuration.

Actions versus static mode#

With actions, commit the returned workflow at .github/workflows/answercloud.yml to the linked branch. The generated deployment uses GitHub OIDC; do not add a long-lived hosting secret as a substitute. Review the returned file and required workflow permissions rather than recreating an older example manually.

With none, the repository already contains built static output. A push to the linked branch queues a direct deployment; no application build runs on Answer Cloud. Use this only when the repository contents are the intended deploy artifact.

github_trigger_deploy supports none sites. ref can be a branch, tag, or SHA and defaults to the linked branch. Its required environment accepts staging, production, or both under the normal release rules. For Actions sites, push or re-run the workflow in GitHub instead; the trigger tool returns github_actions_build.

Automatic deployment commits#

Successful uploaded deployments also save public output to the linked branch automatically while GitHub is enabled. For none, the destination is dir; for actions, it is output_dir beneath dir. Saving follows publication and does not trigger another deployment. See automatic commits after uploads for saved files, commit history, and failure recovery.

Verify and recover#

Call github_get_connection. If disconnected, open the returned install URL, authorize the account and repositories, then read the connection again.
Link the repository and, for Actions, commit the exact workflow.
Make an authorized push or supported trigger.
Poll list_deploys for the resolved commit and inspect get_deploy once its ID appears.
Verify the returned live destination and a meaningful page/chat result.

github_not_connected requires installation setup; github_not_linked requires a site link. github_link_invalid can indicate an inaccessible repository or a repository already used by another site. An installation change may require browser reauthorization. Avoid creating another site to bypass the one-repository constraint.

Unlinking stops future push deployments and automatic deployment commits for that site while preserving the current live site and MCP deployments. Check the repository's workflow when retiring an Actions integration. See GitHub deployment guide, plan features, and deployment status.