# Quickstart

> Go from an invite to a working Githome repository: passkey, CLI sign-in, first push, pull request, release and an AI agent over MCP.

Source: https://git.pkgforge.dev/docs/quickstart

This guide takes you from an invite link to a repository with code, a merged pull request, a first release and an AI agent connected over MCP. It takes about 15 minutes. Each step shows the web UI and, where it exists, the `githome` CLI and the REST API.

The examples use the organization `acme`, the repository `acme/website`, the user `diffy` and the agent `review-bot`, on githome at `https://git.pkgforge.dev`. Replace the names with your own.

## What you need

- An account on githome, which is invite-only: the superadmin makes the invite in the dash (`https://dash.git.pkgforge.dev`) and sends you the link by hand. githome sends no email for it, and open sign-up is off. Anyone can browse and clone public repositories without an account.
- A browser that supports passkeys (current Chrome, Safari, Edge or Firefox).
- Git 2.26 or newer (`git --version`).

## 1. Join with your invite and create a passkey

Githome has no passwords. You sign in to the web UI with a passkey, which your device, phone or password manager stores and unlocks with your fingerprint, face or screen lock.

1. Open the whole invite link that the superadmin sent you (`https://git.pkgforge.dev/invite/...#proof=...`). Invite links work for 14 days.
2. On **Join Githome**, check the **Username** (filled in from your email address) and optionally add a **Display name**. Your repositories will live at `https://git.pkgforge.dev/<username>/...`.
3. Click **Create a passkey and join** and complete your browser's prompt.

You are signed in, and you land on your dashboard. Next time, sign in at `https://git.pkgforge.dev/login` with **Sign in with a passkey**.

