# GitHub tools | answer.cloud Docs

> Canonical source: [GitHub tools | answer.cloud Docs](https://www.answer.cloud/docs/reference/github-tools/)

Connect GitHub, link a repository in Actions or static mode, inspect deployments and automatic commits, and recover or unlink the integration.

reference

GitHub tools

Connect GitHub, link a repository in Actions or static mode, inspect deployments and automatic commits, and recover or unlink the integration.

Reviewed November 1, 2026

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.

```json
{
  "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](https://www.answer.cloud/docs/hosting/github/#automatic-commits-after-uploads) for saved files, commit history, and failure recovery.

## Verify and recover

1. Call `github_get_connection`. If disconnected, open the returned install URL, authorize the account and repositories, then read the connection again.
2. Link the repository and, for Actions, commit the exact workflow.
3. Make an authorized push or supported trigger.
4. Poll `list_deploys` for the resolved commit and inspect `get_deploy` once its ID appears.
5. 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](https://www.answer.cloud/docs/hosting/github/), [plan features](https://www.answer.cloud/docs/account/plans/), and [deployment status](https://www.answer.cloud/docs/reference/deploy-tools/).