# Connect GitHub & GitLab

> Give your easyNode AI agent authenticated git access to GitHub, GitLab or self-hosted GitLab, clone repositories into the File Manager, and see every repo's branch, sync and working-tree state.

Applies to: easyClaw, easyHermes · Updated 2026-09-22


Connect **GitHub**, **GitLab** or a **self-hosted GitLab** to your easyNode appliance, and your AI agent can clone, pull and push your repositories. You don't paste credentials into chat and don't set up SSH keys. Clones live in the appliance's File Manager, and a **Repositories** view shows the state of every repository at a glance.

This works on both appliance types:

- **easyClaw**: connect from **Channels → GitHub** or **Channels → GitLab**.
- **easyHermes**: connect from **Settings → Git hosting**.

## What you get

- **Authenticated git for the agent.** After you connect, plain `git clone`, `git pull` and `git push` on the appliance work for that host. On easyClaw the GitHub CLI (`gh`) is signed in too, so the agent can open pull requests.
- **A github/ and gitlab/ tree in Files.** Repositories are cloned to `/srv/files/github/OWNER/REPO` and `/srv/files/gitlab/GROUP/PROJECT`, so you can browse, preview, download and share their files from the browser.
- **Repository state at a glance.** Branch, commits ahead and behind, uncommitted changes, last commit and last fetch for every repository on the box, including ones the agent cloned into its own workspace.
- **Safe updates.** Fetch and fast-forward-only Pull from the web UI, which never merge or overwrite local work.

## 1) Create an access token

Give the token only the access you want the agent to have.

### GitHub

1. Open [Settings → Developer settings → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new).
2. Under **Repository access**, choose the repositories the agent may use (or *All repositories*).
3. Under **Repository permissions**, set **Contents: Read and write** and **Metadata: Read**. Add **Pull requests: Read and write** if the agent should open PRs.
4. Set an expiry, generate the token and copy it. GitHub shows it only once.

A classic token with the `repo` scope also works, but fine-grained tokens can be limited to specific repositories.

### GitLab (gitlab.com or self-hosted)

1. Open **Preferences → Access Tokens** (`/-/user_settings/personal_access_tokens`).
2. Select **read_api** and **read_repository**. Add **write_repository** if the agent should push.
3. Create the token and copy it.

## 2) Connect it to your appliance

1. **easyClaw:** go to **Channels**, find the **GitHub** or **GitLab** card and click **Connect**.
   **easyHermes:** go to **Settings** and scroll to **Git hosting**.
2. For GitLab, enter your GitLab URL. Leave it as `https://gitlab.com` unless you run your own.
3. Paste the token and click **Verify & Connect**.

The appliance checks the token with GitHub or GitLab before saving it, then:

- stores it on the appliance only, readable by the service account alone
- configures git to use it for that host (your own `~/.git-credentials` is not touched)
- sets a git commit identity from your profile, only if none exists yet (on GitHub it uses your private `noreply` address)

To rotate an expiring token, connect again with the new one. **Disconnect** removes the token and leaves your clones in place.

## 3) Clone a repository

1. Open **Files** and click **Repositories** in the sidebar.
2. Click **+ Clone repository** and choose GitHub or GitLab.
3. Start typing: your repositories are suggested as you type. You can also paste `owner/repo` or a full https URL.
4. Optionally set a branch, or tick **Shallow clone** to fetch only the latest commit.
5. Click **Clone**. Progress is shown live, and when it finishes the File Manager opens the new folder.

Or just ask your agent. For example: *"Clone easydns/octodns and summarise the README."*

## 4) See the state of your repositories

**Files → Repositories** lists every git repository on the appliance, with:

- **Branch:** the checked-out branch, or *detached* at a commit
- **Sync:** commits ahead (↑) or behind (↓) the remote as of the last fetch, or *in sync*
- **Working tree:** staged, modified, untracked and conflicted file counts, or *clean*
- **Last commit:** short hash, message, author and age
- **Fetched:** when the appliance last talked to the remote

Browsing into a repository folder shows the same summary above the file list, with **Fetch** and **Pull** buttons. **Fetch** downloads new commits without touching your files. **Pull** only fast-forwards: if the branch has diverged it stops, so nothing local is ever lost.

## Security

- Tokens never leave your appliance and are never shown again after saving.
- Connecting, disconnecting and Pull from the web UI require the admin login.
- Use fine-grained tokens scoped to the repositories the agent needs. Revoking the token on GitHub or GitLab cuts off access immediately.
- easyClaw's agent is instructed never to force-push or rewrite published history unless you explicitly ask.

## Troubleshooting

- **"rejected the token (401)":** the token is wrong, expired or was cut off when copying. Create a new one.
- **Push fails with 403 / "Permission denied":** the token is read-only. Add *Contents: Read and write* (GitHub) or *write_repository* (GitLab).
- **"Repository not found" on a private repo:** the fine-grained token doesn't include that repository. Edit its repository access.
- **An SSH (`git@…`) remote can't pull or push:** the token covers https only. Run `git remote set-url origin https://github.com/OWNER/REPO.git`.
- **"Not possible to fast-forward":** the branch has diverged from the remote. Ask your agent to rebase or merge.
- **Self-hosted GitLab URL rejected:** it must start with `https://`. Enter it as you open it in a browser, including any path prefix.


## Frequently asked questions

### Where is my GitHub or GitLab token stored?

Only on your appliance, in a file readable by the service account alone. It is never displayed again after you save it, it is removed from remote URLs and error messages, and it is never sent to easyNode.

### Can my AI agent push to my repositories?

Only if the token allows it. Grant Contents: Read and write on GitHub or write_repository on GitLab for pushes. For read-only access, give the token read permissions only.

### Does it work with a self-hosted GitLab?

Yes. Enter your GitLab's https URL, including any path prefix such as https://example.com/gitlab, when you connect.

### Will Pull overwrite my local changes?

No. Pull from the web UI is fast-forward only. If the branch has local commits the remote does not have, it stops with an error instead of merging or overwriting anything.

### Why can't a repository cloned over SSH pull or push?

The stored token covers https remotes only. Switch the remote with git remote set-url origin https://github.com/OWNER/REPO.git.

### What happens when I disconnect?

The token is removed from the appliance and git loses authenticated access to that host. Repositories you already cloned stay in place in Files.

---
_Canonical: https://easynode.ai/docs/git/_