GitHub

Connect GitHub repositories, receive issue requests and review delivered work in pull requests.

Connect GitHub to receive issue requests, push cycle branches and review delivered work in a project pull request. Install the hlix GitHub App on your organization or account and select the repositories it can access.

Projects can also use a managed repository. Connect GitHub to use your team’s repositories and pull-request workflow.

Prerequisites

Agency owner or admin in the hlix Workspace
Permission to install a GitHub App on the target organization or account, or an organization owner who can approve the installation request
A repository you want hlix to work in

Connect it

Start the install. From the dashboard’s integrations screen, or directly:
Terminal window
```
curl -sS -i "$HLIX_BASE_URL/v1/api/integrations/github/install" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"
```
Expected result: a 302 to GitHub’s sign-in page. Open the redirect in a browser. If the app is already installed on an account you can access, signing in links that installation.
Choose the account and repositories, if prompted. GitHub offers all repositories or a selected list. You can update the selection in GitHub later.
Return to Hlix. The installation and its repository selection appear in your Workspace.

Expected result: a redirect to …/integrations?installed=1&provider=github. If an organization owner still has to approve, the flag is pending=1 instead. Connect again after they approve.

To connect another account, start the installation flow again.

Verify.

curl -sS "$HLIX_BASE_URL/v1/api/integrations/github" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

List the repositories available to the installation:

curl -sS "$HLIX_BASE_URL/v1/api/integrations/github/$INSTALL_ID/repositories" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

Expected result: the repositories you granted. Update the repository selection on GitHub if one is missing.

Open a repository from a link

Put hlix.ai/ in front of any GitHub repository link and it opens in hlix:

https://hlix.ai/github.com/<owner>/<repo>

After sign-in, New project opens with the repository and a suggested project name filled in. You can edit both and connect GitHub from that page when needed.

Use the full github.com/<owner>/<repo> form in published links. When typing, hlix.ai/<owner>/<repo> also works as a shortcut for most repository owners.

Open in Hlix badge

Add this to a README so readers can open the repository in hlix:

[![Open in Hlix](https://hlix.ai/badge.svg)](https://hlix.ai/github.com/<owner>/<repo>)

The branch model

hlix uses a project preview branch and a branch for each cycle.

main                                 yours. Human-gated.
└── preview-<prefix>-<project-slug>  ONE long-lived branch per project, cut from main once
    └── <prefix>/<cycle-title>-<id6>   one per cycle, cut from the preview branch

<prefix> is hlix unless your Workspace or the project chose another (branch prefix). main is the repository’s own default branch: when you attach a repository without naming one, hlix reads it from GitHub, and when you change it, hlix moves the open pull request onto the new branch.

One build agent run works on the cycle branch. A cycle that passes review lands on the project’s preview branch by fast-forward, and its cycle branch is deleted. The preview branch is therefore the accumulated, reviewed state of everything hlix has delivered for that project.

Project pull requests

For code delivery, hlix can open a project pull request from the preview branch to each contributing GitHub repository’s default branch, titled:

hlix.ai — <project name> · round <n>

The project’s pull request is reused for later deliveries in the same round. Merge it when you are satisfied; the next round cuts a fresh preview branch and opens the next one.

Reviewed changes accumulate in each repository’s preview branch. A project can have a preview-to-default-branch pull request for each contributing GitHub repository. Open Review to see the available pull requests; managed repositories use the dashboard’s merge action.

Issue sources

Newly opened issues in an attached repository are sent to the project manager through the GitHub source. Existing issue edits, label changes and issue comments do not submit new work. Disable issue sources per project or through Workspace defaults in Sources.

What hlix writes back

Write	When
A cycle branch off the preview branch	when the cycle starts; an existing branch is reused rather than duplicated
Commits on that branch	as the coding agent works, pushed about once a minute
A fast-forward of the preview branch to the cycle branch	when the cycle passes verification and review; the cycle branch is deleted
The project’s long-lived pull request	opened once, then updated by every later cycle

Hlix works in its project and cycle branches. You approve the final merge into your default branch.

Permissions and scopes

Inspect granted permissions and repositories on the installation record or GitHub’s installation settings. Update repository access on GitHub; Hlix picks up the new selection automatically. Restore a suspended installation on GitHub before using it again.

Disconnect

curl -sS -X POST "$HLIX_BASE_URL/v1/api/integrations/github/$INSTALL_ID/revoke" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

owner or admin only. This disconnects the installation in hlix. Uninstalling the app on GitHub is what removes hlix’s access on GitHub’s side — do both.

If GitHub does not connect

Authorization expired or failed: restart from Integrations → GitHub. Contact support if it continues.
Installation already connected elsewhere: disconnect it from the other Hlix Workspace or install the app on another GitHub account.
Installation pending: ask the GitHub organization owner to approve it, then connect again.
Installation suspended or removed: restore or reinstall it on GitHub, then reconnect.
Repository missing: grant it to the Hlix GitHub App in GitHub’s installation settings.
Base branch missing: confirm the project’s configured branch exists in that repository and the installation can access it.
A merge conflict with the preview branch. The cycle gets a checklist item, “Merge the preview and resolve conflicts”, and its next run resolves it on the cycle branch.
Ready to open a pull request: open the project’s Review page when its delivery is ready.