Skip to content
ArchFoundry Docs Open the canvas

Connect a GitHub or GitLab repository

Updated October 19, 2026Plans: Free, Pro, Enterprise

Overview

A connected repository is where Archie reads your code, where your Terraform is committed, and whose pull requests ArchFoundry can review. GitHub connects through the ArchFoundry GitHub App, which leaves no token with ArchFoundry. GitLab connects by signing in to GitLab. Self-hosted GitLab and GitHub Enterprise connect with an access token.

Prerequisites

  • An owner or admin role in your ArchFoundry organization to connect or disconnect a repository, or to open a pull request from ArchFoundry. Any member can read a connected repository.
  • On GitHub, permission to install an app on the account or organization that owns the repository. A member of an organization can ask an owner to approve it.
  • On GitLab, a role of at least Developer on the project.

Steps

  1. In the workspace sidebar, click Repositories. On the canvas, the command palette's Connect a Git repository (GitHub or GitLab) opens the same form.
  2. For GitHub, click Connect GitHub. On GitHub, choose the account, pick Only select repositories and the ones ArchFoundry may use, and install. GitHub sends you back to ArchFoundry.
  3. For GitLab, click Connect GitLab, sign in to GitLab, and choose the projects.
  4. For self-hosted GitLab, GitHub Enterprise or a token, open the line under the buttons that ends or an access token. Paste the page you were looking at into Repository, paste a token into Access token, and click Connect.
  5. The repository appears under Connected, with its host, default branch, how it is connected, and whether it is read only or read and write.

To add or remove GitHub repositories later, click Change repositories. It opens the app's page on GitHub.

Example

When you connect with a token, the repository field takes a URL like this one:

text
https://github.com/<your-org>/<your-repository>

Change <your-org> and <your-repository> to the owner and name on your host. A fine-grained GitHub token needs these permissions, and nothing broader:

text
Contents: Read and write        read files and history, and write the commits you make here
Metadata: Read-only             required by GitHub alongside Contents
Pull requests: Read and write   only if you want the Open a pull request button
Workflows: Read and write       lets Builds on push commit its file to .github/workflows/

A GitLab token needs the api scope and the Developer role. A token carrying delete_repo, admin:org, admin:enterprise, write:org, user, or GitLab's sudo or admin_mode is refused before it is stored.

Verify it worked

  • The row under Connected reads via GitHub, no token held, via GitLab sign-in, nothing pasted, or token followed by its last characters.
  • A token is sealed with AES-256-GCM before it is stored, never shown again, and used only when you ask.

Troubleshooting

That looks like an access token, not a repository URL. You pasted the token into Repository. It goes in Access token.

That is not a repository URL. It needs a host, an owner and a name. Paste the address of the repository's page, not of a file or the host alone.

Only an owner or admin can change repository connections. Ask an owner or admin of your organization to connect it.

GitHub is waiting for an owner of that organization to approve ArchFoundry. A member asked an organization owner to approve the install on GitHub. Once they approve, click Connect GitHub again.

You were signed out while connecting GitHub, so nothing was connected. Log in, then click Connect GitHub again. The same applies to GitLab.

Connecting a repository is not enabled on this server yet. You reached a server without repository connections switched on. Make sure you are on app.archfoundry.ai.

Removing a repository. Click Disconnect on its row. For the GitHub App, also remove the repository on GitHub with Change repositories.

Next steps