# Githome > Githome is a private, GitHub-compatible Git forge at git.pkgforge.dev: repositories, pull requests, issues and an MCP server for AI agents, on Cloudflare. Accounts are by invitation. This file holds what Githome is (the home page, the product, FAQ and company pages), then the essential pages of the docs: Overview, Quickstart, Concepts, Guides, Move your GitHub Actions workflows to Githome, Make your CI faster on Githome, Give an AI coding agent its own account, with guardrails, Compatibility with GitHub Actions, Connect AI apps. Every docs page, including the API reference: https://git.pkgforge.dev/llms-full.txt. The index of everything: https://git.pkgforge.dev/llms.txt --- # Githome > Githome at git.pkgforge.dev: a private, GitHub-compatible forge on Cloudflare, with gh, an MCP server for AI agents and push mirrors. Accounts by invitation. Source: https://git.pkgforge.dev/ (last updated 2026-11-12) ## A private, GitHub-compatible forge for people and AI agents Githome is the internal forge at git.pkgforge.dev: Git repositories, pull requests, issues and releases behind GitHub-compatible REST and GraphQL APIs, an MCP server, the githome CLI and gh for agents, and push mirrors that copy each repository with its forge state. It runs on Cloudflare. Accounts are by invitation, and public repositories are open to read. - **Invite only**: The superadmin invites each account. Anyone can browse and clone public repositories. - **gh**: works as it does with GitHub Enterprise, through the GitHub-compatible REST and GraphQL APIs. - **/mcp**: The MCP server for Claude, Claude Code, Codex and any MCP client, with a browser sign-in or a token. - **1 person**: approves an agent's pull request before it merges, enforced by the server, unless a repository waives it. ## What you get - **[Git hosting](https://git.pkgforge.dev/docs/repositories/git)**: Clone, fetch and push over HTTPS with Git LFS. Every repository is its own strongly consistent store, and pushes that leak a credential are refused. - **[Pull requests with intent](https://git.pkgforge.dev/docs/collaboration/pull-requests)**: Reviews, required approvals and checks, auto-merge and a merge queue. Each pull request says what it's meant to do, so reviewers check the right thing. - **[GitHub-compatible APIs](https://git.pkgforge.dev/docs/reference/rest-api)**: REST and GraphQL APIs that follow GitHub's, so gh, Git and GitHub API clients work with git.pkgforge.dev as they do with GitHub Enterprise. - **[Push mirrors](https://git.pkgforge.dev/docs/self-hosting/deploy#mirrors-and-backups)**: Each repository is pushed with its forge state (refs/githome/meta) to GitHub, Cloudflare Artifacts, GitLab, Forgejo or Codeberg, and backups go to a bucket off Cloudflare once its credentials are set. - **[AI agents with guardrails](https://git.pkgforge.dev/agents)**: Agents get their own accounts and tokens and work through the MCP server, the githome CLI and gh. They can't push to protected branches, and a person approves their pull requests. - **[Secure by default](https://git.pkgforge.dev/security)**: Passkeys instead of passwords, accounts by invitation, encrypted secrets, scoped tokens and an append-only audit log. ## Built for AI coding agents Claude Code, Codex and other agents work through Git, the GitHub CLI, the REST API or the built-in MCP server, as accounts of their own, and the server keeps a person in charge of what lands. Githome includes no model access. Agent tasks, agent review, sandboxes and browser terminals need the forge CI, which is dormant on git.pkgforge.dev. - **[Agent accounts with guardrails](https://git.pkgforge.dev/docs/agents/overview#guardrails)**: Each agent has its own login and tokens, owned by a person or an organization. It can't push to protected branches or manage secrets, and a person approves its pull requests. - **[An MCP server](https://git.pkgforge.dev/docs/agents/mcp)**: Claude, Claude Code, Codex and any MCP client read and change code, pull requests, issues and releases, and search the docs, at /mcp. - **[Cloud agents](https://git.pkgforge.dev/docs/connect/cloud-agents)**: A repository's Agent setup gives a cloud agent, such as a Claude Code cloud environment or Codex in the cloud, a token limited to that repository and a setup script. - **[Today and Needs you](https://git.pkgforge.dev/docs/agents/today)**: One page each morning: what needs you, what your agents are working on, and what changed since yesterday, across every repository. - **[Merge on green](https://git.pkgforge.dev/docs/collaboration/merge-on-green)**: Pull requests merge by themselves once their checks pass, with or without a person's approval, as you choose. An agent's change to a workflow file still needs a person to merge it. - **[Docs written for agents](https://git.pkgforge.dev/docs/agents/docs-for-agents)**: Every docs page is also Markdown, with llms.txt and llms-full.txt, and the MCP server searches and reads the docs. ## Works where you and your agents already work - **[Claude Code](https://git.pkgforge.dev/docs/connect/claude-code)**: Add the MCP server once for every project, then run /mcp in Claude Code to sign in through the browser. `claude mcp add --scope user --transport http githome https://git.pkgforge.dev/mcp` - **[Codex](https://git.pkgforge.dev/docs/connect/codex)**: The same MCP server for OpenAI's Codex CLI, with a browser sign-in, or a token with --bearer-token-env-var GITHOME_TOKEN. `codex mcp add githome --url https://git.pkgforge.dev/mcp` - **[Claude and other MCP clients](https://git.pkgforge.dev/docs/connect/claude)**: Add the server URL to Claude as a connector, or to Cursor or any other MCP client, and sign in through the browser. `https://git.pkgforge.dev/mcp` - **[The githome CLI](https://git.pkgforge.dev/docs/accounts/cli-sign-in)**: Signs in through the browser and sets up git and gh in one command. It needs Node.js 26 or later, and the script installs a private copy when the machine has no Node.js 26. `curl -fsSL https://git.pkgforge.dev/install | bash` - **[gh, the GitHub CLI](https://git.pkgforge.dev/docs/agents/github-cli)**: Pull requests, issues, releases and gh api work as they do with GitHub Enterprise, so agents use the commands they know. `githome auth setup-gh` - **[Git and your editor](https://git.pkgforge.dev/docs/repositories/git)**: Any editor clones, pulls and pushes with the plain HTTPS URL of a repository. `git clone https://git.pkgforge.dev/OWNER/REPO.git` ## gh and Git, as you use them with GitHub Githome's REST and GraphQL APIs follow GitHub's, so gh talks to git.pkgforge.dev the way it talks to a GitHub Enterprise Server, and Git works over HTTPS with Git LFS. `githome setup` signs in through the browser and sets up git and gh. ```sh curl -fsSL https://git.pkgforge.dev/install | bash githome setup # sign in, set up git and gh git clone https://git.pkgforge.dev/OWNER/REPO.git cd REPO gh pr create --title "Fix the parser" --draft gh pr merge --auto --squash ``` The forge CI of git.pkgforge.dev is dormant: an event starts no workflow run, and a dispatch is refused with "CI is off on this deployment". External CI and bots report check runs and commit statuses through the API, and branch protection can require them. ## Accounts by invitation, public read Anyone can browse and clone public repositories without an account. A write needs an account: the superadmin creates or invites each one and sends the one-time invitation link by hand. Open sign-up is off, and people sign in with a passkey. Bugs and questions go to the public tracker [Azathothas/issues](https://github.com/Azathothas/issues) with the label `git.pkgforge.dev`. ## Frequently asked questions ### What is Githome? Githome is the private, internal forge at git.pkgforge.dev. It hosts Git repositories, pull requests, issues and releases behind REST and GraphQL APIs that follow GitHub's, so Git, gh and AI agents work with it as they do with GitHub. It runs on Cloudflare. It is not a product for sale: there is no price, no plan and no hosted service to sign up for. ### Who can use git.pkgforge.dev? Anyone can browse and clone its public repositories without an account. A write needs an account, and accounts are by invitation: the superadmin invites each one and sends the one-time invitation link by hand. Open sign-up is off. People sign in with a passkey, and someone who lost their passkeys asks the superadmin for a sign-in link. See [Invitations](https://git.pkgforge.dev/docs/accounts/invitations). ### Does Githome work like GitHub? For Git, pull requests, issues and releases, yes: Git works over HTTPS with Git LFS, and gh talks to git.pkgforge.dev the way it talks to a GitHub Enterprise Server. Branch protection, required reviews and checks apply to gh as they do on the web. See [GitHub CLI and Claude Code](https://git.pkgforge.dev/docs/agents/github-cli) and the [REST API](https://git.pkgforge.dev/docs/reference/rest-api). ### Do GitHub Actions workflows run on git.pkgforge.dev? No. The Actions code is in Githome and reads `.github/workflows` with GitHub's syntax, but the forge CI of git.pkgforge.dev is dormant: an event starts no run, and a dispatch is refused with "CI is off on this deployment". External CI and bots still report check runs and commit statuses through the API, and branch protection can require them. See [Checks and statuses](https://git.pkgforge.dev/docs/collaboration/checks-and-statuses). ### Is Githome built on Cloudflare? Yes. One Cloudflare Worker serves the site, the API, Git and the MCP server; each repository is its own Durable Object, with large objects in R2 and accounts in D1; Queues and Workflows drive webhooks, email and background work. No Cloudflare Container runs, because the forge CI is dormant. See [Built on Cloudflare](https://git.pkgforge.dev/built-on-cloudflare). ### How does Githome work with Claude Code, Codex and other AI agents? Agents connect to the MCP server at `https://git.pkgforge.dev/mcp` with a browser sign-in or a token, or use Git, gh and the REST API with an agent token. Claude Code: `claude mcp add --scope user --transport http githome https://git.pkgforge.dev/mcp`. Codex: `codex mcp add githome --url https://git.pkgforge.dev/mcp`. Each agent is an account of its own: it can't push to protected branches, and its pull requests need a person's approval. See [Githome for AI agents](https://git.pkgforge.dev/agents). ### Is there a copy of the repositories outside Cloudflare? Yes. Push mirrors copy each repository with its forge state (`refs/githome/meta`) to GitHub, GitLab, Forgejo or Codeberg, and encrypted backups go to an S3-compatible bucket off Cloudflare once its credentials are set. A mirror to Cloudflare Artifacts stays inside Cloudflare. See [Mirrors and backups](https://git.pkgforge.dev/docs/self-hosting/deploy#mirrors-and-backups). ### How do I move a repository from GitHub? Githome's importer copies a repository from GitLab, Forgejo, Gitea or Codeberg on the server, with history, issues, pull requests, reviews, releases and branch protection, keeping their numbers. The server-side import from GitHub needs the import container, which git.pkgforge.dev does not run, so it stops at its Git step with "no import container is configured"; a local import (`githome migrate github --local`) or a GitHub pull mirror brings a GitHub repository in. See [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github). ### Where do I report a bug or ask a question? In the public tracker [Azathothas/issues](https://github.com/Azathothas/issues), with the label `git.pkgforge.dev`. People with an account can report a security problem privately with the [security report form](https://git.pkgforge.dev/security/report); until the deployment has its Turnstile keys, the contact and report forms take messages only from people who are signed in. --- # Git hosting, pull requests and GitHub Actions–compatible CI in one place > What Githome does: Git hosting, pull requests and a merge queue, GitHub Actions–compatible CI (dormant here), a container registry and AI agents. Source: https://git.pkgforge.dev/features (last updated 2026-11-12) Githome is a git forge for teams of people and AI agents. It hosts your repositories, reviews and CI in one place, reads GitHub Actions workflows as they are, and treats AI coding agents as accounts with their own tokens and guardrails. It runs on Cloudflare, with no servers to manage and with copies kept off Cloudflare. This instance is one private forge at git.pkgforge.dev: accounts are by invitation from the superadmin, and anyone can browse and clone public repositories without an account. This page lists what Githome does today, what it doesn't do yet, and where each feature is documented. ## Git hosting - **Clone, fetch and push over HTTPS** with a token or a browser sign-in from the CLI. Shallow clones, Git LFS, tags and `refs/pull//head` and `/merge` work as on GitHub. See [Git over HTTPS](https://git.pkgforge.dev/docs/repositories/git). - **Every repository is its own strongly consistent store.** Each repository is a Cloudflare Durable Object with its own SQLite database, so one busy repository never slows another. - **Push protection on by default.** Every push, and every commit made through the web editor, the API or MCP, is scanned for leaked credentials, and a push that contains one is refused with nothing kept. See [Push protection](https://git.pkgforge.dev/docs/security/push-protection). - **Branch protection** with required pull requests, approvals, required checks, linear history, merge queues and rules for agents. See [Branch protection](https://git.pkgforge.dev/docs/repositories/branch-protection). - **Browse code** in the web UI with highlighted files and diffs, history, branches and tags, a command palette and an in-browser editor. See [Browsing code](https://git.pkgforge.dev/docs/repositories/browsing-code). - **Push mirrors** copy each repository with its forge state to GitHub, Cloudflare Artifacts, GitLab, Forgejo or Codeberg. Backups go to an S3-compatible bucket off Cloudflare once its credentials are set. ## Pull requests, reviews and issues - **Pull requests with intent.** Every pull request can say what the change is meant to do, so human and AI reviewers check the right thing. Drafts, reviews with line comments, required approvals and checks, and merge, squash or rebase. See [Pull requests](https://git.pkgforge.dev/docs/collaboration/pull-requests). - **Auto-merge and a merge queue.** Pull requests land on their own once they're approved and green, and a merge queue tests each one on top of the base branch and the pull requests ahead of it, with the same `merge_group` event and `gh-readonly-queue/` branches as GitHub. See [Merge queue](https://git.pkgforge.dev/docs/collaboration/merge-queue). - **Issues** with labels, assignees, milestones, reactions, locking and search. See [Issues](https://git.pkgforge.dev/docs/collaboration/issues). - **Releases** with notes and downloadable files, following GitHub's model and REST API. See [Releases](https://git.pkgforge.dev/docs/collaboration/releases). - **Checks and commit statuses** from Githome Actions, external CI and bots. See [Checks and commit statuses](https://git.pkgforge.dev/docs/collaboration/checks-and-statuses). ## Actions: CI that reads your GitHub workflows The Actions code is part of Githome, and the forge CI of git.pkgforge.dev is dormant: no workflow runs there now, an event starts no run, and a dispatch is refused with "CI is off on this deployment". The pages below are the reference for the workflow syntax Githome reads. - **Drop-in for GitHub Actions.** Githome reads `.github/workflows/*.yml` with the same triggers, expressions, matrices, `needs`, outputs, reusable workflows, environments, secrets, variables, OIDC, service containers and Docker. JavaScript, composite and Docker actions from GitHub are meant to run as they do there. See [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility), which lists every difference. - **Built-in actions.** `actions/checkout`, `setup-node`, `setup-python`, `setup-go`, `cache`, `upload-artifact` and `download-artifact` are built into the runner, sharing storage and formats with the official actions. - **Self-hosted runners** for macOS, Windows, Arm, GPUs or machines on your own network, with `githome runner`. See [Self-hosted runners](https://git.pkgforge.dev/docs/actions/runners#self-hosted-runners). - **Caches and artifacts** with the official `actions/cache` and `upload-artifact` formats. See [Caching and artifacts](https://git.pkgforge.dev/docs/actions/caching-and-artifacts). ## Container registry Push and pull images at `git.pkgforge.dev//` with `docker`, `podman`, `buildx`, `crane` or the `docker/*` actions, instead of ghcr.io. Images are private by default and can be linked to a repository whose collaborators then share access. See [Container registry](https://git.pkgforge.dev/docs/packages/container-registry). ## Built for AI agents - **Agents are accounts.** Each AI agent gets its own login and tokens, acts for a person or an organization, and is held to guardrails: unless a branch protection rule allows it, an agent can't push to or merge into protected branches, its pull requests need a person's approval, its check results never count as required checks, and runs of code it pushed get no secrets. See [Guardrails](https://git.pkgforge.dev/docs/agents/overview#guardrails). - **Today and Needs you.** One page, the first after you sign in, with what needs you, what your agents are working on and what merged or failed since yesterday, also as the `today` MCP tool. See [Today](https://git.pkgforge.dev/docs/agents/today). - **Merge on green.** Pull requests, agents' included, merge by themselves once their checks pass and their branch's rules are met. See [Merge on green](https://git.pkgforge.dev/docs/collaboration/merge-on-green). - **An MCP server** at `https://git.pkgforge.dev/mcp`, with OAuth sign-in or an agent token. See [Connect AI apps](https://git.pkgforge.dev/docs/connect). - **Agent tasks, agent review, terminals, projects and sandboxes** run an agent for you in a sandbox: Claude Code, Codex or your own command with your own model key opens a pull request, and another agent reviews pull requests. They are part of the code and dormant on git.pkgforge.dev, because they need the forge CI. See [Agent tasks](https://git.pkgforge.dev/docs/agents/tasks), [Agent review](https://git.pkgforge.dev/docs/agents/review), [Terminals](https://git.pkgforge.dev/docs/agents/terminal), [Projects](https://git.pkgforge.dev/docs/agents/projects) and [Sandboxes](https://git.pkgforge.dev/docs/agents/sandboxes). ![The Today page on Githome: what needs you, the agent pull requests at work, your agent tasks and what changed since yesterday](https://git.pkgforge.dev/docs/images/today.webp) See [Githome for AI agents](https://git.pkgforge.dev/agents) for the whole picture. ## Works with the tools you already use | Tool | How it works with Githome | | --- | --- | | `git` | Standard Git over HTTPS. `githome auth setup-git` signs git in through the browser. Editors clone with the plain HTTPS URL; Githome ships no editor extension. | | GitHub CLI (`gh`) | Works as with GitHub Enterprise Server, through Githome's GitHub-compatible REST and GraphQL APIs. See [Use gh](https://git.pkgforge.dev/docs/agents/github-cli). | | Claude Code | The MCP server, added with `claude mcp add --scope user --transport http githome https://git.pkgforge.dev/mcp`. See [Claude Code](https://git.pkgforge.dev/docs/connect/claude-code). | | Codex | The MCP server, added with `codex mcp add githome --url https://git.pkgforge.dev/mcp`. See [Codex](https://git.pkgforge.dev/docs/connect/codex). | | Claude, Cursor and other MCP clients | The MCP server at `/mcp` with a browser sign-in. See [Connect AI apps](https://git.pkgforge.dev/docs/connect). | | Scripts and integrations | A GitHub-style REST API at `/api/v3`, described as [OpenAPI 3.1](https://git.pkgforge.dev/docs/api/openapi.json), and GitHub-compatible [webhooks](https://git.pkgforge.dev/docs/repositories/webhooks). | | The `githome` CLI | Repositories, pull requests, issues, runs, secrets, runners and migrations from a terminal. It needs Node.js 26 or later. See the [CLI reference](https://git.pkgforge.dev/docs/reference/cli). | ## Moving from GitHub A server-side importer brings over a GitLab, Forgejo, Gitea or Codeberg repository with its full Git history, issues, pull requests, reviews, comments, labels, milestones, releases and branch protection, keeping issue and pull request numbers. The server-side import from GitHub needs the import container, which git.pkgforge.dev does not run, so it stops at its Git step with "no import container is configured". To bring in a GitHub repository, use the local import (`githome migrate github --local`) or a GitHub pull mirror. See [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github). ## Security Passkeys instead of passwords, invite-only accounts, branch and push protection, envelope-encrypted secrets, job tokens limited by `permissions:`, signed webhooks and an append-only audit log. See [Security](https://git.pkgforge.dev/security). ## How it runs The service runs on Cloudflare: a Worker serves the web UI, Git, the REST API and MCP; each repository is a Durable Object with SQLite; large objects, caches, artifacts and images live in R2; accounts live in D1; and workflow runs are durable Cloudflare Workflows. The superadmin console is a separate site, `dash.git.pkgforge.dev`, with its own passkey sign-in. See [Built on Cloudflare](https://git.pkgforge.dev/built-on-cloudflare). ## What Githome doesn't do yet Githome is young, and we'd rather you know its limits: - **No forge CI on git.pkgforge.dev.** The Actions code is in Githome and dormant on this host, so no workflow, hosted job, sandbox, task or terminal runs here now. - **HTTPS only for Git.** There's no SSH access. - **No discussions, GitHub Pages-style sites, Codespaces-style cloud editors or app marketplace.** - **No hosted service.** git.pkgforge.dev is one private forge: there is nothing to sign up for, and accounts are made by invitation. --- # Git hosting and CI built for AI coding agents > AI agents get accounts with guardrails, an MCP server, gh and the CLI, Today and merge on green. People decide what lands. Source: https://git.pkgforge.dev/agents (last updated 2026-11-12) Coding agents such as Claude Code and Codex now write a large share of many teams' pull requests. Githome is a git forge designed for that: agents work through the same Git, REST API and MCP server as people, but as accounts of their own, with limits the server enforces, so a person stays in charge of what reaches the main branch. This instance is one private forge at git.pkgforge.dev; accounts are by invitation from the superadmin. Githome has more for agents than accounts: open **Today** in the morning to see what needs you, approve, and let a pull request merge on green. An MCP server, the `githome` CLI and `gh` bring it into the tools you already use. Agent tasks, agent review and sandboxes, which run an agent for you, are part of the code and dormant on git.pkgforge.dev: the forge CI of this host is off, so no sandbox, task or terminal starts here now. | What | In one line | | --- | --- | | [Agent accounts](https://git.pkgforge.dev/agents#agents-are-accounts-not-borrowed-tokens) | Their own logins and tokens, owned by a person or an organization | | [Guardrails](https://git.pkgforge.dev/agents#guardrails-the-server-enforces) | No pushes to protected branches, a person approves, no secrets for agent code | | [Agent tasks](https://git.pkgforge.dev/agents#agent-tasks-a-goal-in-a-pull-request-out) | A goal in, a pull request out, with Claude Code or Codex in a sandbox (dormant here) | | [Agent review](https://git.pkgforge.dev/agents#agent-review-on-every-pull-request) | Inline findings and an Agent review check on every pull request (dormant here) | | [Today and Needs you](https://git.pkgforge.dev/agents#today-what-needs-you) | What needs you and what your agents did since yesterday | | [Merge on green](https://git.pkgforge.dev/agents#merge-on-green) | Agent pull requests land when their checks pass, after a person approves if you want that | | [Integrations](https://git.pkgforge.dev/agents#integrations) | Claude Code, Codex, MCP, the CLI and gh | ## Agents are accounts, not borrowed tokens On most forges an agent acts with a person's token, so its work is indistinguishable from theirs and it can do anything they can. On Githome: - **Each agent has its own login and tokens**, owned by a person or an organization. Every commit it makes is stamped with who it acts for. - **Its role is capped** by a maximum role (write by default) and by its owner's own role. - **It can't sign in to the web UI.** Agents use tokens over Git, the REST API, the CLI and MCP; only people have passkeys and browser sessions. See [Agents](https://git.pkgforge.dev/docs/agents/overview). ## Guardrails the server enforces These hold for Git pushes, the REST API, MCP tools and sandboxes alike: | Rule | What it means | | --- | --- | | No pushes to protected branches | Agents open pull requests instead. A branch protection rule can allow it. | | A person approves agent pull requests | At least one approval from a person, even on a branch with no rule. An agent's approval never counts. | | No merging protected branches | Unless a rule allows agents to merge, or to land through auto-merge once CI and a person agree. | | Agent check results never satisfy required checks | An agent can't report its own CI as green. | | No secrets for agent code | A workflow run of code an agent pushed gets only its job token, so an agent can't push a workflow that sends your secrets elsewhere. | | No secret, variable, environment or branch protection changes | Whatever the agent's role. | | No push protection bypass | A credential in an agent's push is always refused. | The full list is in [Guardrails](https://git.pkgforge.dev/docs/agents/overview#guardrails). ## An MCP server for every AI app Githome runs a Model Context Protocol server at `https://git.pkgforge.dev/mcp`. Claude (claude.ai, Desktop and mobile), Claude Code, Codex, Cursor, VS Code and other MCP clients sign in through the browser with OAuth 2.1, or headless with an agent token. Its tools read code, commit files, open, review and merge pull requests, publish releases, import from GitHub and search these docs, all through the same permission checks and guardrails as Git and the REST API. - [Connect AI apps](https://git.pkgforge.dev/docs/connect): one URL and a browser sign-in for Claude, Claude Code, Codex and others. - [MCP tool reference](https://git.pkgforge.dev/docs/reference/mcp-tools): every tool and its arguments, generated from the server. ## gh, Git and the REST API work as agents expect Agents trained on GitHub already know how to use Githome. The GitHub CLI works with Githome as it does with GitHub Enterprise Server (`githome auth setup-gh` signs it in), so `gh pr create` and `gh pr merge` just work, and Claude Code shows the pull request of the branch it's on. The REST API follows GitHub's at `/api/v3`, with a GraphQL endpoint for the queries `gh` makes. See [Use gh with Githome](https://git.pkgforge.dev/docs/agents/github-cli). ## Sandboxes: a machine for every agent A [sandbox](https://git.pkgforge.dev/docs/agents/sandboxes) is a short-lived Linux container with the repository already cloned, driven over MCP or the REST API: run commands, read and write files, build, test and push. Sandboxes are dormant on git.pkgforge.dev with the rest of the forge CI; a request to start one is refused with "CI is off on this deployment". ## Agent tasks: a goal in, a pull request out Give one of your agents a goal. On a deployment where CI is on, Githome starts a sandbox as that agent with the repository checked out, runs Claude Code, Codex or your own command with your own model key, streams its transcript to the task page, then pushes a branch and opens a pull request for a person to review. Your API key never enters the sandbox: each run gets a token that only Githome's model proxy accepts. A task can **plan first** and wait for your approval, run up to four **attempts** side by side for you to pick from, and **verify and land**. On git.pkgforge.dev tasks are dormant. ![An agent task on Githome: the goal, Claude Code running as the acme-coder agent, its transcript with file edits and test runs, and the pull request it opened](https://git.pkgforge.dev/docs/images/agent-task.webp) A [terminal](https://git.pkgforge.dev/docs/agents/terminal) is a shell in your browser with the repository checked out, where Claude Code or Codex runs on your own plan. It is a sandbox too, so it is dormant here as well. See [Agent tasks](https://git.pkgforge.dev/docs/agents/tasks). ## Agent review on every pull request One of your agents reviews pull requests for bugs, security issues and logic errors, the way Cursor's Bugbot does. It runs in a read-only sandbox with the base branch's `REVIEW.md` rules, posts its findings as inline comments with suggested fixes, and reports an **Agent review** check that fails when a finding is blocking. **Fix it** under a finding starts an agent task on the pull request's branch, and autofix does it for every finding. It needs a sandbox, so it is dormant on git.pkgforge.dev. See [Agent review](https://git.pkgforge.dev/docs/agents/review). ![A pull request opened by an agent on Githome, with its intent, the task that wrote it, and an agent review with an inline finding, a suggested fix and a Fix it button](https://git.pkgforge.dev/docs/images/agent-pull-request.webp) ## Today: what needs you [Today](https://git.pkgforge.dev/docs/agents/today) is the first page after you sign in: what needs you (agent pull requests waiting for a person, reviews you were asked for, your own blocked pull requests), what your agents are working on, and what merged, shipped or failed since yesterday, across every repository you can see. Agents read the same view with the `today` MCP tool. ![The Today page on Githome: counts of what needs you, agent pull requests and failed runs, then the Needs you, Agents at work, Your agent tasks and Since yesterday sections](https://git.pkgforge.dev/docs/images/today.webp) ## Merge on green In **Settings → Merge on green**, a repository admin picks the checks that must pass and the agents whose pull requests land by themselves, and chooses whether a person's approval is still needed. Then pull requests merge the moment their checks pass and their branch's rules are met, with nobody clicking Merge. An agent's change to a workflow file still needs a person to merge it. See [Merge on green automatically](https://git.pkgforge.dev/docs/collaboration/merge-on-green). ![The merge box of an agent's pull request on Githome: its required check passed and auto-merge is on, waiting for a person's approval](https://git.pkgforge.dev/docs/images/merge-on-green.webp) ## Projects with shared memory Every repository is also a [project](https://git.pkgforge.dev/docs/agents/projects): a board of its agent tasks, a conversation for the people working on it, instructions every task follows and a memory every task reads. Each person can turn on a coordinator, an agent that turns their posts into tasks within the limits admins set. Every agent feature is optional and off until someone turns it on. People bring their own model keys or subscriptions; Githome doesn't sell or include model access. ## Integrations | Tool | What it adds | How to get it | | --- | --- | --- | | Claude Code | The MCP server. | `claude mcp add --scope user --transport http githome https://git.pkgforge.dev/mcp`, then sign in from `/mcp`. See [Claude Code](https://git.pkgforge.dev/docs/connect/claude-code). | | Codex | The MCP server. | `codex mcp add githome --url https://git.pkgforge.dev/mcp`, then `codex mcp login githome`. See [Codex](https://git.pkgforge.dev/docs/connect/codex). | | Any MCP client | The MCP server. | `https://git.pkgforge.dev/mcp`. See [MCP](https://git.pkgforge.dev/docs/agents/mcp). | | Claude (claude.ai, Desktop, mobile) | Githome as a custom connector. | Settings → Connectors → Add custom connector. See [Claude](https://git.pkgforge.dev/docs/connect/claude). | | Terminal | The `githome` CLI: pull requests with intent, auto-merge, runs and logs. `githome setup` signs in and sets up git and gh. | `curl -fsSL https://git.pkgforge.dev/install \| bash`. See [CLI sign-in](https://git.pkgforge.dev/docs/accounts/cli-sign-in). | | GitHub CLI | `gh pr create`, `gh pr merge` and the rest. | `githome auth setup-gh`. See [Use gh](https://git.pkgforge.dev/docs/agents/github-cli). | | Editors | Clone with the plain HTTPS URL of a repository; Githome ships no editor extension. | `githome auth setup-git` lets git push with your Githome sign-in. See [Git over HTTPS](https://git.pkgforge.dev/docs/repositories/git). | ## Docs written for agents to read Every docs page is available as Markdown (add `.md` to its URL, or send `Accept: text/markdown`). [/llms.txt](https://git.pkgforge.dev/llms.txt) indexes the site and the docs, [/llms-full.txt](https://git.pkgforge.dev/llms-full.txt) holds all of it in one file, the REST API is described as [OpenAPI 3.1](https://git.pkgforge.dev/docs/api/openapi.json), and agents connected over MCP can call `search_docs` and `read_docs`. See [Docs for AI agents](https://git.pkgforge.dev/docs/agents/docs-for-agents). ## Frequently asked questions ### Which AI coding agents work with Githome? Any agent that uses Git, the GitHub CLI, a REST API or MCP. There are step-by-step guides for Claude, Claude Code, Codex, Cursor and VS Code. ### Can I use my Claude or ChatGPT subscription? In a [terminal](https://git.pkgforge.dev/docs/agents/terminal), on a deployment where CI is on: you sign in to Claude Code or Codex there with your own plan. Headless agent tasks and agent review use an API key (Anthropic, OpenAI or OpenRouter), because the providers allow automated use with API keys. Both are dormant on git.pkgforge.dev. ### Can an agent merge its own pull request? Not by default. A person has to approve an agent's pull request, and agents can't merge into the default branch or protected branches. A repository admin can let agents land approved pull requests through auto-merge, so CI and a person decide rather than the agent. ### Do I need to give Githome my model API key? Only to run agent tasks or agent review with an API key, which need a deployment where CI is on. The key is stored encrypted and never enters the sandbox; runs reach the model through Githome's proxy with a token scoped to that run. Nothing else needs a key. ### Is Githome only for agents? No. People use the same web UI, Git and pull requests as on any forge. Agents are first-class collaborators alongside them. To report a bug or ask a question, use the public tracker at [github.com/Azathothas/issues](https://github.com/Azathothas/issues) with the label `git.pkgforge.dev`. --- # Security built in, not bolted on > How Githome protects code and secrets: passkeys instead of passwords, invite-only accounts, push protection, encrypted secrets, agent guardrails, audit log. Source: https://git.pkgforge.dev/security (last updated 2026-11-12) A forge holds a team's most valuable asset and the keys to its production systems. When AI agents push code and run workflows too, the forge has to enforce limits on its own, not trust that every token is used well. These are the protections every account and repository on Githome gets by default. Githome is a private, internal forge at git.pkgforge.dev, and the [Security overview](https://git.pkgforge.dev/docs/security/overview) documents the model that enforces them. ## People sign in with passkeys There are no passwords to guess, reuse or phish. People sign in with a passkey (WebAuthn) kept by their device, password manager or security key, with user verification required. Passkeys are bound to the domain (`git.pkgforge.dev`), so a look-alike site can't use them. Sensitive actions, such as creating an agent or a token, ask you to confirm with your passkey again when your sign-in is older than two hours. A person who lost their passkeys asks the superadmin for a sign-in link: there is no email recovery and no Cloudflare Access sign-in. See [Passkeys and sign-in](https://git.pkgforge.dev/docs/accounts/passkeys-and-sign-in). ## Invite-only Githome is invite-only: nobody joins without an invitation from the superadmin, who invites each account in the dash and sends the one-time invitation link by hand. Githome sends no email for an invitation. An invitation to an organization or a repository goes to an existing account. Invite links work once and expire after 14 days. Open sign-up is off on git.pkgforge.dev ([Configuration](https://git.pkgforge.dev/docs/self-hosting/configuration#signup)). The superadmin console is a separate site, `dash.git.pkgforge.dev`, with its own passkey sign-in. Anyone can browse and clone public repositories without an account. See [Invitations](https://git.pkgforge.dev/docs/accounts/invitations). ## Leaked credentials never land Every push, and every commit made through the web editor, the REST API or MCP, is scanned for credentials such as cloud keys and tokens. A push that contains one is refused, and nothing from it is kept. Only a repository admin who is a person can push past it, with an audited reason; an agent never can. See [Push protection](https://git.pkgforge.dev/docs/security/push-protection). ## Secrets stay secret - **Envelope encryption** with a key per repository, environment or organization, derived from a master key that can be rotated. - **Masked in logs:** secret values are replaced with `***`. - **Never handed to agent code:** a workflow run of code an agent pushed gets no repository or organization secrets, so an agent can't push a workflow that sends them elsewhere. - **Job tokens** valid for one job and limited by the workflow's `permissions:`, read-only by default for new repositories, plus short-lived OIDC id tokens so deploys need no long-lived cloud keys. The forge CI of git.pkgforge.dev is dormant, so no workflow runs there now; these protections are in the Actions code that stays in Githome. See [OIDC](https://git.pkgforge.dev/docs/actions/oidc). ## A human in the loop for agents AI agents are accounts with their own tokens and server-enforced guardrails: no pushes to protected branches, a person's approval on agent pull requests unless a repository waives it, agent check results never counted as required checks, and no secret, variable, environment or branch protection changes. See [Githome for AI agents](https://git.pkgforge.dev/agents) and [Guardrails](https://git.pkgforge.dev/docs/agents/overview#guardrails). ## Tokens with limits Personal and agent tokens (`ghome_...`) are stored hashed, expire, and can be limited to read, write or admin scope and to specific repositories. A read token never writes. See [Personal access tokens](https://git.pkgforge.dev/docs/accounts/tokens). ## Every sensitive action is recorded An append-only audit log records sign-ins, token and agent changes, permission changes, secret changes, push protection bypasses and more, and, where the deployment sends email, security emails tell you when something important changes on your account. See [Audit log](https://git.pkgforge.dev/docs/security/audit-log). ## Isolation Each repository is its own Durable Object with its own database, and the superadmin console is a separate Worker with its own D1 database and its own sign-in. Where the forge CI runs, each workflow job runs in a fresh container thrown away after the job; on git.pkgforge.dev no container starts. The web UI sends a strict, nonce-based Content Security Policy, HSTS with preload and frame protection on every page, and images from other sites in Markdown are fetched through Githome's own proxy, so those sites never see who reads a page. ## Reviewed before release The [Security overview](https://git.pkgforge.dev/docs/security/overview) documents the whole model in detail: identity and tokens, Git and storage, secrets, the agent features and MCP, the web UI and REST API, and the GitHub importer. ## Report a vulnerability If you find a security problem, please tell us privately through the [report form](https://git.pkgforge.dev/security/report), the contact in [`/.well-known/security.txt`](https://git.pkgforge.dev/.well-known/security.txt). Until the deployment has its Turnstile keys, the form takes reports only from people who are signed in. Good-faith research is covered by a safe harbour. See [Reporting a vulnerability](https://git.pkgforge.dev/docs/security/disclosure). --- # Git hosting built on Cloudflare > How Githome runs Git hosting on Cloudflare Workers, Durable Objects, D1, R2, Queues and Workflows, what that means for users, and its limits. Source: https://git.pkgforge.dev/built-on-cloudflare (last updated 2026-11-12) Githome is a private, internal git forge that runs on Cloudflare, at git.pkgforge.dev, with copies kept off Cloudflare. There are no servers, virtual machines or databases behind it that anyone has to run: one Cloudflare Worker and the Cloudflare products it uses serve Git, pull requests, the REST and GraphQL APIs, the MCP server and the container registry. This page explains which Cloudflare product does what, what that means for the people using it, and the limits that come with it. ## Where it runs Githome is deployed by its operator, from a private repository, to one Cloudflare account. It is not a product for sale: there is no hosted service to sign up for, no plan and no price, and accounts are by invitation from the superadmin. The deployment uses the Workers Paid plan, R2, D1, Queues and Workflows, and each part of the instance has its own host: - **`git.pkgforge.dev`** is the core: the web UI, Git, the APIs, MCP, the container registry and the documentation. Anyone can browse and clone public repositories there without an account. - **`dash.git.pkgforge.dev`** is the superadmin console, a Worker of its own with its own passkey sign-in. - **`NAME.git.pkgforge.dev`** is the host of each module, once the module is deployed. Nobody who uses Githome needs a Cloudflare account; people sign in with passkeys. See [Deployment and operation](https://git.pkgforge.dev/docs/self-hosting), [Deploy and update Githome](https://git.pkgforge.dev/docs/self-hosting/deploy), [Configuration](https://git.pkgforge.dev/docs/self-hosting/configuration) and [Architecture](https://git.pkgforge.dev/docs/self-hosting/architecture). ## Which Cloudflare product runs what This is the same mapping as the [Architecture](https://git.pkgforge.dev/docs/self-hosting/architecture) documentation, which goes into more detail. | Cloudflare product | What it runs in Githome | | --- | --- | | Workers | The web UI and the public docs, Git over HTTPS, Git LFS, the REST and GraphQL APIs, the MCP server and the container registry. The Worker holds no state of its own: it signs the caller in, checks their role and hands the request to the right repository. The superadmin console is a second Worker, and each module is another. | | Durable Objects with SQLite, one per repository | Everything inside one repository: branches and tags, git objects, issues, pull requests, reviews, checks and commit statuses, releases, environments, secrets, webhooks and the merge queue. Live pull request updates reach the browser over the object's WebSockets. | | R2 | Anything too large for SQLite: git objects over 512 KiB compressed, Git LFS files, container image layers, release assets and cached source archives. | | D1 | Data that belongs to no single repository: accounts, organizations, tokens, the list of repositories and who can reach them, invitations, notifications, the audit log and the container registry's index. | | Queues | Webhook deliveries and their retries, notifications, audit log entries and email jobs, sent in the background so the request that caused them doesn't wait. | | Workflows | Imports and account exports and deletions, as durable Cloudflare Workflows whose steps and waits survive restarts and deploys. | | Durable Object alarms and Cron Triggers | Housekeeping such as registry cleanup and token expiry reminders, the mirror and backup jobs, and the workflow scheduler. | | Email Sending | Notification and security email, where the deployment has email sending set up. Githome sends no email for an invitation. | The forge CI of git.pkgforge.dev is dormant: the instance starts no Actions run, no hosted job and no Cloudflare Container. The Actions code is part of Githome, and the [Actions documentation](https://git.pkgforge.dev/docs/actions/overview) keeps its reference content. ## How a push moves through it 1. `git push` reaches the Worker, which checks your token and your role on the repository and passes the push to the repository's Durable Object. 2. The object scans every new file for leaked credentials ([push protection](https://git.pkgforge.dev/docs/security/push-protection)), stores the objects (small ones in its SQLite database, large ones in R2), checks branch protection and moves each branch with a compare-and-swap, so two pushes to the same branch are applied one after the other. 3. The object emits a `push` event to the events queue, which writes the audit log entry, delivers webhooks and creates notifications in the background. A push mirror, where one is set up, copies the repository with its forge state to another provider. ## What this means for you - **No servers to run.** The instance is a Worker and the Cloudflare products it binds to, so there is nothing to provision, patch or scale. `gh` and your editor's plain HTTPS clone work as they do with GitHub. - **One busy repository never slows another.** Each repository is its own Durable Object with its own database, the single writer for everything in it, so ref updates and merges are strongly consistent without locks. - **Long work survives restarts.** An import is a durable Workflow, so a deploy or a restart doesn't lose it. - **Mirrored and backed up.** Push mirrors copy each repository, with its forge state in `refs/githome/meta`, to GitHub, Cloudflare Artifacts, GitLab, Forgejo or Codeberg, and backups go to an S3-compatible bucket off Cloudflare once its credentials are set. - **Cloudflare's network.** Requests are answered by the Worker at the Cloudflare location that receives them. A repository's own data lives in its Durable Object, in one place, so pages that read a repository make a trip to wherever that object is. ## Limits that come with building on Cloudflare - **A push carries at most 100 MB.** Use [Git LFS](https://git.pkgforge.dev/docs/repositories/git-lfs) for large files. Container image layers larger than Cloudflare's 100 MB request limit can't be pushed in one request. - **Clones send more bytes than GitHub's.** Packs are sent without deltas, so clones and fetches download more data. See [Git over HTTPS](https://git.pkgforge.dev/docs/repositories/git#limits-and-differences-from-github). - **No Cloudflare Containers in use.** Because the forge CI is dormant, there are no hosted runners and no agent sandboxes on git.pkgforge.dev. Imports from GitLab, Forgejo, Gitea and Codeberg run without a container; the server-side import from GitHub needs the import container and stops at its Git step. - **Per-account quotas.** The superadmin sets quotas for repositories and storage per account. See [Limits](https://git.pkgforge.dev/docs/reference/limits). ## Frequently asked questions ### Does Githome run on Cloudflare? Yes, with copies off Cloudflare. A Cloudflare Worker serves the web UI, Git, the APIs and MCP; each repository is a Durable Object with its own SQLite database; large files live in R2 and accounts in D1; imports are Cloudflare Workflows. See [Architecture](https://git.pkgforge.dev/docs/self-hosting/architecture). ### Can I sign up for Githome? No, accounts are by invitation. The superadmin invites each account in the dash and sends the one-time invitation link by hand. Anyone can browse and clone public repositories without an account. See [Invitations](https://git.pkgforge.dev/docs/accounts/invitations). ### Does Githome run CI? Not on git.pkgforge.dev. The forge CI is dormant, so no workflow runs there now. The Actions documentation keeps the reference content for the code that stays in Githome. ### Where do I report a bug or ask a question? In the public tracker, [github.com/Azathothas/issues](https://github.com/Azathothas/issues), with the label `git.pkgforge.dev`. Report security problems privately with the [report form](https://git.pkgforge.dev/security/report), which takes reports only from signed-in people until the deployment has its Turnstile keys. --- # About Githome > What Githome is, how it's built on Cloudflare, who can use it at git.pkgforge.dev, and how to reach the people who run it. Source: https://git.pkgforge.dev/about (last updated 2026-11-12) Githome is a private, internal git forge at git.pkgforge.dev. It is compatible with GitHub's API and with `gh`, and it runs on Cloudflare, with copies kept off Cloudflare. Agents do their work through Git and pull requests like everyone else; people see what the agents did, approve what needs them and follow the whole process. Githome is not a product for sale: there is no plan, no price and no hosted service to sign up for. ## Why it exists GitHub was designed for people. Agents on GitHub borrow a person's token, their pull requests look like anyone else's, and the only limits on them are the ones a team remembers to configure. Githome is a forge where an agent is an account of its own with limits the server enforces, and where moving from GitHub costs an afternoon rather than a rewrite: your workflow files stay in the repository (no run starts here while the forge CI is dormant), and `gh` and your editor's plain HTTPS clone keep working. ## How it's built - **On Cloudflare, with no servers.** A Worker serves the web UI, Git, the REST and GraphQL APIs and MCP; every repository is a Durable Object with its own SQLite database; accounts live in D1 and large objects in R2. See [Architecture](https://git.pkgforge.dev/docs/self-hosting/architecture) and [Built on Cloudflare](https://git.pkgforge.dev/built-on-cloudflare). - **Separate hosts for separate jobs.** The core serves `git.pkgforge.dev`. The superadmin console is its own site, `dash.git.pkgforge.dev`, with its own passkey sign-in, and each module will serve `NAME.git.pkgforge.dev` once it is deployed. See [Deployment and operation](https://git.pkgforge.dev/docs/self-hosting). - **Mirrored and backed up.** Push mirrors copy each repository, with its forge state, to GitHub, Cloudflare Artifacts, GitLab, Forgejo or Codeberg, and backups go to an S3-compatible bucket off Cloudflare once its credentials are set. - **The forge CI is dormant.** git.pkgforge.dev starts no Actions run, no hosted job and no agent sandbox. The Actions code is part of Githome, and the [Actions documentation](https://git.pkgforge.dev/docs/actions/overview) keeps its reference content. ## Who can use it Anyone can browse and clone public repositories at git.pkgforge.dev without an account. A write needs an account, and accounts are by invitation: the superadmin invites each one in the dash and sends the one-time invitation link by hand. Githome sends no email for an invitation, and open sign-up is off. People sign in with a passkey. See [Invitations](https://git.pkgforge.dev/docs/accounts/invitations) and [Passkeys and sign-in](https://git.pkgforge.dev/docs/accounts/passkeys-and-sign-in). ## For AI assistants and search engines Everything on this site is public and available as Markdown: add `.md` to any page's address, or send `Accept: text/markdown`. [/llms.txt](https://git.pkgforge.dev/llms.txt) indexes the site and the documentation, and [/llms-full.txt](https://git.pkgforge.dev/llms-full.txt) holds all of it in one file. Every site page shows the date its facts were last checked. ## Contact - **Questions and privacy requests:** the [contact form](https://git.pkgforge.dev/contact), for people with an account. Messages reach the superadmin, who reads them in the dash. - **Bugs and questions about the service:** the public tracker, [github.com/Azathothas/issues](https://github.com/Azathothas/issues), with the label `git.pkgforge.dev`. Without an account, this is the way to reach the people who run the instance: until the deployment has its Turnstile keys, the contact form and the report form take messages only from people who are signed in. - **Security problems:** the private [report form](https://git.pkgforge.dev/security/report), as listed in [`/.well-known/security.txt`](https://git.pkgforge.dev/.well-known/security.txt), for people with an account. - **git.pkgforge.dev status:** [/status](https://git.pkgforge.dev/status). - **Documentation:** [git.pkgforge.dev/docs](https://git.pkgforge.dev/docs). --- # Githome FAQ > Short answers about Githome: who can use it, accounts and sign-in, GitHub compatibility, the dormant forge CI, Cloudflare, AI agents, security and migration. Source: https://git.pkgforge.dev/faq (last updated 2026-11-12) Short, direct answers to the questions people and AI assistants ask most about Githome. Each answer links to the page with the details. ## Frequently asked questions ### What is Githome? Githome is a private, internal git forge at git.pkgforge.dev, compatible with GitHub's API and with `gh`. It hosts Git repositories, pull requests with reviews and a merge queue, issues, releases and a container registry, and gives AI agents accounts of their own with guardrails the server enforces. It runs on Cloudflare, with copies kept off Cloudflare. See [Features](https://git.pkgforge.dev/features) and [About Githome](https://git.pkgforge.dev/about). ### Can I sign up for Githome? No. Githome is not a product for sale, and there is no hosted service to sign up for and no plan or price. Accounts are by invitation: the superadmin invites each account in the dash and sends the one-time invitation link by hand, and Githome sends no email for an invitation. Open sign-up is off on git.pkgforge.dev. Anyone can browse and clone public repositories without an account; a write needs an account. See [Invitations](https://git.pkgforge.dev/docs/accounts/invitations). ### Can I deploy my own copy? No. The repository of Githome is private, and there is no public clone URL. The docs describe how the instance at git.pkgforge.dev is deployed and configured, so that its operator and its users can reason about it: see [Deployment and operation](https://git.pkgforge.dev/docs/self-hosting) and [Deploy and update Githome](https://git.pkgforge.dev/docs/self-hosting/deploy). ### Where do I report a bug or ask a question? In the public tracker, [github.com/Azathothas/issues](https://github.com/Azathothas/issues), with the label `git.pkgforge.dev`. Githome takes no pull requests from visitors. For a question to the people who run the instance, use the [contact form](https://git.pkgforge.dev/contact) if you have an account: until the deployment has its Turnstile keys, the contact form and the [security report form](https://git.pkgforge.dev/security/report) take messages only from people who are signed in. Without an account, ask in the public tracker. The messages reach the superadmin. ### Is Githome a GitHub alternative? For the teams that use it, yes: Githome replaces GitHub's code hosting and pull requests. It doesn't have GitHub's app marketplace, Codespaces, Pages or Discussions, and its forge CI is dormant. See [Features](https://git.pkgforge.dev/features). ### Does Githome run CI? Not on git.pkgforge.dev. The forge CI is dormant: an event starts no Actions run, and a dispatch, a sandbox or a terminal is refused with "CI is off on this deployment". No hosted job runs there and no Cloudflare Container starts. The Actions code is part of Githome, and the [Actions documentation](https://git.pkgforge.dev/docs/actions/overview) keeps its reference content: syntax, expressions, events and permissions. Each of those pages notes that no workflow runs on git.pkgforge.dev now. ### Do GitHub Actions workflow files work on Githome? The syntax, expressions, matrices, reusable workflows, environments, secrets, variables and OIDC are implemented, and every difference from GitHub is listed in [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility). Because the forge CI of git.pkgforge.dev is dormant, no workflow runs there now. Your workflow files stay in the repository. ### Does Githome have macOS, Windows or Arm runners? No hosted ones, and none run on git.pkgforge.dev while the forge CI is dormant. Self-hosted runners are described in [Runners](https://git.pkgforge.dev/docs/actions/runners). ### Does Githome run on Cloudflare? Yes, with copies off Cloudflare (push mirrors, and backups once their bucket is set). A Cloudflare Worker serves the web UI, Git, the REST and GraphQL APIs and MCP; each repository is a Durable Object with its own SQLite database; large files are in R2 and accounts in D1; imports are Cloudflare Workflows. The superadmin console is its own site, `dash.git.pkgforge.dev`, and each module will serve `NAME.git.pkgforge.dev` once it is deployed. See [Built on Cloudflare](https://git.pkgforge.dev/built-on-cloudflare). ### Which AI coding agents work with Githome? Any agent that uses Git, the GitHub CLI, a REST API or MCP. Githome gives agents the MCP server at `https://git.pkgforge.dev/mcp` (browser sign-in, or a bearer token), the `githome` CLI, `gh` against the core, agent tokens and guardrails. Claude Code: `claude mcp add --scope user --transport http githome https://git.pkgforge.dev/mcp`. Codex: `codex mcp add githome --url https://git.pkgforge.dev/mcp`. claude.ai connects through a connector. Githome ships no editor extension, no Claude Code or Codex plugin and no plugin marketplace, and an editor clones with the plain HTTPS URL. See [Connect AI apps](https://git.pkgforge.dev/docs/connect) and [Githome for AI agents](https://git.pkgforge.dev/agents). ### Does Githome have an MCP server? Yes, at `https://git.pkgforge.dev/mcp`, with browser sign-in (OAuth 2.1) or an agent token. Its tools read code, commit files, open, review and merge pull requests and start imports, under the same permission checks and guardrails as Git and the REST API. The tools that start work (a dispatch, a re-run, a sandbox) answer "CI is off on this deployment"; the tools that read workflow runs and job logs answer from stored data. See [MCP server](https://git.pkgforge.dev/docs/agents/mcp). ### Can an AI agent merge its own pull request? Not by default. Agents are accounts of their own: unless a branch protection rule allows it, they can't push to or merge into the default branch or protected branches, their pull requests need a person's approval, and their check results never satisfy required checks. See [Guardrails](https://git.pkgforge.dev/docs/agents/overview#guardrails). ### How do I move from GitHub? Githome's server-side importer copies a GitLab, Forgejo, Gitea or Codeberg repository with its full Git history, issues and pull requests (keeping their numbers), reviews, comments, labels, milestones, releases and branch protection, without a container. The server-side import from GitHub needs the import container, which git.pkgforge.dev does not run, so it stops at its Git step with "no import container is configured". For GitHub, use the local import (`githome migrate github --local`) or a GitHub pull mirror. Secret values can't be copied, so you enter them once. See [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github). ### Can I keep a copy on GitHub? Yes. Push mirrors copy each repository, with its forge state, to GitHub, Cloudflare Artifacts, GitLab, Forgejo or Codeberg. See [Mirrors and backups](https://git.pkgforge.dev/docs/self-hosting/deploy#mirrors-and-backups). ### Does the GitHub CLI work with Githome? Yes. `gh` works with Githome as it does with GitHub Enterprise Server: after `githome auth setup-gh`, commands such as `gh pr create` and `gh pr merge` work in a Githome clone. See [Use gh with Githome](https://git.pkgforge.dev/docs/agents/github-cli). ### Does Githome work with VS Code, Cursor and JetBrains IDEs? Githome ships no editor extension and no JetBrains plugin. An editor clones with the plain HTTPS URL of the repository, with a token as the password. ### Does Githome support Git LFS? Yes. Githome has a built-in Git LFS server, so `git lfs push`, `git lfs pull` and clones of repositories that use LFS work as they do with GitHub. See [Git LFS](https://git.pkgforge.dev/docs/repositories/git-lfs). ### Does Githome have a container registry? Yes. Push and pull images at `git.pkgforge.dev//` with `docker`, `podman`, `buildx` or `crane`. Images are private by default and can be linked to a repository whose collaborators then share access. See [Container registry](https://git.pkgforge.dev/docs/packages/container-registry). ### What doesn't Githome do yet? Git works over HTTPS only, with no SSH. There are no discussions, Pages-style sites, Codespaces-style cloud editors or app marketplace, and the forge CI is dormant. See [What Githome doesn't do yet](https://git.pkgforge.dev/features#what-githome-doesnt-do-yet). ### How do people sign in, and how are secrets protected? People sign in with passkeys; there are no passwords, no email recovery and no Cloudflare Access sign-in. A person who lost their passkeys asks the superadmin for a sign-in link. Every push, and every commit made through the web editor, the API or MCP, is scanned for leaked credentials and refused if it contains one. Stored secrets are encrypted with a key per repository, environment or organization, and an append-only audit log records sensitive actions. See [Security](https://git.pkgforge.dev/security). ### Is Githome SOC 2 certified? No. Githome is a private, internal instance, not a service for sale, so there is nothing to certify. The [Security overview](https://git.pkgforge.dev/docs/security/overview) documents the whole security model. See [Security](https://git.pkgforge.dev/security). ### How do I contact the people who run Githome? If you have an account, use the [contact form](https://git.pkgforge.dev/contact) at git.pkgforge.dev/contact, or the [security report form](https://git.pkgforge.dev/security/report) for security problems; the messages reach the superadmin. Until the deployment has its Turnstile keys, both forms take messages only from people who are signed in, so without an account use the [public tracker](https://github.com/Azathothas/issues) with the label `git.pkgforge.dev`. See [Contact form](https://git.pkgforge.dev/docs/admin/contact-form). ### How do people join? Accounts are by invitation from the superadmin, who sends the one-time invitation link by hand; Githome sends no email for an invitation. An invitation to an organization goes to an existing account. Open sign-up is off on git.pkgforge.dev. See [Invitations](https://git.pkgforge.dev/docs/accounts/invitations) and [Configuration](https://git.pkgforge.dev/docs/self-hosting/configuration#signup). --- # Privacy policy > What personal data git.pkgforge.dev and the Githome CLI, editor extensions and agent plugins handle, who processes it, and how long it is kept. Source: https://git.pkgforge.dev/privacy (last updated 2026-10-26) This policy covers **git.pkgforge.dev**, the website and Githome instance that Codician runs, and the Githome **CLI, editor extensions and AI-agent plugins** that Codician publishes. It explains what personal data they handle, why, who processes it, how long it is kept, and what you can ask of us. **The short version:** we collect what git.pkgforge.dev needs to work, we don't sell data, we don't show ads, and there are no analytics or tracking cookies. If you run Githome yourself, your instance's data stays on your own Cloudflare account, and Codician never receives it. Codician ("we") is responsible for the data described here. Contact: **hi@codician.com**. ## If you run your own Githome Githome is open-source software (Apache-2.0). When you deploy it to your own Cloudflare account, you, not Codician, decide what your instance collects and keep all of its data: accounts, repositories, logs and everything else stay on your Cloudflare account. The software doesn't send usage data or telemetry to Codician. Each instance does tell search engines about its own public pages through IndexNow; you can turn that off ([Search engines](https://git.pkgforge.dev/docs/admin/site-administration#search-engines)). This policy doesn't cover instances run by other people; ask whoever runs yours. ## The CLI, editor extensions and AI-agent plugins The `githome` CLI, the VS Code and JetBrains extensions, and the Claude Code and Codex plugins talk only to the Githome instance you set them up for (git.pkgforge.dev unless you choose another). They sign you in to that instance and send it the requests you make, such as listing pull requests or reading a job log. They send nothing to Codician or anyone else. Your token is kept on your computer: in the CLI's config file, your editor's secret storage, or the place your agent app keeps sign-ins. Downloading the CLI, an extension or a plugin from git.pkgforge.dev is an ordinary web request, handled as described under [Visiting the website](https://git.pkgforge.dev/privacy#visiting-the-website). Marketplaces you install from (the Visual Studio Marketplace, Open VSX, the JetBrains Marketplace or a plugin directory) handle your data under their own policies. ## Visiting the website Anyone can read git.pkgforge.dev's public pages, documentation and public repositories without an account. For those visits we don't collect personal data beyond what any web server handles: - **Cloudflare**, which hosts git.pkgforge.dev, processes your IP address, browser user agent and the pages you request to serve the site and protect it from attacks. Our request logs are kept for up to 7 days. - **No analytics or advertising.** There are no analytics scripts, tracking pixels or third-party marketing tools on git.pkgforge.dev. - **Star on GitHub buttons** are plain links. git.pkgforge.dev's server reads the star count from GitHub, so your browser contacts GitHub only if you follow one. ### Cookies git.pkgforge.dev sets only cookies it needs to work. None are used for advertising or to follow you across sites, so there's no cookie banner. | Cookie | What it does | How long | | --- | --- | --- | | `__Host-ghome_session` | Keeps you signed in | 30 days, or until you sign out | | `__Host-ghome_webauthn` | Holds the passkey challenge while you sign in | 5 minutes | | `__Host-ghome_access` | Marks the email recovery that you started in this browser, where the instance offers it | 15 minutes | | `__Host-ghome_csrf` | Protects forms against cross-site request forgery | 30 days | | `__Host-ghome_d1` | Lets the database show you your own changes straight away | 1 day | | `__Host-ghome_flash` | Shows a one-time message after an action | 1 minute | | `__Host-ghome_theme` | Remembers light or dark appearance if you choose one | 400 days | | `__Host-today_collapsed` | Remembers which sections of the Today page you folded | 1 year | ## Forms anyone can use - **Early access requests** (`/early-access`): the email address you give and, if you fill them in, your name, company, what you'd use Githome for and where you host code today. Unconfirmed requests are deleted after 7 days; confirmed ones are kept until a site administrator deletes the request, and you can delete yours yourself at any time. To enforce daily limits, we keep a hashed form of your IP address and of the email address you typed for one day. Details: Early access. - **Contact messages** (`/contact`): your name, the email address you give (or your account's, if you're signed in), the topic and your message, and a note our site administrators may add about how they answered. Only git.pkgforge.dev's site administrators can read messages, and we use them only to reply. If you aren't signed in, your message waits until you confirm your address with the link we email you; unconfirmed messages are deleted after 7 days, unread. Messages marked as spam are deleted after 30 days, and answered ones 365 days after we mark them handled. For daily limits, we keep a hashed form of your IP address and of the email address you typed for one day. Details: [Contact form](https://git.pkgforge.dev/docs/admin/contact-form). - **Security reports** (`/security/report`): what you write, and the email address you give for a reply if you aren't signed in. Only git.pkgforge.dev's site administrators can read reports. - People who aren't signed in pass a **Cloudflare Turnstile** check on these forms, which Cloudflare runs using signals from your browser. ## Accounts on git.pkgforge.dev git.pkgforge.dev is invite-only: accounts are for the people working on Githome. If you have one, we handle: - **Account data:** your email address, username, display name and the profile details you add; the **public keys** of your passkeys (private keys never leave your device); access tokens and agent accounts you create, stored in a form that only lets us check them; who invited you and when. - **What you put on the instance:** repositories and everything in them, issues, pull requests, reviews, comments, releases, workflow files, job logs, artifacts and container images. Git commits carry the author name and email address configured in git; in a public repository they are public. - **Agent features:** model provider API keys you add are stored encrypted and never enter the sandboxes where agents run. When you start an agent task, review or sandbox, the prompts, code and command output the agent needs go to **the model provider you chose** (such as Anthropic or OpenAI), under your own account with that provider and its own terms and privacy policy. Githome keeps each task's transcript, visible to people with write access to the repository, and a record of the tokens each run used, so it can show usage and enforce budgets. - **Security records:** an audit log of significant actions (such as sign-ins, token changes, permission changes and deletions) with who acted, when and from which IP address; a log of the notification emails sent to you and whether they were delivered; addresses that bounced or marked our mail as spam, so we stop writing to them; abuse reports and blocks. We use this data to run the instance and keep it secure: hosting your code, running workflows and agents, signing you in, sending the notifications you've chosen, and preventing abuse. Where laws such as the GDPR apply, the legal bases are providing the service you signed up for and our legitimate interest in keeping it secure. **We don't use your private content to train machine-learning models.** ## Who processes the data - **Cloudflare, Inc.** hosts git.pkgforge.dev and stores its data: Workers, Durable Objects, D1, R2, Queues, Containers (CI runners and agent sandboxes), Email Sending (notifications) and Turnstile. Data isn't pinned to one country: Cloudflare places it and runs jobs in its data centers around the world, and transfers rely on the Standard Contractual Clauses in Cloudflare's data processing terms. - **The model provider you choose** for agent features, as described above. - **Other people:** public repositories and public profiles are visible to anyone; private repositories to the people given access. - **Authorities:** we disclose data only when the law requires it or when it's needed to protect people's safety or rights, and we tell you first where we're allowed to. We don't sell or rent personal data, and we don't share it for advertising. ## How long data is kept | Data | Kept | | --- | --- | | Request logs (with IP addresses) | Up to 7 days | | Sign-in sessions | 30 days, or until you sign out | | Notification email log | 90 days | | Job logs | 90 days | | Workflow artifacts | 1 to 90 days, as the workflow sets (90 by default) | | Account data exports | 7 days | | Contact messages | 7 days unconfirmed; 30 days once marked spam; 365 days after they are answered | | Audit log | 2 years | | Database backups | 30 days of point-in-time recovery | | Username of a deleted account | Not reusable for 90 days | | Your account, content and provider keys | Until you delete them or your account | ## Your choices and rights - **See and export your data:** under **Settings → Account**, download an archive with your profile, settings, repositories (as git bundles) and the issues, comments and reviews you wrote. See [Exporting and deleting your account](https://git.pkgforge.dev/docs/accounts/account-data). - **Correct it:** edit your profile and email address in your settings. - **Delete it:** delete repositories, tokens and provider keys in settings, or your whole account under **Settings → Account**. Commits, issues and comments you made in other people's repositories stay part of those repositories, shown as written by a deleted user, and the audit log keeps what your account did. - **Anything else:** write to **hi@codician.com** to ask for a copy of your data, to object to or restrict a use of it, or with any question. We answer within one month. Depending on where you live, you can also complain to your data protection authority. ## Security Data is encrypted in transit; provider keys and secrets are encrypted at rest; runners and sandboxes are isolated per job; sign-in uses passkeys; and access is logged. See [Security](https://git.pkgforge.dev/security). Please report vulnerabilities through [the private report form](https://git.pkgforge.dev/security/report), never a public issue. ## Children git.pkgforge.dev is not meant for children, and its accounts are for the people working on Githome. ## Changes We'll update this page when what we do changes and change the date at the top. If a change matters to people with accounts, we'll tell them by email before it takes effect. ## Contact Codician, **hi@codician.com**, or the [contact form](https://git.pkgforge.dev/contact). Security reports: [git.pkgforge.dev/security/report](https://git.pkgforge.dev/security/report). --- # Overview > What Githome is, how it fits together, and where to start, whether you are a person, a team moving from GitHub or an AI agent. Source: https://git.pkgforge.dev/docs Githome is a private git forge for people and AI agents, running on Cloudflare at `https://git.pkgforge.dev`. It hosts git repositories, pull requests with reviews and a merge queue, issues, a container registry, a GitHub-style REST API and an MCP server for agents. It also holds GitHub-Actions-compatible CI, which is dormant on git.pkgforge.dev: no workflow runs there now. A server-side importer brings over a repository from GitLab, Forgejo, Gitea or Codeberg, with its history, issues, pull requests, reviews and releases; the server-side import from GitHub needs the import container, which git.pkgforge.dev does not run, so a GitHub repository comes in through the local import (`githome migrate github --local`) or a GitHub pull mirror (see [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github)). ## Start here | If you want to | Read | | --- | --- | | Get set up and push your first repository | [Quickstart](https://git.pkgforge.dev/docs/quickstart) | | Understand accounts, roles, agents and runs | [Concepts](https://git.pkgforge.dev/docs/concepts) | | Move a project from GitHub (the local import, `githome migrate github --local`) or from another forge (**Settings → Imports**) | [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github) | | Read how CI works (dormant on git.pkgforge.dev: no workflow runs there now) | [Actions overview](https://git.pkgforge.dev/docs/actions/overview) and [Workflow syntax](https://git.pkgforge.dev/docs/actions/workflow-syntax) | | Connect Claude, Claude Code, Codex or another AI app (one URL, a browser sign-in) | [Connect AI apps](https://git.pkgforge.dev/docs/connect) | | Run your own AI agents on Githome, with their own accounts and tokens | [Agents](https://git.pkgforge.dev/docs/agents/overview) and [MCP](https://git.pkgforge.dev/docs/agents/mcp) | | Give an agent a goal and get a pull request back, with your own model key (dormant: the forge CI is off) | [Agent tasks](https://git.pkgforge.dev/docs/agents/tasks) | | See the tokens and cost your agent tasks and reviews used | [Usage and cost](https://git.pkgforge.dev/docs/agents/tasks#usage-and-cost) | | Pay for an organization's agents with its own keys, and set what they may use (dormant: the forge CI is off) | [Agents in organizations](https://git.pkgforge.dev/docs/agents/organizations) | | Work in a browser shell with Claude Code or Codex (dormant: the forge CI is off) | [Terminals](https://git.pkgforge.dev/docs/agents/terminal) | | Track agent work on a board, with shared memory and project instructions | [Projects](https://git.pkgforge.dev/docs/agents/projects) | | See what needs you and what your agents did since yesterday | [Today](https://git.pkgforge.dev/docs/agents/today) | | Have one of your agents review pull requests for bugs, like Bugbot (dormant: the forge CI is off) | [Agent review](https://git.pkgforge.dev/docs/agents/review) | | Script against Githome | [REST API guide](https://git.pkgforge.dev/docs/reference/rest-api), [REST API reference](https://git.pkgforge.dev/docs/api) and [CLI reference](https://git.pkgforge.dev/docs/reference/cli) | | Export your data or delete your account | [Exporting and deleting your account](https://git.pkgforge.dev/docs/accounts/account-data) | | Check whether Githome is up | [Status page](https://git.pkgforge.dev/docs/self-hosting/status-page) | | Administer githome (the superadmin, in the dash at `https://dash.git.pkgforge.dev`) | [Site administration](https://git.pkgforge.dev/docs/admin/site-administration) | | Report a security problem privately (the [report form](https://git.pkgforge.dev/security/report)) | [Reporting a vulnerability](https://git.pkgforge.dev/docs/security/disclosure) | ## What you get - **Git hosting.** Clone, fetch and push over HTTPS with a token. Shallow clones, Git LFS and `refs/pull//head` and `/merge` work as on GitHub. See [Git over HTTPS](https://git.pkgforge.dev/docs/repositories/git). - **Pull requests and issues.** Draft pull requests, reviews with line comments, required approvals and checks, merge, squash and rebase, an `intent` field that tells reviewers what a change is meant to do, and a merge queue. See [Pull requests](https://git.pkgforge.dev/docs/collaboration/pull-requests) and [Merge queue](https://git.pkgforge.dev/docs/collaboration/merge-queue). - **Actions.** Workflow YAML compatible with GitHub Actions: the same triggers, expressions, matrices, `needs`, outputs, reusable workflows, secrets, variables, OIDC, service containers and Docker. The forge CI of git.pkgforge.dev is dormant, so no workflow runs there now. See [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility). - **Container registry.** Push and pull images at `git.pkgforge.dev//` instead of ghcr.io. See [Container registry](https://git.pkgforge.dev/docs/packages/container-registry). - **Agents as first-class accounts.** Agents have their own logins and tokens, act on behalf of a person or an organization, and work through MCP, the REST API, git or the CLI. Guardrails keep a human in the loop: unless a branch protection rule allows it, agents can't push to or merge into the default branch or protected branches, and their pull requests need a human approval. [Agent tasks](https://git.pkgforge.dev/docs/agents/tasks) and [agent review](https://git.pkgforge.dev/docs/agents/review) need the forge CI, which is dormant here, and [Today](https://git.pkgforge.dev/docs/agents/today) shows what needs you and what your agents did. See [Agents](https://git.pkgforge.dev/docs/agents/overview). - **Security by default.** Passkeys instead of passwords, invite-only sign-up, branch protection, push protection that blocks leaked credentials, encrypted secrets and an audit log. See [Security overview](https://git.pkgforge.dev/docs/security/overview). ## How Githome runs Githome runs on Cloudflare, with copies kept off Cloudflare and no servers to manage: a Worker serves the web UI, git, the API and MCP; each repository is a Durable Object with its own SQLite database; large objects live in R2; and accounts live in D1. Githome starts no Cloudflare Container. See [Architecture](https://git.pkgforge.dev/docs/self-hosting/architecture). ## Ways to work with Githome | Interface | Best for | Where | | --- | --- | --- | | Web UI | Browsing code, reviewing, settings | `https://git.pkgforge.dev` | | git | Code | `https://git.pkgforge.dev//.git` | | CLI | Terminals and scripts | [`githome`](https://git.pkgforge.dev/docs/reference/cli) | | REST API | Integrations, GitHub-compatible tools | `https://git.pkgforge.dev/api/v3`, see [the reference](https://git.pkgforge.dev/docs/api) | | MCP | AI apps and agents | `https://git.pkgforge.dev/mcp`, see [Connect AI apps](https://git.pkgforge.dev/docs/connect) and [the tools](https://git.pkgforge.dev/docs/reference/mcp-tools) | | Webhooks | Reacting to events elsewhere | [Webhooks](https://git.pkgforge.dev/docs/repositories/webhooks) | ## For AI agents reading these docs Every page is available as plain Markdown: add `.md` to its URL, or send `Accept: text/markdown`. [/llms.txt](https://git.pkgforge.dev/llms.txt) indexes every page, [/llms-full.txt](https://git.pkgforge.dev/llms-full.txt) holds all of them in one file, and [/docs/api/openapi.json](https://git.pkgforge.dev/docs/api/openapi.json) describes the REST API. Agents connected over MCP can call `search_docs` and `read_docs`. See [Docs for AI agents](https://git.pkgforge.dev/docs/agents/docs-for-agents). ## Access Githome is invite-only, and open sign-up is off. You join from the link of an instance invite, which the superadmin makes in the dash and sends you by hand; githome sends no email for it. You sign in with a passkey, and a person who lost their passkeys asks the superadmin for a sign-in link. These docs are public and need no account, and so are public repositories: anyone can browse and clone them, but opening issues, commenting, pushing and every other change need an account. See [Invitations](https://git.pkgforge.dev/docs/accounts/invitations). A bug or a question goes to the public tracker [Azathothas/issues](https://github.com/Azathothas/issues) with the label `git.pkgforge.dev`. --- # 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//...`. 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//.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). --- # Concepts > The Githome mental model in one page: accounts, agents, repositories, roles, tokens, checks, releases, environments, Actions and audit. Source: https://git.pkgforge.dev/docs/concepts This page explains the building blocks of Githome and how they fit together. Each section is a short summary with a link to the page that covers it in full. If you know GitHub, most ideas carry over; the differences are called out as you go. All of it happens on githome, the private forge at `https://git.pkgforge.dev`, where accounts are made by invitation. The examples use that address. ## Accounts Every action on Githome is taken by an account. There are three kinds: users, organizations and agents. All three share one namespace, so `https://git.pkgforge.dev/diffy`, `https://git.pkgforge.dev/acme` and `https://git.pkgforge.dev/review-bot` are all account pages, and repositories live under users and organizations. ### Users A user is a person. Githome is invite-only, and [open sign-up](https://git.pkgforge.dev/docs/accounts/passkeys-and-sign-in#open-sign-up) is off: you join by opening an invite link that the superadmin sends you, choosing a username and creating a passkey. There are no passwords. In the browser you sign in with a passkey; everything outside the browser (Git, the CLI, the REST API, MCP clients) uses a [token](#tokens). The superadmin administers githome in the dash at `https://dash.git.pkgforge.dev`: people and invitations, email, the audit log and more. The core has no **Site administration** section in settings. See [Passkeys and sign-in](https://git.pkgforge.dev/docs/accounts/passkeys-and-sign-in), [Invitations](https://git.pkgforge.dev/docs/accounts/invitations) and [Site administration](https://git.pkgforge.dev/docs/admin/site-administration). ### Organizations An organization is a shared account that owns repositories, agents, container images and Actions secrets for a group of people. Members have one of three roles, which decide their role on every repository the organization owns: | Organization role | Role on the organization's repositories | | --- | --- | | member | The organization's base permission: `none`, `read`, `write` or `admin` | | admin | admin | | owner | admin, plus managing owners and renaming the organization | The base permission is a setting of the organization, as on GitHub: new organizations start with `read`, and owners change it on the organization's **Settings** tab. A member who creates a repository in the organization gets `admin` on it. Unlike GitHub, there are no teams and no custom roles. To give someone more access to a single repository, add them as a collaborator on it. See [Organizations](https://git.pkgforge.dev/docs/accounts/organizations) and [Base permission](https://git.pkgforge.dev/docs/accounts/organizations#base-permission). ### Agents An agent is an account for an AI tool or an automation, such as `review-bot`. It is owned by a user or an organization, acts on their behalf and authenticates only with tokens: it can't have a passkey, so it never signs in to the web UI. GitHub has no equivalent; the closest thing is a bot account or a GitHub App. Agents are held to guardrails that keep a person in the loop: - An agent never has more access than its owner. An organization's agent can reach only that organization's repositories. - Its maximum role is `write` unless its owner chooses otherwise. - It can't push to, or merge into, the default branch or a protected branch, unless a branch protection rule explicitly allows it. A rule can instead let it turn on auto-merge, so Githome merges its pull request once the required checks pass and a person approves (or, if an admin waives that, on green checks alone). - A pull request it opens needs at least one approval from a person, and its own approvals never count. - It can't change branch protection, add, change or delete secrets or variables (repository, organization or environment), create, change or delete environments, dismiss reviews, delete or transfer repositories, or bypass push protection. - Commit statuses and check runs it reports never satisfy a required check, and tags it pushes never match an environment's tag rules. - Commits it makes carry a `githome-agent` header naming the agent and the person it acts for. - A workflow run whose code came from an agent (the agent triggered it, pushed the branch last, or opened the pull request, and re-runs and `workflow_run` followers of such a run) acts as the agent, so a workflow can't carry agent-written code past these rules. - It can import from GitHub only into an organization it or its owner administers, its imports never bypass push protection, and they skip variables, secret names and environments. Agents work through the [MCP server](https://git.pkgforge.dev/docs/agents/mcp), the REST API, the CLI and Git. Githome can also run one for you, where the forge CI is on (it is dormant on git.pkgforge.dev, so no agent task, terminal or sandbox starts there now): an [agent task](https://git.pkgforge.dev/docs/agents/tasks) gives one of your agents a goal and runs Claude Code, Codex or your own command with your own model key, then opens a pull request, a [terminal](https://git.pkgforge.dev/docs/agents/terminal) gives you a shell in a sandbox where Claude Code or Codex runs on your own subscription and can take tasks too, a repository's [project](https://git.pkgforge.dev/docs/agents/projects) puts its tasks on a board with shared memory and instructions, and [agent review](https://git.pkgforge.dev/docs/agents/review) has one review pull requests for bugs. [Today](https://git.pkgforge.dev/docs/agents/today), the first page after signing in, shows what needs you and what your agents are doing. See [Agents](https://git.pkgforge.dev/docs/agents/overview). ### People imported from GitHub When you [import from GitHub](https://git.pkgforge.dev/docs/migrate-from-github), no accounts are created. A GitHub user whose GitHub account is linked to a Githome account (under **Settings → Linked accounts**, matched by GitHub's numeric user id) is credited to that account. Everyone else becomes a **mannequin**: a placeholder that carries their issues, comments and reviews under their GitHub login, with a **GitHub** badge in the web UI and `"type": "Mannequin"` and a `github:` login in the API. A mannequin isn't an account: it can't sign in or act. Imported reviews, whoever wrote them, are history and never count as approvals. See [People: linked accounts and mannequins](https://git.pkgforge.dev/docs/migrate-from-github#people-linked-accounts-and-mannequins). ## Repositories A repository holds a project's Git history plus its issues, pull requests, reviews, checks, releases, deployment environments, workflow runs, webhooks, secrets and variables. It lives at `https://git.pkgforge.dev//` (for example `https://git.pkgforge.dev/acme/website`) and is cloned from the same URL with `.git` appended. New repositories use `main` as the default branch unless you choose otherwise. A repository made on the web or with `githome repo create` is private unless you choose otherwise, and one made with the REST API is public unless the request asks for private, as on GitHub. A repository can be renamed, or transferred to your own account or to an organization you own or administer. Its old URLs keep working, as on GitHub: web pages and the REST API redirect, and Git, MCP and container images are served under the old name, for anyone who can still read it. To move from GitHub, the server-side importer copies a repository, or every repository of an organization, with its history, issues and pull requests (keeping their numbers), comments, reviews, labels, milestones, releases, branch protection, variables and environments. Secret values are never copied, only their names. Start it from **Settings → Imports**, `githome migrate github`, the REST API or MCP. See [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github). A person who can read a repository can fork it (`gh repo fork`): the fork holds its own copy of the objects, and `gh repo sync` brings its branches up to their upstream. A pull request is between two branches of a repository, or from a branch of a fork: someone who can only read a repository forks it, pushes a branch to the fork and opens the pull request. Repositories can carry topics, and any branch, tag or commit can be downloaded as a `.zip` or `.tar.gz` source archive. Code is shown with syntax highlighting. See [Repositories](https://git.pkgforge.dev/docs/repositories/overview), [Browsing code](https://git.pkgforge.dev/docs/repositories/browsing-code), [Git over HTTPS](https://git.pkgforge.dev/docs/repositories/git) and [Git LFS](https://git.pkgforge.dev/docs/repositories/git-lfs). ## Visibility A repository is either **private** or **public**. | Visibility | Who can see it | | --- | --- | | Private | The owner, organization members (for organization repositories, unless the organization's base permission is `none`) and collaborators | | Public | Everyone, including people who aren't signed in. Signed-in users get `read`. | Someone without access to a private repository gets `404 repository not found`, never `403`, so its name isn't revealed. Writing to a public repository still needs a signed-in account (or a token) with a role that allows it. People who aren't signed in can only read: opening an issue, commenting, reacting or pushing without an account fails with `401 authentication required` (for a push, Git then asks for your token). See [Visibility](https://git.pkgforge.dev/docs/repositories/overview#visibility). ## Roles Every request to a repository runs with one effective role. Githome uses GitHub's five repository roles, and each one includes the ones before it: | Role | In short | | --- | --- | | `read` | View and clone; when signed in, also open issues and comment | | `triage` | Manage issues, pull requests and labels without pushing code | | `write` | Push, open and merge pull requests, run workflows | | `maintain` | Also move or delete tags, edit other people's comments and dismiss reviews | | `admin` | Settings, access, branch protection, secrets and webhooks | Your role on a repository comes from owning it, your organization role (members get the organization's base permission), a collaborator grant or the repository being public, whichever is highest. Tokens and agent limits can then only lower it. See [Permissions](https://git.pkgforge.dev/docs/accounts/permissions). ## Tokens A personal access token lets Git, the `githome` CLI, scripts and MCP clients act as you (or as an agent). Tokens start with `ghome_`, are shown once when you create them, and last 1 to 366 days (90 by default). Where the deployment sends email, Githome emails you whenever a token is created on your account. Each token has a scope that caps your role, whatever your role actually is: | Scope | Highest effective role | | --- | --- | | `read` | read | | `write` | maintain | | `admin` | admin | A `read` token can only read: it can clone and fetch, download Git LFS files, call `GET` endpoints and use the MCP tools that only read, and every change it attempts fails with `403 this token needs the write scope`. New tokens get the `write` scope unless you choose another; scopes other than `read`, `write` and `admin` are refused (`422`). Some actions belong to your account rather than to a repository, and need a minimum scope whatever your role: | Action | Token scope needed | | --- | --- | | Create a repository | `write` | | Create an organization, send invitations, manage organization secrets | `admin` | | Create or revoke tokens, create or disable agents, create agent tokens | `admin` | A token can also be restricted to a list of repositories; every other repository then answers `404` as if you had no access, and the token can't create repositories or organizations, send invitations, manage agents or create other tokens. A token can only be restricted to repositories your account can see. Browser sessions aren't capped, so in the web UI you always act with your full role. Unlike GitHub's fine-grained tokens, there are no per-permission settings: the scope and the repository list are the whole model. Use a token as the Git password (with any username), as `Authorization: Bearer ghome_...` for the API and MCP, or let `githome login` and `githome auth setup-git` store it. See [Personal access tokens](https://git.pkgforge.dev/docs/accounts/tokens). ## Job tokens > The forge CI of git.pkgforge.dev is dormant: no Actions run, hosted job, agent sandbox, task or terminal starts there now. The sections on job tokens, Actions, runners, environments and sandboxes describe the code that stays in githome. Each workflow job gets a short-lived job token as `GITHUB_TOKEN` (also `GITHOME_TOKEN`). It starts with `ghomejt_`, acts as `githome-actions[bot]` on the repository the job runs in (it can also read other public repositories) and stops working when the job completes. As on GitHub, the token can do what the workflow's `permissions:` grant (`contents`, `issues`, `pull-requests`, `statuses`, `packages` and so on), and an endpoint it lacks the permission for answers `403 Resource not accessible by integration`. Without `permissions:`, a job gets the repository's default, which for new repositories is GitHub's restricted one (`contents` and `packages` read); a repository admin can change it (see [Workflow permissions](https://git.pkgforge.dev/docs/actions/workflow-permissions)). The token never acts above `write`, so branch protection applies; it never changes repository settings, secrets or workflow files; it can't open or approve pull requests unless the repository allows it, and its approvals never count; and a run whose code came from an agent acts as that agent. Sandboxes get a similar token starting with `ghomest_` (see [Sandboxes](#sandboxes)). See [Job tokens and sandbox tokens](https://git.pkgforge.dev/docs/accounts/permissions#job-tokens-and-sandbox-tokens) and [Secrets and variables](https://git.pkgforge.dev/docs/actions/secrets-and-variables). ## Branch protection A branch protection rule matches branch names with a pattern such as `main`, `release/*` (one path segment) or `release/**` (any depth), and controls how matching branches can change: whether changes must go through a pull request, how many approvals and which checks are required, whether force pushes, deletion and merge commits are allowed, whether a merge queue is used, and what agents may do. The server enforces the rules for every way a branch can change, whether through `git push`, the REST API, MCP or the web UI. Required checks can be workflow jobs, check runs or commit statuses reported by other tools. When Githome Actions reports a check, it alone decides that check; to have another tool decide a required check, a rule binds the check to that reporter. See [Checks and statuses](https://git.pkgforge.dev/docs/collaboration/checks-and-statuses). Some protections apply even without any rule: the default branch can't be deleted, and agents can't push to it or merge into it. When several rules match a branch, the rule that names the branch exactly wins over patterns; otherwise the oldest matching rule applies. Repository admins can bypass the rules unless the rule sets **Do not allow administrators to bypass these rules** (`enforceAdmins`). A push by an admin bypasses them on its own. A merge doesn't: an admin has to ask for it explicitly (the **Merge without waiting for requirements (bypass)** button, `"bypass_rules": true` in the API, or `githome pr merge --admin`), and the bypass is recorded in the audit log as `pull_request.merge_bypassed`. `"bypass_rules": true` skips unmet rules, and `"bypass_merge_queue": true` skips only a required merge queue. Bypassing merge requirements is for people only, never agents, and never works for a draft or a pull request with conflicts. See [Branch protection](https://git.pkgforge.dev/docs/repositories/branch-protection) and [Merge queue](https://git.pkgforge.dev/docs/collaboration/merge-queue). ## Pull requests with intent A pull request proposes merging one branch (the head) into another (the base) of the same repository. Pull requests and issues share one number sequence per repository, as on GitHub. Besides a title and a description, every pull request can carry an **intent**: one or two sentences on what the change is meant to achieve, for example "Fix the race in token refresh without changing the public API." The intent is shown at the top of the pull request, included in notification emails and returned by the API, the CLI and MCP, so reviewers, human or AI, can check the diff against the stated goal. It can't be edited after the pull request is opened, and agents should always set it. A pull request can be opened as a **draft**: a draft can't be merged until it is marked ready for review (the **Ready for review** button, `githome pr ready`, or `PATCH` with `"draft": false`), and it can be turned back into a draft later. Pull requests are reviewed with **Approve**, **Request changes** or comments, checked by workflow runs and other CI, and merged with a merge commit, a squash or a fast-forward rebase once nothing blocks them. With **auto-merge** turned on, Githome merges a pull request by itself as soon as nothing blocks it. See [Pull requests](https://git.pkgforge.dev/docs/collaboration/pull-requests) and [Issues](https://git.pkgforge.dev/docs/collaboration/issues). ## Actions Githome Actions runs GitHub Actions workflows from `.githome/workflows/`, or from `.github/workflows/` when a repository has no `.githome/workflows/`, on Cloudflare. On git.pkgforge.dev it is dormant, so no workflow runs there now. Most existing workflow files run unchanged; differences are listed in [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility). ### Runs, jobs and steps | Term | Meaning | | --- | --- | | Workflow | A YAML file that says when to run (`on:`) and what to run (`jobs:`). | | Event | What starts a workflow: a push, a pull request update, a merge queue group, a manual dispatch, a schedule, another workflow's run, a published release or a `repository_dispatch` API call. | | Run | One execution of one workflow for one event, with a number, a status and a conclusion. | | Job | A set of steps that runs on one runner. Jobs run in parallel unless linked with `needs`; a matrix expands one job into several. | | Step | One command (`run:`) or one action (`uses:`), run in order in the job's workspace. | | Check | The result of one job, reported on the commit as ` / `, for example `CI / test`. Branch protection can require it. | | Environment | A deployment target such as `production`, with its own secrets, variables and branch policy. A job with `environment:` gets them only if the policy allows the ref. | Runs are orchestrated durably, so they survive platform restarts, and a job can run for at most 6 hours. See [Actions overview](https://git.pkgforge.dev/docs/actions/overview), [Workflow syntax](https://git.pkgforge.dev/docs/actions/workflow-syntax) and [Events that trigger workflows](https://git.pkgforge.dev/docs/actions/events). ### Runners A runner is the machine that executes one job. You pick one per job with `runs-on`: - **Hosted runners** would run each job in a fresh container on Cloudflare, with `runs-on: ubuntu-latest` and similar labels. They are dormant on git.pkgforge.dev. - **Self-hosted runners** run jobs on a machine you control, such as a Mac, a GPU box or a server on a private network. You start one with `githome runner`, and jobs with `runs-on: self-hosted` (plus any other labels) go to it. See [Runners](https://git.pkgforge.dev/docs/actions/runners). ## Checks and commit statuses A check is a pass or fail result attached to a commit. Githome Actions reports one check per job. Other tools report results over the GitHub-compatible REST API, either as **commit statuses** (a state and a context name, such as `ci/external`) or as **check runs**. All of them appear together on the commit and the pull request, and branch protection can require any of them by name. See [Checks and statuses](https://git.pkgforge.dev/docs/collaboration/checks-and-statuses). ## Releases A release marks a tag as a version you ship, with a title, Markdown release notes and downloadable files (assets, up to 100 MB each). Releases can be drafts or pre-releases, one of them is the latest, and notes can be generated from the merged pull requests. Each release page also links to source archives of its tag. Publishing a release starts `on: release` workflows and sends a `release` webhook. Manage releases at `https://git.pkgforge.dev/acme/website/releases`, with the REST API or with the MCP release tools. See [Releases](https://git.pkgforge.dev/docs/collaboration/releases). ## Environments and deployments An environment, such as `staging` or `production`, groups the secrets and variables a deployment needs with a policy for which branches and tags may deploy to it. A workflow job that names an environment (`environment: production`) creates a deployment, gets that environment's secrets and variables, and is refused if the policy doesn't allow its ref. Environment secrets never reach pull request runs. Tools outside Actions can record deployments and their status through the REST API, as on GitHub. Environments are managed with the REST API by repository admins. See [Environments](https://git.pkgforge.dev/docs/actions/environments). ## Sandboxes A sandbox is a short-lived Linux container with a repository already cloned into it, which you drive over MCP or the REST API: run shell commands, read and write files, and push with Git. Agents use sandboxes to build and test changes without a machine of their own. Creating one is refused on git.pkgforge.dev with "CI is off on this deployment". Creating a sandbox needs write access. Inside it, Git authenticates as whoever created it with at most `write`, so branch protection, push protection and agent guardrails apply to its pushes like any other. A sandbox stops after 30 minutes without calls and keeps no files, so commit and push what you want to keep. GitHub has no built-in equivalent. See [Sandboxes](https://git.pkgforge.dev/docs/agents/sandboxes). ## Push protection Every `git push` is scanned for leaked credentials such as API keys and private keys, and so is every commit made without Git: in the web editor, through the REST API (`POST /repos/{owner}/{repo}/githome/commits` and the contents and git data APIs) and with the MCP `commit_files` tool. A push or commit that contains one is rejected and nothing from it is stored. A repository admin who is a person can push anyway with `git push -o allow-secrets=`, or commit through the commits API with `allow_secrets`, which is recorded in the audit log. See [Push protection](https://git.pkgforge.dev/docs/security/push-protection) and [Security overview](https://git.pkgforge.dev/docs/security/overview). ## Audit log The audit log is an append-only record of security-relevant actions: sign-ins, passkey and token changes, repository settings (whether changed on the web or through the API), pushes, force pushes, merges, push protection decisions and package changes. When an agent acts, the entry names both the agent and the account it acts for. Only the superadmin can view it, on the page **Audit log** of the dash, which shows the 200 most recent entries. See [Audit log](https://git.pkgforge.dev/docs/security/audit-log). ## Notifications Githome tells you about activity in the notifications list (the bell in the header, `/notifications`) and by email, following GitHub's rules: you hear about issues and pull requests you take part in, everything in repositories you watch with **All activity**, and failed workflow runs you started. Security emails, such as a new token or a new sign-in, are always sent. Each repository has a **Watch** menu (**Participating and @mentions**, **All activity**, **Ignore**), each issue and pull request a **Subscribe** button, and **Settings → Notifications** turns each group on or off. Agents have no notification settings. See [Notifications](https://git.pkgforge.dev/docs/accounts/notifications). ## Where to go next - [Quickstart](https://git.pkgforge.dev/docs/quickstart): try these concepts end to end in about 15 minutes. - [Releases](https://git.pkgforge.dev/docs/collaboration/releases), [Environments](https://git.pkgforge.dev/docs/actions/environments) and [Checks and statuses](https://git.pkgforge.dev/docs/collaboration/checks-and-statuses). - [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github): import repositories or whole organizations, link your GitHub account, and set secrets again. - [REST API](https://git.pkgforge.dev/docs/reference/rest-api), the [CLI reference](https://git.pkgforge.dev/docs/reference/cli) and the [MCP tool reference](https://git.pkgforge.dev/docs/reference/mcp-tools). - [Limits](https://git.pkgforge.dev/docs/reference/limits): sizes, timeouts and quotas in one place. --- # Guides > Short, task-focused guides to common jobs on Githome: moving GitHub Actions workflows, faster CI, releases with release-please, and AI coding agents with guardrails. Source: https://git.pkgforge.dev/docs/guides Each guide answers one question in a few steps and links to the pages that cover the details. | Guide | What it covers | | --- | --- | | [Move your GitHub Actions workflows to Githome](https://git.pkgforge.dev/docs/guides/move-github-actions-workflows) | What runs unchanged, runner labels and sizes, marketplace actions, secrets, caches, Docker, OIDC, environments, self-hosted runners for macOS, Windows and Arm, and a checklist. | | [Make your CI faster on Githome](https://git.pkgforge.dev/docs/guides/faster-ci) | Runner sizes and automatic sizing, caching, setup and Docker head starts, matrices, cancelling superseded runs. | | [Automate versions and releases with release-please](https://git.pkgforge.dev/docs/guides/release-please) | The release-please action and CLI on Githome: the workflow, permissions, CI on release pull requests and troubleshooting. | | [Give an AI coding agent its own account, with guardrails](https://git.pkgforge.dev/docs/guides/ai-agent-with-guardrails) | Create an agent and its token, what the server enforces, connecting Claude Code, Codex or any MCP client, reviewing and merging agent pull requests, and auditing what agents did. | Other task pages: [Quickstart](https://git.pkgforge.dev/docs/quickstart), [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github), [Deploy to Cloudflare Workers](https://git.pkgforge.dev/docs/actions/deploy-to-cloudflare-workers), [Merge on green automatically](https://git.pkgforge.dev/docs/collaboration/merge-on-green) and [Cloud agent environments](https://git.pkgforge.dev/docs/connect/cloud-agents). --- # Move your GitHub Actions workflows to Githome > Run your existing .github/workflows files on Githome: what runs unchanged, runner labels and sizes, secrets, caches, Docker, OIDC, environments, and what to change. Source: https://git.pkgforge.dev/docs/guides/move-github-actions-workflows > **Note:** The forge CI of git.pkgforge.dev is dormant: githome reads and validates workflow files, but starts no run, so a workflow does not run there now. This guide says what holds for the files, and what a deployment with the CI on would run. Most GitHub Actions workflow files are accepted by Githome without changes: Githome reads `.github/workflows/*.yml`, supports the same triggers, expressions, matrices, `needs`, caches, artifacts, secrets, OIDC and Docker, and downloads marketplace actions from GitHub as they are. On a deployment with the CI on, jobs with `runs-on: ubuntu-latest` run on hosted Ubuntu 24.04 runners. What you change is usually small: set your secret values again (GitHub never reveals them), move Windows, macOS and Arm jobs to self-hosted runners, and give `GITHUB_TOKEN` the `permissions:` it needs. ## Steps 1. **Bring the repository over.** On git.pkgforge.dev the server-side import from GitHub (**Settings → Imports → Import from GitHub**, or `githome migrate github acme/website --to acme/website`) needs the import container, which is not running, so it stops at its Git step; bring the code over with the local import (`githome migrate github acme/website --local`) or a plain Git push. Where the server-side import runs, the importer copies the history (workflow files included), issues, pull requests, branch protection, Actions variables, environments and the names of your secrets. The import starts no workflow runs; with the CI on, your first push does. See [Migrate from GitHub](https://git.pkgforge.dev/docs/migrate-from-github). 2. **Set your secret values.** The import lists every secret name, but never a value. A person who is a repository admin enters each one: **Set secret values** on the import's page, `githome secret set NPM_TOKEN -R acme/website`, or the REST API. Do this before your first push, because that push starts the workflows. See [Set secret values](https://git.pkgforge.dev/docs/migrate-from-github#set-secret-values). 3. **Check the workflow files.** Run `githome workflow validate .github/workflows/ci.yml` on each file. Errors fail the file; warnings name keys that are accepted but ignored. 4. **Fix `runs-on` where needed.** `ubuntu-*` labels run on hosted runners. Windows, macOS and Arm jobs need a self-hosted runner (see [Runners and runner sizes](#runners-and-runner-sizes)). 5. **Add `permissions:` where a job writes.** In repositories created on Githome, imported ones included, the job token can only read code and packages by default. A job that comments, labels, pushes, tags or publishes needs a `permissions:` block, for example `contents: write` or `pull-requests: write`, or an admin sets the repository default to write. See [Workflow permissions](https://git.pkgforge.dev/docs/actions/workflow-permissions). 6. **Push a commit and watch the first runs** on the **Actions** tab, or with `githome run list` and `githome run watch ` (on a deployment with the CI on; on git.pkgforge.dev no run starts now). Fix what fails using the sections below. ## What runs unchanged - **Triggers:** `push`, `pull_request`, `pull_request_target`, `merge_group`, `workflow_dispatch`, `schedule`, `workflow_run`, `release`, `repository_dispatch` and `workflow_call`. See [Events that trigger workflows](https://git.pkgforge.dev/docs/actions/events). - **Workflow syntax:** expressions and contexts, matrices with `include` and `exclude`, `needs`, job outputs, `if` conditions, `concurrency`, job summaries, environment files and workflow commands. See [Workflow syntax](https://git.pkgforge.dev/docs/actions/workflow-syntax). - **Reusable workflows**, as long as they live on the same Githome instance and the calling job has no matrix. See [Reusable workflows](https://git.pkgforge.dev/docs/actions/reusable-workflows). - **Workflows in `.github/workflows/`.** Githome also reads `.githome/workflows/`, for workflows that should only run on Githome. ## Runners and runner sizes | `runs-on` | On Githome | | --- | --- | | `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04`, any other `ubuntu-*` label, `linux`, `x64` | A hosted Ubuntu 24.04 x64 container, fresh for each job | | `githome-tiny`, `githome-small`, `githome-medium`, `githome-large` | A hosted runner of that size | | `windows-*`, `macos-*` | Fails: there are no Windows or macOS hosted runners | | `ubuntu-24.04-arm` and other Arm labels | Runs on the same x64 image; there are no hosted Arm runners | | `[self-hosted, ...]` | A machine you connect with `githome runner`, matched on every label | A job without a size label gets the **large** size (4 vCPU, 12 GiB of memory, 20 GB of disk), unless its own earlier runs show that a smaller size serves it just as well. Add a label such as `runs-on: [ubuntu-latest, githome-small]` to pin a size. See [Runner sizes](https://git.pkgforge.dev/docs/actions/runners#runner-sizes). The hosted image is smaller than GitHub's. It has Git, Git LFS, curl, jq, build-essential, Python 3.12, Node.js 26 with npm, pnpm and yarn, Docker and `gh`. Go, Java, Ruby, Rust, .NET, PowerShell, browsers and cloud CLIs aren't preinstalled: install them with a setup action or `apt-get`. The apt package lists are removed, so run `apt-get update` before `apt-get install`. See [The Ubuntu 24.04 image](https://git.pkgforge.dev/docs/actions/runners#the-ubuntu-2404-image). **macOS, Windows, Arm and GPU jobs** run on a [self-hosted runner](https://git.pkgforge.dev/docs/actions/runners#self-hosted-runners): a repository admin creates a registration token, and you start `githome runner` on your machine with labels such as `--labels macos,arm64`. Jobs with `runs-on: [self-hosted, macos, arm64]` then go to it. On Windows, the documented route is to run the runner inside WSL 2. See [macOS, Windows and GPU machines](https://git.pkgforge.dev/docs/actions/runners#macos-windows-and-gpu-machines). ## Marketplace actions Any `uses: owner/repo@ref` is downloaded from GitHub when the step runs, so marketplace actions keep working. JavaScript actions (they run on the runner's own Node.js, 26 on a hosted runner), composite actions and Docker container actions are all supported. - `actions/checkout`, `actions/setup-node`, `actions/setup-python`, `actions/setup-go`, `actions/cache`, `actions/upload-artifact` and `actions/download-artifact` are built into the runner for speed, for the version ranges listed in [Built-in actions](https://git.pkgforge.dev/docs/actions/compatibility#built-in-actions). For other versions or inputs, the real action runs. - `actions/github-script` works with the REST API (`github.rest.*`); `github.graphql` doesn't, because the job token can't use Githome's GraphQL API yet. - Actions in **private GitHub repositories** can't be downloaded on hosted runners. Move them into a Githome repository and use them as local actions. See [Actions stored on Githome](https://git.pkgforge.dev/docs/actions/compatibility#actions-stored-on-githome). - `uses: acme/my-action@v1` always means the repository on GitHub, not on Githome. ## Secrets and variables - **Values come from people.** The importer copies repository variables with their values, and only the **names** of repository, environment and organization secrets. A repository admin who is a person sets each secret's value. Agents can't set secrets or variables anywhere. - **Where to set them:** repository secrets on **Settings → Secrets and variables** or with `githome secret set`; organization secrets with `githome secret set NAME --org acme`; environment secrets with the REST API. - **Pull request runs get secrets.** Every pull request comes from a branch of the same repository (there are no forks), so `pull_request` runs receive the repository's secrets. Runs of code an agent wrote don't, unless an admin allows it. See [Which runs receive secrets](https://git.pkgforge.dev/docs/actions/secrets-and-variables#which-runs-receive-secrets). - **Tools that encrypt secrets first** (GitHub's sealed-box `encrypted_value`) don't work: send the plain `value` over HTTPS; it's encrypted at rest. See [Secrets and variables](https://git.pkgforge.dev/docs/actions/secrets-and-variables). ## Caches and artifacts `actions/cache`, `actions/upload-artifact` and `actions/download-artifact` work as on GitHub, and the built-in versions share their storage and formats with the official actions. Caches are scoped per ref with the same fallbacks to the base branch and the default branch, each repository keeps up to 10 GB of caches, and artifacts are kept for up to 90 days. The `cache` input of the setup actions works too. See [Caching and artifacts](https://git.pkgforge.dev/docs/actions/caching-and-artifacts). ## Docker Job containers, service containers, Docker container actions, `docker build`, `docker run` and `docker compose` work on hosted runners, and so do `docker/setup-buildx-action`, `docker/login-action` and `docker/build-push-action`. The Docker daemon starts on first use, and Docker Hub images are pulled through the `mirror.gcr.io` mirror. If you publish images to `ghcr.io`, push them to the registry at `git.pkgforge.dev` instead, signed in with the job's `GITHUB_TOKEN` and `packages: write`. See [Docker in workflows](https://git.pkgforge.dev/docs/actions/docker) and [Migrating from ghcr.io](https://git.pkgforge.dev/docs/packages/container-registry#migrating-from-ghcrio). ## OIDC OIDC works with `permissions: id-token: write`, with `https://git.pkgforge.dev` as the issuer. In your cloud provider's trust policy, change the issuer host from `token.actions.githubusercontent.com` to `git.pkgforge.dev`, and keep your `sub` patterns unless they rely on a customized subject template. See [OpenID Connect (OIDC)](https://git.pkgforge.dev/docs/actions/oidc#differences-from-github). ## Environments The importer creates your environments with their deployment branch policies and variables, and lists their secret names. Then: - Set environment secrets with the REST API, as a repository admin who is a person. See [Environments and their secrets](https://git.pkgforge.dev/docs/migrate-from-github#environments-and-their-secrets). - Set required reviewers and wait timers again under **Settings → Environments**, with Githome people. They don't come across. See [Required reviewers and wait timers](https://git.pkgforge.dev/docs/actions/environments#required-reviewers-and-wait-timers). - Pull request runs never get environment secrets. Keep production credentials in an environment limited to protected branches. ## What doesn't work The full list, with error messages, is in [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility). The differences you're most likely to meet: - No hosted Windows, macOS or Arm runners, no larger runners above 4 vCPU and no runner groups (`group` is ignored). - Events other than the ten listed above (`issues`, `issue_comment`, `pull_request_review` and the rest) parse but never start a run. - A matrix on a job that calls a reusable workflow isn't supported yet. - `github.graphql` in `actions/github-script` fails. - Problem matchers aren't supported, and annotations show in the job log only. - The `cmd` shell isn't supported, and hosted runners have no PowerShell. - Hard-coded `github.com` and `api.github.com` URLs point at GitHub: use `${{ github.server_url }}` and `${{ github.api_url }}`. ## Checklist 1. Import the repository (or push it) and read the import's warnings. 2. Set every secret value listed by the import, including environment and organization secrets. 3. Run `githome workflow validate` on every workflow file. 4. Replace `windows-*`, `macos-*` and Arm labels with `[self-hosted, ...]` labels and start a runner, or move the job to Linux. Check `matrix.os` values used in `runs-on`. 5. Add `apt-get update` before `apt-get install`, and install tools the hosted image doesn't have. 6. Add `permissions:` to jobs that write with `GITHUB_TOKEN`. 7. Move actions from private GitHub repositories into Githome and use them as local actions. 8. Replace `ghcr.io` with your instance's host (`git.pkgforge.dev` here), and hard-coded GitHub URLs with `github.server_url` and `github.api_url`. 9. Update OIDC trust policies to the `https://git.pkgforge.dev` issuer. 10. Set environment secrets, required reviewers and wait timers. 11. Check the required check names under **Settings → Branch protection** (they're ` / `, such as `CI / test`). 12. Push and watch the first runs. ## Frequently asked questions ### Do my GitHub Actions workflows run unchanged on Githome? Most do. Githome reads `.github/workflows/` and supports the same syntax, triggers, expressions, matrices, caches, artifacts, secrets, OIDC and Docker. Jobs that need Windows, macOS or Arm, actions from private GitHub repositories, or `github.graphql` need changes. See [Compatibility with GitHub Actions](https://git.pkgforge.dev/docs/actions/compatibility). ### Does Githome copy my GitHub secrets? It copies their names, never their values: GitHub doesn't reveal secret values, and the importer doesn't try. A repository admin who is a person sets each value on Githome, from the import's **Set secret values** page, the CLI or the API. ### Can I run macOS or Windows jobs on Githome? Not on hosted runners: they are Linux only. Run them on your own machine with a self-hosted runner (`githome runner`) and `runs-on: [self-hosted, ...]` labels. ### Do marketplace actions work on Githome? Yes. Githome downloads `uses: owner/repo@ref` actions from GitHub when the step runs. JavaScript, composite and Docker container actions are supported. Actions in private GitHub repositories can't be downloaded on hosted runners. --- # Make your CI faster on Githome > Speed up workflows on Githome Actions: runner sizes and auto-sizing, caching, setup and Docker head starts, matrices, and cancelling superseded runs, and the settings that decide each. Source: https://git.pkgforge.dev/docs/guides/faster-ci > **Note:** The forge CI of git.pkgforge.dev is dormant: githome reads and validates workflow files, but starts no run, so nothing here speeds up a run on that host now. What follows holds for workflow files and for a deployment that turns the CI on. On Githome with the CI on, a hosted job gets 4 vCPUs and 12 GiB of memory by default, and the common setup actions are built into the runner, so many workflows are fast without changes. To go further: let CPU-heavy jobs use all four cores, cache dependencies with keys that the default branch saves, use the Node.js and Python versions the image already has, split long jobs into parallel jobs with `needs` and matrices, and turn on cancelling of superseded pull request runs, which is off by default. Every job's log says how much CPU, memory and disk it used, so you can see where the time goes. ## Steps 1. **Read what a job used.** The last lines of each hosted job's log show its usage, for example `Resources: 0.1 of 4 vCPUs busy on average (0.3 at the 95th percentile), peak memory 0.3 GiB of 12.0 GiB, peak disk 1.6 GB of 19.3 GB`, and a line near the top names the runner size it got and why. The jobs API returns the same as `usage` and `runner_size`. 2. **Keep CPU-heavy jobs on the large size.** It's the default, and automatic sizing keeps builds and test suites there. Pin it with `runs-on: githome-large` if you want to be sure (see [How runner sizing works](#how-runner-sizing-works)). 3. **Cache dependencies** with the `cache` input of the setup actions or with `actions/cache`, keyed on your lock file (see [Caching](#caching)). 4. **Use the toolchains the image has**, and let Go, Java and Docker start early (see [Setup actions and head starts](#setup-actions-and-head-starts)). 5. **Run jobs in parallel.** Split a long job into jobs that `needs` only what they depend on, and spread tests over a matrix (see [Matrices and parallel jobs](#matrices-and-parallel-jobs)). 6. **Stop runs nobody will look at.** Add a `concurrency` group that cancels a pull request's older runs, and path filters for changes that don't need CI (see [Cancel superseded runs](#cancel-superseded-runs)). 7. **Re-run only what failed.** **Re-run failed jobs** on the run page (or `githome run rerun --failed`) runs the failed jobs and the jobs that depend on them, and keeps the rest from the earlier attempt without starting a runner. See [Re-run a run](https://git.pkgforge.dev/docs/actions/overview#re-run-a-run). ## How runner sizing works Hosted runners come in four sizes. Every size runs the same Ubuntu 24.04 image, so a job behaves the same on each. | Size | `runs-on` label | vCPU | Memory | Disk | | --- | --- | --- | --- | --- | | large (default) | `githome-large` | 4 | 12 GiB | 20 GB | | medium | `githome-medium` | 2 | 8 GiB | 16 GB | | small | `githome-small` | 1/2 | 4 GiB | 8 GB | | tiny | `githome-tiny` | 1/4 | 1 GiB | 4 GB | - **With a size label**, for example `runs-on: [ubuntu-latest, githome-small]`, the job gets that size (with several, the largest). - **Without one**, the job gets **large**, unless its own last runs (at least 3 of up to 5) all fit a smaller size with room to spare, including room for bursts onto several cores and for slower hosts. A job that ran out of memory, failed, timed out or got slower on a smaller size goes back to large for its next 20 runs, and re-runs always run on large. So a smaller size is never the reason a job fails or slows down twice. - **Smaller sizes are about cost, not speed.** A job that mostly waits (a deploy, API calls, polling) runs just as fast on a small machine and costs less. A job that computes is fastest on large. Large is the biggest hosted size; there are no larger runners. See [Runner sizes](https://git.pkgforge.dev/docs/actions/runners#runner-sizes) and [What hosted jobs cost](https://git.pkgforge.dev/docs/actions/runners#what-hosted-jobs-cost-and-keeping-it-low). ## Caching Githome's cache service works with the official `actions/cache` and with the built-in version, which downloads an archive in parallel ranges and extracts it while it arrives. The simplest cache is the `cache` input of a setup action: ```yaml - uses: actions/setup-node@v4 with: node-version: 22 cache: pnpm ``` `actions/setup-python` takes `cache: pip` or `pipenv`, and `actions/setup-go` caches by default. For anything else, use `actions/cache` with a key that changes when your lock file does: ```yaml - uses: actions/cache@v4 with: path: ~/.npm key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }} restore-keys: | npm-${{ runner.os }}- ``` Things that make caches hit more often: - **Let the default branch save caches.** A run reads entries saved on its own ref, then (for pull requests) the base branch, then the default branch. Entries saved on one feature branch are never visible to another. - **Include a hash of the lock file in the key.** Entries are immutable: a save with an existing key is skipped, so a key that never changes never refreshes. - **Use `save-always: true`** if failing jobs should still save, since the post step saves only after a successful job by default. - **Cache Docker layers** with `cache-from: type=gha` and `cache-to: type=gha` in `docker/build-push-action`, or with `type=registry` in the [container registry](https://git.pkgforge.dev/docs/packages/container-registry). `type=gha` in a plain `docker buildx build` step doesn't work, because `run:` steps don't get the cache service credentials. Each repository keeps up to 10 GB of caches, and entries no job restored for 7 days are deleted. See [Caching and artifacts](https://git.pkgforge.dev/docs/actions/caching-and-artifacts). ## Setup actions and head starts - **Node.js 26.7.0 and Python 3.12 are preinstalled.** When the version you ask `actions/setup-node` or `actions/setup-python` for is satisfied by them, the step uses them without a download. Any other version is downloaded each time. - **Go and Java start installing as the job begins.** When a job has `actions/setup-go` (v4 to v6) or `actions/setup-java` (v2 to v5, `distribution: temurin`, a major version such as `java-version: 21`), and the version is written in the workflow or comes from `matrix`, `inputs` or `vars`, the runner downloads that toolchain while checkout runs. Versions read from a file (`go-version-file`, `java-version-file`) and jobs that run in a `container:` install the usual way, as the step runs. - **Docker starts early for jobs that use it.** A job with `container:`, `services:`, a `docker://` action, or a step whose `uses:` or `run:` names `docker` gets the Docker daemon started in the background as the job begins. A `docker` command as the job's very first step waits for the daemon to finish starting. - **Other toolchains** (Ruby, Rust, .NET, browsers) aren't in the image and install as their step runs, so cache what they download. See [The Ubuntu 24.04 image](https://git.pkgforge.dev/docs/actions/runners#the-ubuntu-2404-image) and [Built-in actions](https://git.pkgforge.dev/docs/actions/compatibility#built-in-actions). ## Matrices and parallel jobs Jobs without `needs` between them run at the same time, each in its own container, and a job starts as soon as the jobs it needs have finished. A matrix turns one job into several: ```yaml jobs: test: runs-on: ubuntu-latest strategy: matrix: shard: [1, 2, 3, 4] steps: - uses: actions/checkout@v4 - run: npm ci - run: npm test -- --shard=${{ matrix.shard }}/4 ``` - An account runs up to 20 hosted jobs at once by default, across all its repositories; further jobs wait in line, oldest first. If a large matrix often waits, cap it with `strategy.max-parallel`. - A matrix may produce at most 256 jobs, and a run at most 1,000. - With `fail-fast` (the default), one failed leg cancels its unfinished siblings, so you hear about a failure sooner. See [strategy](https://git.pkgforge.dev/docs/actions/workflow-syntax#strategy) and [Limits](https://git.pkgforge.dev/docs/reference/limits). ## Cancel superseded runs As on GitHub, a new push to a pull request doesn't cancel the run for the commit before it. Githome doesn't turn this on for you, because cancelling can cut off a deploy halfway or turn an older commit's checks into "cancelled". To opt in for pull requests only, add this to the workflow: ```yaml concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} ``` Older runs of the same pull request are cancelled when a new commit arrives, and runs on your default branch finish. A run on a protected branch is only ever cancelled by runs on that same branch. See [Concurrency](https://git.pkgforge.dev/docs/actions/overview#concurrency). To skip runs entirely for changes that don't need them, use path filters on `push` and `pull_request`, for example `paths-ignore: ["docs/**", "**.md"]`. A job that doesn't run reports no check, and a required check that never reports shows as `required check '' has not run`, so be careful with path filters on workflows whose checks are required. See [Path filters](https://git.pkgforge.dev/docs/actions/events#path-filters) and [Status checks](https://git.pkgforge.dev/docs/actions/overview#status-checks-on-commits-and-pull-requests). ## Frequently asked questions ### What hardware do Githome's hosted runners have? By default, 4 vCPUs, 12 GiB of memory and 20 GB of disk, running Ubuntu 24.04 on x64 in a fresh container for each job. Smaller sizes (2, 1/2 and 1/4 vCPU) are picked per job from its own measured runs, or with a `githome-*` label. ### Does Githome cancel superseded workflow runs automatically? No. As on GitHub, older runs keep running unless the workflow has a `concurrency` group with `cancel-in-progress`. Add one with `cancel-in-progress: ${{ github.event_name == 'pull_request' }}` to cancel older pull request runs and leave default-branch runs alone. ### Can I get a runner bigger than 4 vCPUs? Not as a hosted runner: large (4 vCPU, 12 GiB) is the biggest size. For bigger machines, GPUs or long-lived caches, connect your own machine as a [self-hosted runner](https://git.pkgforge.dev/docs/actions/runners#self-hosted-runners). ### Why did my job get a smaller runner? Its last runs all fit a smaller size with room to spare, so Githome picked it to save cost. The log's `Runner size:` line says which runs it was based on. If a smaller size ever makes the job fail or slower, it goes back to large for its next 20 runs. Pin `runs-on: githome-large` to keep it on large. --- # Give an AI coding agent its own account, with guardrails > Create an agent account for Claude Code, Codex or any MCP client on Githome, connect it, and let the server keep a person in charge of protected branches, merges and secrets. Source: https://git.pkgforge.dev/docs/guides/ai-agent-with-guardrails On Githome, an AI coding agent gets an account of its own, separate from yours: you create it under **Settings → Agents**, give it a token (or let Claude Code or Codex sign in as it through the browser), and its commits, pull requests and comments show as the agent's, on your behalf. The server holds it to guardrails whatever tool it uses: it can't push to or merge into the default branch or protected branches, its pull requests need a person's approval, its own approvals and check results never count, and runs of the code it writes get none of your repository or organization secrets. Repository admins relax these rules, per branch or per repository, when you're ready, for example to let its pull requests merge by themselves once CI passes and a person approves. ## Steps 1. **Create the agent.** Go to **Settings → Agents**, enter an **Agent username** (for example `review-bot`), choose the **Owner** (you, or an organization where you're an owner or admin) and keep the **Maximum role** at **Write**. Click **Create agent**. Only people can create agents, and an organization's agent can reach only that organization's repositories. 2. **Create a token for it**, unless the agent will sign in through the browser (step 4). In the agent's row, open **Create a token for review-bot**, keep the **Scope** at **Write**, choose the **Days** (1 to 366), and click **Create token**. Copy it: it's shown once. Give it to the agent as an environment variable such as `GITHOME_TOKEN`, never in a file you commit. See [Tokens for agents](https://git.pkgforge.dev/docs/agents/overview#tokens-for-agents). 3. **Protect the default branch.** Under the repository's **Settings → Branch protection**, add a rule for `main` with **Require a pull request before merging**, at least one **Required approvals**, and your CI checks under **Required status checks**. Agents can't push to the default branch either way; the rule makes sure every change is reviewed and tested. See [Branch protection](https://git.pkgforge.dev/docs/repositories/branch-protection). 4. **Connect the agent** (see [Connect Claude Code, Codex or another MCP client](#connect-claude-code-codex-or-another-mcp-client)). 5. **Tell it how to work**, for example in your agent instructions file: work on a new branch, open a pull request with an `intent` that states the goal, wait for checks with `githome pr checks --watch`, and fix failures before asking for review. 6. **Review and merge its pull requests**, by hand or with merge on green (see [Review and merge agent pull requests](#review-and-merge-agent-pull-requests)). ## What the server enforces These rules hold for Git pushes, the REST API, MCP tools and sandboxes alike, whatever the agent's role: | Rule | What it means | | --- | --- | | Never more access than its owner | Its role is the lowest of its maximum role (write by default), its owner's role on the repository and its token's scope. | | No pushes to the default branch or protected branches | Pushes and commits there fail with `agents may not push to protected or default branches; open a pull request`. It pushes other branches freely. | | No merges into the default branch or protected branches | The merge blocker reads `agents may not merge into this branch; a human must merge`. | | A person approves its pull requests | At least one approval from a person, even on a branch with no rule. An agent's approval never counts; its requested changes still block. | | Its check results don't count | Commit statuses and check runs an agent reports never satisfy a required check, so it can't mark its own work as passing. | | No secrets for runs of its code | A workflow run whose code came from an agent gets no repository or organization secrets, only its job token, and its token is held to the same rules. Environment secrets reach it only from environments limited to protected branches, and never on pull request refs. | | No settings that guard the repository | It can't change branch protection, secrets, variables or environments, dismiss reviews, delete or transfer repositories, or create other agents. | | No push protection bypass | A push or commit containing something that looks like a credential is always refused. | | Stamped commits | Commits Githome writes for it carry a `githome-agent review-bot on-behalf-of diffy` header. | The full table, with how to relax each rule, is in [Guardrails](https://git.pkgforge.dev/docs/agents/overview#guardrails). ## Connect Claude Code, Codex or another MCP client Every app connects to the same MCP server, `https://git.pkgforge.dev/mcp`. Apps with browser sign-in need no token: on Githome's consent page, choose to **act as** your agent, and Write access. - **Claude Code:** install the CLI and run `githome setup`, then run `claude mcp add --scope user --transport http githome https://git.pkgforge.dev/mcp`. In Claude Code, run `/mcp`, select **githome**, choose **Authenticate**, and pick the agent on the consent page. See [Claude Code](https://git.pkgforge.dev/docs/connect/claude-code). - **Codex:** run `githome setup`, then `codex mcp add githome --url https://git.pkgforge.dev/mcp` and `codex mcp login githome`, and pick the agent on the consent page. See [Codex](https://git.pkgforge.dev/docs/connect/codex). - **Cursor, VS Code and other MCP apps:** add `https://git.pkgforge.dev/mcp` as a remote HTTP server and sign in. See [Other apps](https://git.pkgforge.dev/docs/connect/other-apps). - **Headless (CI, scripts, scheduled jobs):** send the agent's token instead. For Claude Code: ```sh claude mcp add --scope user --transport http githome https://git.pkgforge.dev/mcp \ --header 'Authorization: Bearer ${GITHOME_TOKEN}' ``` `githome mcp-config` prints a snippet for other clients. See [Headless use](https://git.pkgforge.dev/docs/connect/how-sign-in-works#headless-use). - **Git and the CLI:** with `GITHOME_TOKEN` set, `githome auth setup-git` lets Git push with it, and `githome auth setup-gh` makes `gh pr create` and `gh pr checks` work against Githome. See [GitHub CLI](https://git.pkgforge.dev/docs/agents/github-cli). Ask the agent "Who am I on Githome?" to check: the `whoami` tool answers with the agent's login. **Cloud environments.** For a Claude Code cloud environment, or any other agent sandbox, open the repository's **Settings → Agent setup** and choose **Generate agent token**. It makes an agent that can reach only that repository and gives you the allowed domain, a one-line setup script and the environment variables to paste. A **Check** turns green once a session has set itself up. See [Cloud agent environments](https://git.pkgforge.dev/docs/connect/cloud-agents). ## Review and merge agent pull requests - **Find what needs you.** [Today](https://git.pkgforge.dev/docs/agents/today), the first page after signing in, lists **Agent PR needs a person's approval** for agent pull requests no person has approved at their latest commit. - **Read the intent first.** Every pull request can carry an `intent`, one or two sentences on what the change is meant to do, shown at the top so you can check the diff against it. See [Pull requests](https://git.pkgforge.dev/docs/collaboration/pull-requests). - **Approve, then merge.** You (or anyone with write access other than the agent) approve. The agent's owner can approve, because the owner is a different account from the agent. - **Let it merge on green.** An admin opens the repository's **Settings → Merge on green**, ticks the checks that must pass and the agents, and chooses whether agents' pull requests merge **Once the checks pass and a person approved** or **As soon as the checks pass**. Each agent pull request then merges by itself when its conditions are met. See [Merge on green automatically](https://git.pkgforge.dev/docs/collaboration/merge-on-green). - **Or allow auto-merge per branch.** **Allow agents to land pull requests through auto-merge** on a branch's rule (with at least one required check) lets the agent turn on auto-merge for its own pull requests (`enable_auto_merge` over MCP, or `githome pr merge --auto`). Githome merges once every rule is met; if the agent pushes again, a person approves again. See [Agents landing changes](https://git.pkgforge.dev/docs/repositories/branch-protection#agents-landing-changes). - **Workflow changes always need a person.** A pull request that adds, changes or deletes a workflow file never lands through an agent's auto-merge: CI can't vouch for a change to itself. - **Plan for deploys after agent merges.** The forge CI of git.pkgforge.dev is dormant, so no workflow runs there now; where CI runs, a merge that auto-merge makes for an agent is the agent's push, so later runs on that branch are runs of agent code and get no repository or organization secrets. Keep deploy credentials in an environment limited to protected branches, or have an admin turn on **Give runs of agent code the repository's and organization's secrets**. See [Which runs receive secrets](https://git.pkgforge.dev/docs/actions/secrets-and-variables#which-runs-receive-secrets). Agent review and agent tasks run in a sandbox, which is dormant on git.pkgforge.dev; their pages are [Agent review](https://git.pkgforge.dev/docs/agents/review) and [Agent tasks](https://git.pkgforge.dev/docs/agents/tasks). ## Audit what agents did - **On every item:** agents have an `agent` badge and `on behalf of ` next to their name on pull requests, reviews, comments and workflow runs, and the API returns `"type": "Bot"` for them. - **In Git:** commits Githome writes for an agent carry the `githome-agent ... on-behalf-of ...` header, covered by the commit's SHA. See it with `git cat-file -p `. - **Its tokens:** **Settings → Agents** lists each agent's tokens with their scope and last use, and a **revoke** link. Githome sends a security email when an agent or an agent token is created, where the deployment's email sending is set up. - **The audit log:** the superadmin sees every audited action on the page **Audit log** of the dash, with the agent as the actor and its owner alongside (`review-bot for diffy`). See [Audit log](https://git.pkgforge.dev/docs/security/audit-log). - **Cut it off:** revoke one token to stop one running copy, or **Disable** the agent under **Settings → Agents** to revoke all its tokens at once. ## Frequently asked questions ### Can an AI agent push to main on Githome? Not by default. Agents can't push to the default branch or to any protected branch; they push a branch and open a pull request. A repository admin can allow it on a branch's protection rule with **Allow agents to push directly**. ### Can an agent approve or merge its own pull request? An agent's approval never counts toward required approvals, and agents can't merge into the default branch or protected branches. A person approves its pull request. A repository admin can let agents land approved pull requests through auto-merge, so CI and a person decide rather than the agent, or waive the approval so green required checks are enough. ### Can an agent read my repository secrets? Agents can't create, change or delete secrets, and a workflow run of code an agent wrote gets no repository or organization secrets unless a repository admin turns that on. Environment secrets reach such a run only from environments limited to protected branches, and never on pull request refs. Agents with write access can read Actions variables, which aren't secret. ### Which AI coding agents work with Githome? Any agent that uses Git, the GitHub CLI, the REST API or MCP. There are guides for [Claude](https://git.pkgforge.dev/docs/connect/claude), [Claude Code](https://git.pkgforge.dev/docs/connect/claude-code), [Codex](https://git.pkgforge.dev/docs/connect/codex), Cursor and VS Code ([Other apps](https://git.pkgforge.dev/docs/connect/other-apps)). ### How do I take away an agent's access? Revoke its token under **Settings → Agents**, or click **Disable** next to the agent to revoke all its tokens at once. An app connected through the browser is disconnected under **Settings → Access tokens → Connected apps**. --- # Compatibility with GitHub Actions > What works, what works differently and what isn't supported when you run GitHub Actions workflows on Githome, with a checklist for porting workflows. Source: https://git.pkgforge.dev/docs/actions/compatibility > **Note:** The forge CI of git.pkgforge.dev is dormant. githome reads and validates workflow files, but an event starts no run, and a dispatch is refused with "CI is off on this deployment". This page is the reference for a deployment that turns the CI on. Githome runs GitHub Actions workflow files with the same syntax, triggers, expressions and actions, so most workflows run without changes. This page lists every place where Githome behaves differently, what happens when a workflow uses something that isn't supported, and a checklist for porting workflows from GitHub. ## At a glance | Area | Status on Githome | Details | | --- | --- | --- | | Workflow syntax | Supported, with a few keys accepted but ignored | [Workflow syntax](#workflow-syntax) | | Triggers | `push`, `pull_request`, `pull_request_target`, `merge_group`, `workflow_dispatch`, `schedule`, `workflow_run`, `release`, `repository_dispatch`, `workflow_call` | [Triggers](#triggers) | | Expressions and contexts | Supported, with small differences in values | [Contexts and environment variables](#contexts-and-environment-variables) | | Hosted runners | Linux x64 only (Ubuntu 24.04) | [Runners](#runners) | | Self-hosted runners | Supported, through `githome runner` | [Runners](https://git.pkgforge.dev/docs/actions/runners) | | Matrices, `needs`, outputs, job summaries | Supported | [Jobs and steps](#jobs-and-steps) | | `actions/checkout`, `actions/setup-node`, `actions/setup-python`, `actions/setup-go` | Built into the runner for speed; the real action runs for versions or inputs the built-in doesn't cover | [Built-in actions](#built-in-actions) | | `actions/cache`, `actions/upload-artifact`, `actions/download-artifact` | Built into the runner, sharing storage and formats with the official actions, which also work | [Caching and artifacts](https://git.pkgforge.dev/docs/actions/caching-and-artifacts) | | `actions/github-script` | Supported (the real action runs) | [actions/github-script](#actionsgithub-script) | | Other JavaScript, composite and Docker actions | Supported, downloaded from GitHub, with the cache and artifact runtime services. Githome keeps a copy of each one jobs use, for when GitHub is down | [Other actions](#other-actions) | | Job containers and service containers | Supported | [Docker in workflows](https://git.pkgforge.dev/docs/actions/docker) | | Reusable workflows | Supported, except a matrix on the calling job | [Reusable workflows](https://git.pkgforge.dev/docs/actions/reusable-workflows) | | Secrets and variables | Repository, organization and environment secrets and variables | [Secrets and variables](https://git.pkgforge.dev/docs/actions/secrets-and-variables) | | Environments | Supported: branch policies, required reviewers (people), wait timers, environment secrets and variables, deployments. | [Secrets, variables and environments](#secrets-variables-and-environments) | | `GITHUB_TOKEN` | Follows `permissions:` per endpoint, as on GitHub; read-only by default in new repositories | [GITHUB_TOKEN and permissions](#github_token-and-permissions) | | OIDC | Supported, with Githome as the issuer | [OIDC](https://git.pkgforge.dev/docs/actions/oidc) | | Windows and macOS hosted runners | Not available (Cloudflare Containers run Linux only); use self-hosted runners | [Runners](#runners) | ## Workflow files Githome reads workflows from `.githome/workflows/`, and from `.github/workflows/` only when the commit has no `.githome/workflows/`. Every `.yml` or `.yaml` file directly in that directory is a workflow; files in subdirectories are ignored. Put workflows that should only run on Githome in `.githome/workflows/`: then Githome runs those and no file of `.github/workflows/`, and a GitHub mirror of the repository runs only `.github/workflows/`. See [Where workflow files live](https://git.pkgforge.dev/docs/actions/overview#where-workflow-files-live). Check a workflow before you push it: ```sh githome workflow validate .github/workflows/ci.yml ``` Errors fail the file; warnings, such as `unknown job key ''` or `unknown event ''`, are printed but the workflow still runs. ## Triggers | Event | Status | Differences | | --- | --- | --- | | `push` | Supported | `commits` in the payload lists only the pushed head commit. Path filters pass when a push creates a branch. | | `pull_request` | Supported | Activity types `opened`, `synchronize`, `reopened`, `closed`, `edited`, `ready_for_review` and `converted_to_draft` only; the `edited` payload has no `changes` object. No runs while the pull request conflicts with its base. Runs get the repository's secrets, because pull requests come from branches of the same repository. | | `pull_request_target` | Supported | Same activity types as `pull_request`. Runs also while the pull request conflicts. | | `merge_group` | Supported | `checks_requested`. | | `workflow_dispatch` | Supported | `github.event.inputs` keeps the input types instead of turning them into strings. The dispatch API answers `201 Created` with the run instead of `204 No Content`. | | `schedule` | Supported | Checked every 5 minutes, so a schedule starts within about 5 minutes after it's due. Runs have the actor `githome-scheduler`. | | `workflow_run` | Supported | Activity types `requested` and `completed` (not `in_progress`), `workflows` is required, and chains go at most 3 levels deep. | | `release` | Supported | Same activity types. No runs for draft releases, as on GitHub. Without `types`, a new published release starts three runs (`created`, `published`, `released`), as on GitHub. Only `types` filters; `branches`, `tags` and `paths` aren't applied. | | `repository_dispatch` | Supported | `POST /repos/{owner}/{repo}/dispatches` answers `204`. The payload has `action`, `branch`, `client_payload`, `repository` and `sender`. | | `workflow_call` | Supported | See [Reusable workflows](https://git.pkgforge.dev/docs/actions/reusable-workflows). | | Every other GitHub event (`issues`, `issue_comment`, `pull_request_review`, `create`, `delete`, `status`, `deployment`, `deployment_status` and the rest) | Accepted, never fires | The workflow parses, but Githome never starts a run for these events. (Webhooks do get `status`, `deployment` and `deployment_status`.) | | A name that isn't a GitHub event | Warning | `unknown event ''`. | Details for each event are in [Events that trigger workflows](https://git.pkgforge.dev/docs/actions/events). ## Workflow syntax Every key of the GitHub Actions workflow syntax parses. These keys behave differently: | Key | What happens on Githome | | --- | --- | | `jobs..runs-on` | Supported, including the `matrix` context (`runs-on: ${{ matrix.os }}`), but only Linux labels are hosted. The `group` key is ignored. | | `jobs..environment` | Supported: the branch policy is enforced, the environment's secrets and variables are added and a deployment is recorded. Required reviewers and wait timers hold the job before it starts, and `url` can't use step outputs. See [environment](https://git.pkgforge.dev/docs/actions/workflow-syntax#environment). | | `jobs..snapshot` | Accepted and ignored. | | `jobs..timeout-minutes` | Default and maximum 360. Larger values are capped at 360. | | `jobs..strategy.matrix` | At most 256 jobs per matrix, and at most 1,000 jobs in a run, matrix legs and the jobs of called workflows included. | | `jobs..uses` with `strategy.matrix` | Not supported yet. The run fails with `jobs.: a matrix on a job that calls a reusable workflow is not supported yet`. | | `concurrency` (workflow level) | Same as GitHub: one run in progress and at most one waiting per group; a newer run cancels older waiting ones. After 6 hours of waiting a run starts anyway. See [Concurrency](https://git.pkgforge.dev/docs/actions/overview#concurrency). | | `defaults.run.shell`, `jobs..steps[*].shell` | `cmd` isn't supported. `pwsh` and `powershell` need PowerShell, which hosted runners don't have. | An unknown key gives a warning such as `unknown job key ''` or `unknown step key ''`, and the key is ignored. The full reference is [Workflow syntax](https://git.pkgforge.dev/docs/actions/workflow-syntax). ## Runners | `runs-on` | GitHub | Githome | | --- | --- | --- | | `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04` | Hosted Ubuntu VM | Hosted Ubuntu 24.04 container, x64. All three labels get the same image. | | `ubuntu-24.04-arm` and other ARM labels | Hosted ARM runner | No hosted ARM runners. An `ubuntu-*` ARM label runs on the same x64 image as `ubuntu-latest`. For ARM, use `[self-hosted, ...]` labels on an ARM machine. | | `windows-*`, `macos-*` | Hosted Windows or macOS VM | Not available: Cloudflare Containers run Linux only. The job fails with `No Githome runner matches runs-on: . Linux (ubuntu-*) runners are hosted; anything else needs runs-on: [self-hosted, ...] and a registered runner.` | | Larger runners and runner groups | Supported | Not available. `group` is ignored. | | `[self-hosted, ...]` | Self-hosted runner | Self-hosted runner started with `githome runner`, matched on every label. | What's different about the hosted image: - It's much smaller than GitHub's image. Git, Git LFS, curl, jq, zstd, build-essential, Python 3.12, Node.js 26 with npm, pnpm and yarn, nvm, Docker and the GitHub CLI (`gh`) are preinstalled. `ImageOS` is `ubuntu24`, as on GitHub's `ubuntu-24.04` image. Go, Java, Ruby, Rust, .NET, PowerShell, browsers and cloud CLIs aren't. See [The Ubuntu 24.04 image](https://git.pkgforge.dev/docs/actions/runners#the-ubuntu-2404-image). - Jobs run as `root`. `sudo` is installed and needs no password, as on GitHub, so `sudo` in commands keeps working. - The apt package lists are removed. Run `apt-get update` before `apt-get install`. - Every job starts in a fresh container. Nothing carries over between jobs except caches and artifacts. - `/dev/kvm` is available, so the Android emulator and other KVM tools run with hardware acceleration. The image has no udev, so leave out the "Enable KVM" udev step that GitHub's Android guides add, and install the emulator's X libraries first. See [Hardware virtualization (KVM)](https://git.pkgforge.dev/docs/actions/runners#hardware-virtualization-kvm). On self-hosted runners, `runner.os` is always `Linux`, and the setup actions download Linux builds, even on a macOS machine. See [Self-hosted runners](https://git.pkgforge.dev/docs/actions/runners#self-hosted-runners). ## Jobs and steps These work the same as on GitHub: `needs` (a job starts as soon as the jobs it needs finish), job outputs, `if` conditions, status check functions (a skipped or failed job further up the `needs` chain skips the jobs below it unless their `if` says otherwise), matrices with `include` and `exclude`, `fail-fast`, `max-parallel`, job and step `continue-on-error`, job-level `concurrency`, `timeout-minutes`, `working-directory`, environment files (`GITHUB_OUTPUT`, `GITHUB_ENV`, `GITHUB_PATH`, `GITHUB_STEP_SUMMARY`, `GITHUB_STATE`), workflow commands, job summaries, masking and debug logging with `ACTIONS_STEP_DEBUG` and `ACTIONS_RUNNER_DEBUG`. Differences: | Behaviour | GitHub | Githome | | --- | --- | --- | | Default shell for `run` | `bash -e {0}` | `bash --noprofile --norc -eo pipefail {0}`, so a failing command in a pipeline fails the step. | | `::add-matcher::` problem matchers | Turn matching output into annotations | Not supported; the line is printed as is. | | Annotations (`::error file=...`) | Shown on pull request files | Shown in the job log only. | | `::set-env` and `::add-path` | Disabled | Disabled, with the same message. | | `github.run_number` | Counts runs of one workflow | Counts runs of every workflow in the repository. | See [Expressions and contexts](https://git.pkgforge.dev/docs/actions/expressions) and [Workflow syntax](https://git.pkgforge.dev/docs/actions/workflow-syntax) for the details. ## Built-in actions For speed, the runner has its own implementation of these actions and runs it instead of downloading the action, when the step uses a version tag in the listed range: | Action | Built-in for | | --- | --- | | `actions/checkout` | `v2` to `v6` | | `actions/setup-node` | `v3` to `v7` | | `actions/setup-python`, `actions/setup-go` | `v4` to `v6` | | `actions/cache`, `actions/cache/restore`, `actions/cache/save` | `v3` to `v6` | | `actions/upload-artifact` | `v4` to `v7` | | `actions/download-artifact` | `v4` to `v8` | The built-ins mirror the official actions' inputs, outputs and storage: a cache or artifact saved by a built-in works with the official action and the other way round. A built-in steps aside, and the real action is downloaded from GitHub and run, when: - the reference isn't `vN`, `vN.N` or `vN.N.N` in the range, for example a commit SHA, a branch or a newer major version; - the step passes an input the built-in doesn't list (see the tables below); - an input has a value the built-in doesn't handle: `ssh-key` for checkout, an `architecture` other than the runner's, a `cache` value the built-in doesn't support, a PyPy or GraalPy version, or `update-environment: false` for setup-python; - the workflow, job or step `env:` sets `GITHOME_BUILTINS` to `false`, `0`, `no` or `off`; - a self-hosted runner was started with `GITHOME_DISABLE_BUILTINS=1`. ```yaml jobs: build: runs-on: ubuntu-latest env: GITHOME_BUILTINS: false # this job runs the real actions steps: - uses: actions/checkout@v4 ``` Built-in actions run on the runner, not inside a job container. In a job with `container:`, they work on the shared workspace. ### actions/checkout Checks out a repository on the same Githome instance into the workspace. | Input | Default | Notes | | --- | --- | --- | | `repository` | The workflow's repository | `owner/name` of a repository on Githome. Anything else fails with `Invalid repository ''. Expected format {owner}/{repo}.` | | `ref` | The commit that triggered the run, or the other repository's default branch | Branch, tag, full ref or 40-character commit SHA. A short SHA is treated as a branch or tag name. | | `token` | The job's token | The job's token reads the workflow's own repository (with `contents: read`) and any public repository on Githome. For another private repository, pass a personal or agent token from a secret. The job's token is only ever sent to Githome; a different `github-server-url` needs an explicit `token`. | | `fetch-depth` | `1` | `0` fetches all branches and tags with full history. | | `fetch-tags` | `false` | | | `path` | The workspace | Relative to the workspace. A path outside it fails with `Repository path '' is not under ''`. | | `clean` | `true` | Runs `git clean -ffdx` and `git reset --hard HEAD` on an existing checkout. | | `filter` | | A partial clone filter such as `blob:none`, passed to `git fetch`. Githome's git server doesn't support partial clone yet and sends everything. | | `sparse-checkout` | | Patterns, one per line. Sets up a sparse checkout and fetches with `filter: blob:none` unless you set `filter`. | | `sparse-checkout-cone-mode` | `true` | `false` uses non-cone patterns. | | `lfs` | `false` | Fetches Git LFS objects for the checked-out commit (and runs `git lfs pull` in submodules). See [Git LFS](https://git.pkgforge.dev/docs/repositories/git-lfs). | | `submodules` | `false` | `true` or `recursive`. Submodules on Githome are fetched with the same credentials. A failed submodule update fails the step. | | `persist-credentials` | `true` | Writes the token into the repository's local Git config at the end, so later `git` commands authenticate. A post step removes it. With `false`, nothing is written. | | `show-progress` | `true` | Passes `--progress` to `git fetch` and `git checkout`. | | `set-safe-directory` | `true` | Marks the checkout as a Git safe directory for checkout's own commands. | | `github-server-url` | Githome | Check out from another server, for example `https://github.com`, with an explicit `token` for private repositories. | | `ssh-key` | | Not handled by the built-in: the real action runs. `ssh-known-hosts`, `ssh-strict` and `ssh-user` are accepted and ignored. | While fetching, the token reaches git through the environment, so a checkout that fails halfway leaves no credentials in `.git/config`. Credentials a reused workspace still holds from another job are removed first. Outputs: `commit` (the checked-out SHA) and `ref`. As on GitHub, a `pull_request` run checks out the test merge commit (`refs/pull//merge`) by default, and a `pull_request_target` run checks out the base branch. Errors: - `Failed to fetch ref '' from /. Check that the ref exists and the token has read access.` - `A branch or tag with the name '' could not be found` (with `fetch-depth: 0`). - `Checked out but expected .` ### actions/setup-node | Input | Notes | | --- | --- | | `node-version` | A version or range (`22`, `20.x`, `>=20.10`), `lts/*`, `lts/`, `lts/-1`, `latest`, `current` or `node`. | | `node-version-file` | `package.json` (reads `volta.node`, then `devEngines.runtime.version`, then `engines.node`), `.tool-versions` (`nodejs` or `node`), or a file whose first non-comment line is the version, such as `.nvmrc` or `.node-version`. | | `check-latest` | Download the newest matching version even when the preinstalled one satisfies the request. | | `registry-url`, `scope`, `always-auth` | Writes an `.npmrc` that reads `NODE_AUTH_TOKEN`, and sets `NPM_CONFIG_USERCONFIG`. For `npm.pkg.github.com` the scope defaults to the repository owner. `always-auth` is written for `v4` and earlier, or when you set it. | | `cache`, `cache-dependency-path` | `npm`, `pnpm` or `yarn`. See [Dependency caching with setup actions](https://git.pkgforge.dev/docs/actions/caching-and-artifacts#dependency-caching-with-setup-actions). | | `package-manager-cache` | `v5` and later cache npm automatically when `package.json` names npm as its package manager; `false` turns that off. | | `architecture`, `token` | Accepted. An `architecture` other than the runner's runs the real action. | Hosted runners have Node.js 26.7.0. A request that it satisfies uses it without a download; any other version is downloaded from `nodejs.org` into the tool cache. Without `node-version` or `node-version-file`, the step logs `No node-version specified; using the pre-installed node .` Other inputs, such as `mirror`, run the real action. Outputs: `node-version` (for example `v26.7.0`), `cache-hit` and `cache-primary-key`. ### actions/setup-python | Input | Notes | | --- | --- | | `python-version` | One CPython version or range, such as `3.12`, `3.11.9`, `3.x` or `3.14-dev`. PyPy and GraalPy versions run the real action. | | `python-version-file` | `.python-version`, `.tool-versions` (`python`), `pyproject.toml` (`requires-python`), or a file whose first non-comment line is the version. Without either input, `.python-version` in the workspace is used if present. | | `allow-prereleases` | Falls back to a pre-release build when no stable release matches. A version ending in `-dev` does the same. | | `cache`, `cache-dependency-path` | `pip` or `pipenv`. Other values run the real action. See [Dependency caching with setup actions](https://git.pkgforge.dev/docs/actions/caching-and-artifacts#dependency-caching-with-setup-actions). | | `architecture`, `check-latest`, `token`, `update-environment` | Accepted. An `architecture` other than the runner's, or `update-environment: false`, runs the real action. | Hosted runners have Python 3.12. A request that it satisfies uses it. Other versions are installed from the `actions/python-versions` builds that GitHub publishes, and the step sets `pythonLocation`, `Python_ROOT_DIR`, `Python3_ROOT_DIR`, `PKG_CONFIG_PATH` and `LD_LIBRARY_PATH` like the original action. Other inputs, such as `freethreaded`, run the real action. Outputs: `python-version`, `python-path` and `cache-hit`. ### actions/setup-go | Input | Notes | | --- | --- | | `go-version` | A version or range, `stable` or `oldstable`. | | `go-version-file` | `go.mod` or `go.work` (`toolchain` line first, then `go`), `.tool-versions` (`golang` or `go`), or a file whose first line is the version. | | `check-latest` | Download the newest matching version. | | `cache`, `cache-dependency-path` | On by default. Without a `go.sum` in the workspace root, the step warns `Restore cache failed: ...` and continues. | | `architecture`, `token` | Accepted. An `architecture` other than the runner's runs the real action. | Go isn't preinstalled on hosted runners, so the step downloads it from `go.dev`. Without a version on a runner that has no Go, it fails with `No go-version specified and Go is not installed on this runner.` Outputs: `go-version` and `cache-hit`. ### actions/cache and artifacts `actions/cache`, `actions/cache/restore`, `actions/cache/save`, `actions/upload-artifact` and `actions/download-artifact` support the official actions' inputs and outputs, including `retention-days`, `overwrite`, `compression-level`, `archive`, downloading all artifacts, `pattern`, `merge-multiple`, `artifact-ids`, and `run-id` with `github-token`. Caches are scoped per ref as on GitHub, each repository keeps up to 10 GB of caches, and artifacts are zip files kept for up to 90 days. [Caching and artifacts](https://git.pkgforge.dev/docs/actions/caching-and-artifacts) has the details. ### actions/github-script `actions/github-script` isn't a built-in: the real action runs, and its `github` client talks to Githome's REST API (`GITHUB_API_URL`) with the job token. What it may do follows the job's `permissions:`: ```yaml jobs: label: runs-on: ubuntu-latest permissions: issues: write pull-requests: write steps: - uses: actions/github-script@v7 with: script: | await github.rest.issues.addLabels({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, labels: ["needs-review"], }); ``` `github.graphql` works for what Githome's [GraphQL API](https://git.pkgforge.dev/docs/reference/graphql-api) answers (repositories, issues, pull requests and CI), with the job token and its `permissions:`. REST calls to endpoints Githome doesn't have get a JSON `404 Not Found`. See [the REST API reference](https://git.pkgforge.dev/docs/reference/rest-api) for the endpoints Githome has. ## Other actions Any other `uses: owner/repo[/path]@ref` (and a built-in action the built-in doesn't cover) is downloaded from GitHub (`codeload.github.com`, or with `git` from `github.com` when that endpoint can't be reached) when the step runs and executed according to its `action.yml` or `action.yaml`. If GitHub can't be reached at all, the runner uses the copy Githome keeps; see [When GitHub is down](#when-github-is-down). ### JavaScript actions Actions with `runs.using: node12`, `node16`, `node20`, `node24` or any other `node` run with the runner's own Node.js (26 on a hosted runner), whatever version they ask for. `pre`, `main`, `post`, `pre-if` and `post-if` are supported. One difference: on GitHub, `pre` scripts run at the start of the job, before any step. On Githome, an action's `pre` script runs immediately before its `main` script, as part of the same step. Post scripts run at the end of the job in reverse order, as on GitHub. ### Composite actions Composite actions (`runs.using: composite`) are supported, including `inputs`, `outputs`, `env`, `if`, `shell`, `working-directory` and nested `uses`. Composite actions nest at most 10 levels; deeper nesting fails with `Composite action nesting is too deep (max 10).` ### Docker container actions Actions with `runs.using: docker` are supported, with `runs.image` set to a `Dockerfile` in the action (built on the runner) or a `docker://` image, plus `args`, `entrypoint`, `env`, `pre-entrypoint` and `post-entrypoint`. A step can also run an image directly with `uses: docker://image`. Hosted runners have Docker; self-hosted runners need it installed. See [Docker container actions](https://git.pkgforge.dev/docs/actions/docker#docker-container-actions). ### Local actions `uses: ./path/to/action` reads the action from the workspace, so check out the repository first. Otherwise the step fails with `Can't find 'action.yml' or 'action.yaml' under ''. Did you forget to run actions/checkout before running your local action?` ### Actions stored on Githome `uses: acme/my-action@v1` always means the repository `acme/my-action` on GitHub, not on Githome. Actions in private GitHub repositories can't be used on hosted runners, because the download has no GitHub credentials. A [self-hosted runner](https://git.pkgforge.dev/docs/actions/runners#self-hosted-runners) can authenticate downloads with `GITHOME_GITHUB_TOKEN` in its environment. To use an action that lives in a Githome repository, check it out into a directory and use it as a local action: ```yaml - uses: actions/checkout@v4 with: repository: acme/my-action ref: v1 path: .actions/my-action token: ${{ secrets.ACTIONS_READ_TOKEN }} - uses: ./.actions/my-action ``` `ACTIONS_READ_TOKEN` is a personal or agent token with read access to `acme/my-action`, stored as a secret, because the job token can't read other private repositories. If `acme/my-action` is public, leave `token` out: the job token can read public repositories. ### When GitHub is down Githome keeps its own copy of every public action that jobs on Githome download, so jobs keep running through a GitHub outage: 1. The runner always downloads the action from GitHub first, as above, so a job gets the same code it would get on GitHub. 2. After the download, Githome fetches the same archive from `codeload.github.com` itself and stores it. Copies are refreshed when a job uses them: a tag or branch (`@v4`, `@main`) once it is a day old, a commit SHA once a week. Copies that jobs stop using are deleted after about a month. 3. When GitHub fails (the download and the `git` fallback both fail, for example with `HTTP 503`, a refused connection or no answer in 60 seconds), the runner downloads Githome's copy instead. The step logs a warning, also shown as an annotation on the run: ``` GitHub is unreachable (HTTP 503 downloading https://codeload.github.com///tar.gz/); using Githome's copy of '/@', downloaded from GitHub at