Connect GitHub

Guard connects to GitHub through a GitHub App installation. The installation supplies the account boundary and repository selection; Guard then verifies that the returned installation can access the repository before treating it as connected.

Before you start

You need permission to use or install the Enji Guard GitHub App for the target account or organization. If an organization owner must approve new applications, ask for that approval before creating the Guard project.

Decide which repositories the installation should expose. Prefer selected-repository access when Guard does not need every repository in the account. The repository picker can show several connected GitHub accounts, so know which personal account or organization owns the target.

Connect the GitHub App

1. Open New project, or open an existing project and choose Add a repository.
2. Choose GitHub as the source.
3. If no installation is available, select Connect your GitHub. GitHub opens in another tab so you can install the app or approve access.
4. Choose the personal account or organization that owns the repository.
5. Select the repositories the installation may expose, then return to Guard.
6. Wait for the connection tab to report Successfully connected with GitHub. It closes automatically after the confirmation delay, or you can close it yourself.

Guard preserves the in-progress project name, selected repositories, and optional website while the GitHub installation tab is open. When the original tab regains focus, it refreshes available installations and repository choices.

If GitHub returns without the expected installation details or cannot confirm repository access, Guard reports a connection error instead of silently marking the repository connected.

Select repositories

Choose the connected GitHub account, search the repository list, and select the repositories that belong to this project. Repositories already attached to the project appear separately and cannot be added a second time.

If the target is under another account, use Switch GitHub account. If the installation exists but does not include the repository, use Add GitHub repo or configure the installation in GitHub, then return and refresh the list.

For the first project, one repository is usually enough to understand the workflow. A project can contain more repositories when they form one product boundary; Projects, repositories, and websites explains how to choose that boundary.

Verify the connection

Complete project setup and open the resulting project or repository dashboard. A healthy connection has three observable results:

• the selected repository appears under the intended project;
• Guard can identify its provider path and current repository context;
• initial checks enter a queued, running, completed, or explicit error state.

For repository-specific connection flows, Guard verifies the installation against the saved repository. If verification fails, it marks the connection unavailable rather than continuing with assumed access.

If a repository is missing

Check these conditions in order:

1. Confirm that you selected the GitHub account or organization that owns the repository.
2. Open the GitHub App installation and confirm that the repository is included in its repository access.
3. If organization approval is pending, wait for an owner to approve the installation.
4. Return to Guard, focus the setup tab, and refresh or reopen the repository picker.
5. If the repository was renamed or transferred, verify the installation under its new owner.

Do not create a second project with a similarly named repository as a workaround. If a previously connected repository becomes unavailable, use Repository is unavailable.

Access boundary

The connection allows Guard to perform the workflows you later enable. Read-only audits do not change repository files. Code review may post comments, and a supported improvement may create an issue or a reviewable pull request. Guard does not merge the pull request automatically.

Review Provider and write matrix before enabling provider writes.