# Using infinigit with coding agents This file is the quick operational reference for an AI coding agent working with repositories hosted on [infinigit](https://infinigit.com). Read it before changing an infinigit-hosted project. Repository-local `AGENTS.md` files may add project-specific instructions and take precedence within their directory. ## What infinigit is infinigit is Git hosting and collaboration infrastructure on the Internet Computer (ICP). It preserves ordinary Git commits, trees, blobs, tags, branches, and object IDs. The preferred transport is the custom `igit://` URL scheme: ```text igit://infinigit.com/OWNER/REPOSITORY ``` Use standard Git commands after installing the remote helper. Do not rewrite an `igit://` remote to HTTP or SSH unless a human explicitly asks for the compatibility transport. ## Install the required tools You need Git, the ICP CLI (`icp`), the infinigit CLI, and the Git remote helper: ```bash npm install --global @icp-sdk/icp-cli infinigit-cli git-remote-igit command -v git icp infinigit git-remote-igit ``` Cargo packages are also available: ```bash cargo install infinigit-cli git-remote-igit ``` Some alpha releases require the companion `infinigit-pack` binary beside `git-remote-igit`. If Git reports that it is missing, build it from `https://github.com/infinigit-labs/infinigit` with: ```bash cargo build --release --bin infinigit-pack git config --global infinigit.pack-bin /absolute/path/to/infinigit-pack ``` ## Identity: agents do not need usernames Every write is authorized by an ICP principal. An agent can use its raw principal as its infinigit namespace and does not need to claim a username. Never create or request an infinigit password; infinigit does not use passwords. For a new independently revocable CLI identity, run: ```bash infinigit auth link-device --name coding-agent --label "Coding agent" ``` The command prints a short-lived pairing code. A human approves it at `https://infinigit.com/#/settings/devices`. Use `--read-only` for an agent that only needs to clone and fetch. If an interrupted attempt already created the identity, repeat with `--reuse-existing`. Alternatively, a human can create a browser-linked session: ```bash infinigit auth login --name coding-agent ``` Inspect or refresh the configured identity with: ```bash infinigit auth status --name coding-agent infinigit auth reauth --name coding-agent ``` Do not change the user's global default ICP identity. The infinigit tools select their configured identity without requiring that change. Never print, commit, or transmit seed phrases, delegation files, access tokens, or decrypted secrets. ## Clone, fetch, pull, and push ```bash git clone igit://infinigit.com/OWNER/REPOSITORY cd REPOSITORY git fetch origin git pull --ff-only git push -u origin HEAD ``` Public repositories are anonymously readable but never anonymously writable. Private repositories deliberately look nonexistent to callers without access. If a private clone reports `repository not found`, first verify the selected identity and ask the owner to grant that principal access. Normal Git behavior is expected, including branches, tags, force updates, ref deletion, atomic ref checks, and concurrent-update rejection. Do not force-push, delete refs, rewrite published history, or bypass branch protection unless the human explicitly authorizes it. On a stale-ref rejection, fetch and reconcile the concurrent work instead of blindly retrying with force. Commit hashes remain canonical Git object IDs. Do not replace Git hashes with an ICP-specific content identifier. ## Creating repositories A signed-in principal can create a repository from **My repositories** at `https://infinigit.com`. A claimed username is optional. Without one, the URL uses the principal itself: ```text igit://infinigit.com/PRINCIPAL/project ``` If that principal later claims a username, existing principal-based repository links continue to resolve. Repository names allow letters, numbers, periods, underscores, and hyphens; only the special profile repository `.igit` may begin with a period. To import every branch and tag from another Git host, create an empty destination and run: ```bash infinigit import SOURCE_GIT_URL igit://infinigit.com/OWNER/REPOSITORY ``` Do not embed source-host passwords or tokens in URLs. Let Git's credential manager provide them. ## Ask a human to grant an agent access Give the repository administrator this copy-and-paste command, substituting the agent's principal and repository URL: ```bash infinigit repo access grant AGENT_PRINCIPAL write \ --repo igit://infinigit.com/OWNER/REPOSITORY ``` Permissions are: - `read`: clone and fetch, including private-repository discovery. - `write`: read plus pushes permitted by repository rules. - `admin`: repository administration as well as write access. Administrators can inspect or revoke direct grants: ```bash infinigit repo access list --repo igit://infinigit.com/OWNER/REPOSITORY infinigit repo access revoke AGENT_PRINCIPAL \ --repo igit://infinigit.com/OWNER/REPOSITORY ``` Commands accept either a raw principal, `username`, or `@username`. Access is always rechecked by the directory and authoritative storage shard; a supplied name never proves authorization. ## Organization membership Organization membership is invitation-based. Ask an organization owner or admin to run: ```bash infinigit org members invite ORGANIZATION AGENT_PRINCIPAL member ``` Then, using the invited agent identity: ```bash infinigit org members invitations infinigit org members accept INVITATION_ID ``` Roles are `member`, `admin`, and `owner`. Administrators can manage them with: ```bash infinigit org members list ORGANIZATION infinigit org members role ORGANIZATION AGENT_PRINCIPAL admin infinigit org members remove ORGANIZATION AGENT_PRINCIPAL ``` Teams provide repository access to groups of organization members. Team and repository policy can also be managed under the organization's settings in the web app. ## Repository secrets Secrets are encrypted vault data stored outside Git. Never add plaintext secrets, `.env` files, generated credentials, or decrypted vault output to a commit. A repository may have up to five named vaults under the current policy. Run secret commands inside a checkout, or add `--repo igit://infinigit.com/OWNER/REPOSITORY`: ```bash infinigit secrets vaults infinigit secrets create prod infinigit secrets list prod printf '%s' "$VALUE" | infinigit secrets set prod API_TOKEN --stdin infinigit secrets unset prod API_TOKEN infinigit secrets put prod --from-dotenv .env.prod infinigit secrets pull prod --format dotenv --output .env.prod infinigit secrets pull prod --format shell infinigit secrets run prod -- ./your-command infinigit secrets rotate prod ``` Prefer `infinigit secrets run` when possible so plaintext is passed only to the child process environment. Treat `pull --format shell` as sensitive output; do not log it. Vault permissions separately control reading, writing, deleting secrets, deleting vaults, and managing access. ## Branches, reviews, and automation - Respect protected branches and required status checks. - Use a topic branch and pull request when repository policy requires review. - Put repository-specific agent instructions in the repository's own `AGENTS.md`; more deeply nested files can narrow instructions for a subtree. - `CODEOWNERS` lives at `.igit/CODEOWNERS` on the default branch. Owners may be users, principals, or teams written as `@organization/team`. - Woodpecker CI can react to pushes, branch changes, pull-request lifecycle events, and path filters. Its runner is external because ICP canisters do not execute arbitrary shell jobs. - Keep CI credentials in an infinigit vault or the runner's protected secret store, never in workflow files. ## Markdown and shareable source links Repository Markdown supports badges, HTTPS images, relative images, and links to other Markdown files. Keep relative assets in the repository so they remain valid across clones and branches. The web file browser encodes the file path in the URL. A non-default revision also includes its commit hash. Use the line anchors shown beside source lines to share a stable link to a particular line; prefer a commit-pinned URL when the exact content matters. ## Safe agent workflow Before editing: ```bash git status --short git branch --show-current git remote -v ``` Then: 1. Read every applicable repository-local `AGENTS.md` completely. 2. Preserve unrelated local changes and generated credentials. 3. Work on a topic branch unless the human explicitly requests another flow. 4. Make the smallest coherent change and add tests for new behavior and failure paths. 5. Run the repository's documented checks. 6. Review `git diff --check`, `git diff --stat`, and the exact staged files. 7. Commit with an outcome-focused message. 8. Push only to the remote and branch the human authorized. Never force-push without explicit authorization. Do not assume that access to one repository grants access to its organization, other repositories, teams, secrets, or treasury. Use the least permission the task needs and ask for a scoped grant when blocked. ## Troubleshooting checklist If Git cannot find the `igit` transport: ```bash command -v git-remote-igit git config --global --get infinigit.pack-bin ``` If authentication fails: ```bash infinigit auth status infinigit auth reauth ``` If access fails, report the exact repository URL, the agent principal from `infinigit auth status`, the requested permission (`read`, `write`, or `admin`), and the copy-and-paste grant command. Do not ask a human to share their private identity material. For deeper human-oriented guidance, visit `https://infinigit.com/#/docs/getting-started`. Platform source and issue tracking are at `https://github.com/infinigit-labs/infinigit`.