Githome
Get started: Quickstart
Docs / Get started

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.

View as Markdown

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.

2. Install the CLI and sign in

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

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

On Windows, in 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.

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

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.

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:

    ScopeAllows
    ReadClone, 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).
    AdminEverything 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.

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.

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

REST API.

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.

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.

From an existing project:

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

Or start from scratch:

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 and Git over HTTPS.

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:

# .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. 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.

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:

permissions:
  contents: write
  pull-requests: write

A repository admin can also change the default. See Workflow permissions.

7. Open a pull request

Make a change on a branch and push it:

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.

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:

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 and 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.

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):

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.

To deploy from a workflow with its own secrets and branch rules, use an environment (environment: production on a job); see 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:

{
  "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 and the MCP tool reference.

Next steps