> **Note:** Add a second passkey on another device, or keep the passkey in a password manager that syncs, under **Settings → Passkeys and sessions**. See [Passkeys and sign-in](https://git.pkgforge.dev/docs/accounts/passkeys-and-sign-in).

## 2. Install the CLI and sign in

Install the `githome` command-line client. On Linux and macOS:

```sh
curl -fsSL https://git.pkgforge.dev/install | bash
```

On Windows, in PowerShell:

```powershell
powershell -c "irm https://git.pkgforge.dev/install.ps1 | iex"
```

The script puts the CLI in `~/.githome` and adds it to your `PATH`. The CLI needs Node.js 26 or later. The script uses yours when you have one, and otherwise installs a private copy of the Node.js 26 LTS from nodejs.org. See [Install and sign in to the CLI](https://git.pkgforge.dev/docs/accounts/cli-sign-in).

Sign in through your browser and let Git (and the GitHub CLI, if you have it) use the same sign-in:

```sh
githome setup            # opens git.pkgforge.dev; click Authorize
githome whoami           # prints diffy
```

`githome setup` runs `githome login`, then `githome auth setup-git`, so `git clone`, `fetch` and `push` to git.pkgforge.dev use the sign-in, and `githome auth setup-gh` when `gh` is installed. It adds no plugin to any editor or agent. You can run those steps yourself instead. The sign-in opens an **Authorize the Githome CLI** page showing your computer's name. Check it, keep **Write** access for this guide, and click **Authorize**. The terminal prints `✓ Logged in to https://git.pkgforge.dev as diffy`. No token to copy: the CLI gets its own, valid for 90 days and listed under **Settings → Access tokens**, and `githome logout` revokes it. On a machine without a browser (over SSH, for example), `githome setup` prints a code to enter at `https://git.pkgforge.dev/login/device` from any device instead.

Working in an editor? Clone with the plain HTTPS URL of the repository (`https://git.pkgforge.dev/<owner>/<repo>.git`), as in the steps below. See [Git over HTTPS](https://git.pkgforge.dev/docs/repositories/git).

## 3. Tokens for scripts

Scripts and plain Git without the CLI authenticate with a personal access token.

1. Go to **Settings → Access tokens** (`https://git.pkgforge.dev/settings/tokens`).
2. Under **Create a token**, enter a **Name** (for example `ci`), keep **Expires in (days)** at 90 (1 to 366), and pick a **Scope**:

   | Scope | Allows |
   | --- | --- |
   | **Read** | Clone, fetch and view only. Every change is refused (`this token needs the write scope`). |
   | **Write** (default) | Push, issues, pull requests, releases, runs and creating repositories (up to the maintain role). |
   | **Admin** | Everything you can do, including repository settings and secrets, and creating organizations, agents, invitations and other tokens. |

   Leave **Restrict to repositories** empty, or pick the repositories the script needs.
3. Click **Create token** and copy the token. It starts with `ghome_` and is shown only once.

Where the deployment sends email, Githome emails you whenever a token is created on your account, including by a CLI sign-in. See [Personal access tokens](https://git.pkgforge.dev/docs/accounts/tokens).

The `GITHOME_TOKEN` and `GITHOME_URL` environment variables give the CLI a token without signing in, which is handy in scripts; `githome login --token ghome_...` saves one. Without the CLI, Git asks for a username and password: enter any username and the token as the password.

## 4. Create a repository

Pick one of these.

**Web UI.** Click **+** in the header (or open `https://git.pkgforge.dev/new`). Choose the **Owner** (you or an organization such as `acme`), enter the **Repository name** `website`, an optional **Description**, the **Visibility** (**Private** is the default) and the **Default branch** (`main`). Click **Create repository**.

**CLI.**

```sh
githome repo create website --org acme --private -d "Marketing site"
```

**REST API.**

```sh
curl -X POST https://git.pkgforge.dev/api/v3/orgs/acme/repos \
  -H "Authorization: Bearer ghome_..." \
  -H "content-type: application/json" \
  -d '{"name": "website", "description": "Marketing site", "visibility": "private"}'
```

Leave out `--org acme` (or use `POST /api/v3/user/repos`) to create it in your own account. See [Repositories](https://git.pkgforge.dev/docs/repositories/overview).

## 5. Push your code

To bring over a repository that lives on GitHub, import it instead of pushing: `githome migrate github acme/website --local --to acme/website`. On git.pkgforge.dev the server-side import from GitHub (**Settings → Imports**) needs the import container, which is not running, so it stops at its Git step with "no import container is configured". The local import runs on your machine instead: it copies branches, tags, the default branch, variables and secret names (secret names only, never values), and with `--issues` also labels, issues, comments and open pull requests, created anew. Imports from GitLab, Forgejo, Gitea and Codeberg run on the server and copy the history, issues and pull requests with their numbers. See [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github).

From an existing project:

```sh
cd website
git remote add origin https://git.pkgforge.dev/acme/website.git
git push -u origin main
```

Or start from scratch:

```sh
mkdir website && cd website
echo "# website" > README.md
git init -b main
git add README.md
git commit -m "first commit"
git remote add origin https://git.pkgforge.dev/acme/website.git
git push -u origin main
```

Open `https://git.pkgforge.dev/acme/website` to see the files (with syntax highlighting) and the rendered README.

Every push is checked for leaked credentials, and so is every commit made in the web editor, through the REST API or over MCP. If you accidentally commit an API key or private key, the push is rejected with `Push blocked: possible secrets detected.` and nothing from it is stored: remove the secret from your commits and push again. See [Push protection](https://git.pkgforge.dev/docs/security/push-protection) and [Git over HTTPS](https://git.pkgforge.dev/docs/repositories/git).

## 6. Workflows

> The forge CI of git.pkgforge.dev is dormant: no run starts there now, so a workflow you push shows no run. Githome keeps the code that reads GitHub Actions workflows from `.github/workflows/`, and this step shows what such a file looks like. Do not expect a run, a log or a check from it on git.pkgforge.dev.

A workflow file looks like this:

```yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Show what we are building
        run: |
          echo "Event: ${{ github.event_name }}, commit: ${{ github.sha }}"
          ls -la
```

Pushing such a file starts no run on git.pkgforge.dev, and a workflow dispatch is refused with "CI is off on this deployment". Where the CI is on, a run reports a check named `CI / test` (workflow name, then job name) on the commit, which you can require in branch protection. Another CI system can report its results on the same commits as commit statuses or check runs through the GitHub-compatible REST API, and that works here; see [Checks and statuses](https://git.pkgforge.dev/docs/collaboration/checks-and-statuses). Where the CI is on, a run with a syntax error fails and shows the errors; `githome workflow validate` checks files before you push. See [Actions](https://git.pkgforge.dev/docs/actions/overview).

Each job gets a `GITHUB_TOKEN` that follows GitHub's `permissions:` model. In a new repository it can only read the code and packages (`contents: read`, `packages: read`), which is all the checkout above needs. A workflow that comments on pull requests, pushes or publishes releases has to ask for more, for example:

```yaml
permissions:
  contents: write
  pull-requests: write
```

A repository admin can also change the default. See [Workflow permissions](https://git.pkgforge.dev/docs/actions/workflow-permissions).

## 7. Open a pull request

Make a change on a branch and push it:

```sh
git switch -c update-readme
echo "Our marketing site." >> README.md
git commit -am "Describe the project"
git push -u origin update-readme
```

The push output includes a link: `Create a pull request for 'update-readme':` followed by the compare URL.

**Web UI.** Open that link (or the repository's **Pull requests** tab, then **New pull request**). On the compare page, fill in:

- **Title**,
- **Intent**: one or two sentences on what the change is meant to do, for human and AI reviewers,
- **Description** (Markdown),

then click **Create pull request**.

**CLI.**

```sh
githome pr create --title "Describe the project" \
  --intent "Add a one-line description of the site to the README." \
  --body "Small docs change."
```

Checks that other tools report appear on the pull request (no `pull_request` workflow runs here, because the forge CI is dormant). When nothing blocks it, merge it with **Merge pull request** (choose **Create a merge commit**, **Squash and merge** or **Rebase and merge (fast-forward)**), or:

```sh
githome pr merge 1 --squash --delete-branch
```

Teammates review with **Approve** or **Request changes** on the pull request, or `githome pr review 1 --approve`. You can't approve your own pull request. To require reviews and green checks before merging, add a rule under **Settings → Branch protection**. See [Pull requests](https://git.pkgforge.dev/docs/collaboration/pull-requests) and [Branch protection](https://git.pkgforge.dev/docs/repositories/branch-protection).

To skip the merge click from now on, open **Settings → Merge on green** once its checks have run: tick the checks and **Turn on auto-merge for pull requests I open**, and pull requests, yours and your agents', merge by themselves when the checks pass. See [Merge on green automatically](https://git.pkgforge.dev/docs/collaboration/merge-on-green).

## 8. Publish a release

A release turns a tag into a version people can download, with release notes and attached files.

**Web UI.** Open `https://git.pkgforge.dev/acme/website/releases` (or **Releases** in the sidebar of the repository page) and click **Draft a new release**. Under **Tag**, type a new tag such as `v0.1.0` (its **Target for a new tag** defaults to `main`), add a **Release title** and **Release notes**, optionally check **Generate release notes from merged pull requests (when the notes are empty)** and choose files under **Attach files**, then click **Publish release**. The release page also links to **Source code (zip)** and **Source code (tar.gz)** archives of the tag.

**REST API** (GitHub-compatible, so Octokit and similar tools work too):

```sh
curl -X POST https://git.pkgforge.dev/api/v3/repos/acme/website/releases \
  -H "Authorization: Bearer ghome_..." -H "content-type: application/json" \
  -d '{"tag_name": "v0.1.0", "name": "First release", "generate_release_notes": true}'
```

Publishing creates the tag if it doesn't exist. See [Releases](https://git.pkgforge.dev/docs/collaboration/releases).

To deploy from a workflow with its own secrets and branch rules, use an environment (`environment: production` on a job); see [Environments](https://git.pkgforge.dev/docs/actions/environments).

## 9. Connect an AI agent over MCP

Agents are separate accounts for AI tools. They act on behalf of the person or organization that owns them, never get more access than their owner, can't push or merge to the default branch or protected branches, and their pull requests always need a human approval.

### Create the agent

**Web UI.** Go to **Settings → Agents**. Under **Create an agent**, enter the **Agent username** `review-bot`, a **Display name**, the **Owner** (you or `acme`) and the **Maximum role** (keep **Write**). Click **Create agent**. Then open **Create a token for review-bot**, keep the defaults (**Scope** **Write**, 30 **Days**) and click **Create token**. Copy the token; it is shown once.

Tokens can't create agents or tokens, so create agents in the web UI under **Settings → Agents**, then create the agent's token in its row (**Create a token for**). The token is shown once. An agent owned by `acme` can work in every `acme` repository, up to its maximum role. Creating an organization agent needs the owner or admin role in the organization.

### Point your MCP client at Githome

Githome's MCP server is at `https://git.pkgforge.dev/mcp` (Streamable HTTP). Give the client the agent's token as a bearer token:

```json
{
  "mcpServers": {
    "githome": {
      "type": "http",
      "url": "https://git.pkgforge.dev/mcp",
      "headers": { "Authorization": "Bearer ghome_..." }
    }
  }
}
```

`githome mcp-config` prints this snippet with `${GITHOME_TOKEN}` in place of the token, which clients such as Claude Code expand from the environment. For Claude Code, save it as `.mcp.json` in your project and set `GITHOME_TOKEN` to the agent's token. Or sign in with OAuth: `claude mcp add --scope user --transport http githome https://git.pkgforge.dev/mcp` for Claude Code, and `codex mcp add githome --url https://git.pkgforge.dev/mcp` for Codex (add `--bearer-token-env-var GITHOME_TOKEN` to use a token).

Ask the agent something like "Use the githome tools: who am I, and what pull requests are open in acme/website?". It calls `whoami` and `list_pull_requests`. Agents can read and commit files without Git (`get_file`, `list_tree`, `commit_files`), open pull requests with an intent (`create_pull_request`), review, publish releases (`create_release`, `upload_release_asset`) and more. The tools that start work (a dispatch, a re-run, `sandbox_create`) are refused with "CI is off on this deployment" while the forge CI is dormant; the tools that read runs and logs (`list_workflow_runs`, `get_workflow_run`, `get_job_logs`) answer from stored data. See [MCP](https://git.pkgforge.dev/docs/agents/mcp) and the [MCP tool reference](https://git.pkgforge.dev/docs/reference/mcp-tools).

## Next steps

- [Concepts](https://git.pkgforge.dev/docs/concepts): accounts, roles, tokens, visibility, Actions and agents in one page.
- [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github): import a repository from GitLab, Forgejo, Gitea or Codeberg on the server, or from GitHub with a local import, then set its secrets again.
- [Merge on green automatically](https://git.pkgforge.dev/docs/collaboration/merge-on-green): pull requests merge by themselves once their checks pass.
- [Branch protection](https://git.pkgforge.dev/docs/repositories/branch-protection): require pull requests, reviews and checks, and [Checks and statuses](https://git.pkgforge.dev/docs/collaboration/checks-and-statuses) to report results from other CI systems.
- [Releases](https://git.pkgforge.dev/docs/collaboration/releases) and [Environments](https://git.pkgforge.dev/docs/actions/environments): ship versions and deploy them.
- [Organizations](https://git.pkgforge.dev/docs/accounts/organizations) and [Invitations](https://git.pkgforge.dev/docs/accounts/invitations): bring your team.
- [Secrets and variables](https://git.pkgforge.dev/docs/actions/secrets-and-variables): give workflows credentials.
- [Workflow syntax](https://git.pkgforge.dev/docs/actions/workflow-syntax) and [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility).
- [Agents](https://git.pkgforge.dev/docs/agents/overview) and [Sandboxes](https://git.pkgforge.dev/docs/agents/sandboxes): put AI agents to work safely.
- [REST API](https://git.pkgforge.dev/docs/reference/rest-api) and the [CLI reference](https://git.pkgforge.dev/docs/reference/cli).