Hosted repositories

Anvil can host your code itself. Under Code in the sidebar you create repositories, browse files and history, track issues, open pull requests and merge them, all inside Anvil. Pull requests get the same reviews as any other repository.

Hosted repositories work the same however you sign in: with an email link, GitHub or Gitea. The first time you open Code, Anvil sets up your account for hosting; that takes a second and happens once. Repositories are stored on Anvil's server in Germany.

Create a repository #

1. Open Code → New repository.
2. Pick a name (letters, digits, dots, dashes, underscores) and, if you like, a one-line description.
3. Choose Private (only you and the people you add) or Public (everyone with an Anvil account).
4. Leave Add a README on to start with one commit on main, so you can clone straight away. Turn it off to push an existing project into an empty repository.
5. Leave Review pull requests on to have Anvil review every pull request. You can turn it off later in the repository's Settings.

To create it in an organisation instead, pick the organisation as Owner.

Clone and push #

Every repository has an HTTPS clone address under Anvil's own domain (or use SSH):

git clone https://selfhost-test.wicker.life/git/<owner>/<repo>.git

When git asks for a password, use an Anvil API token: create one under Settings → Connect an agent. Any username works. The token acts as you, so git can read and push exactly the repositories you can.

To push a project you already have into a new, empty repository:

git remote add origin https://selfhost-test.wicker.life/git/<owner>/<repo>.git
git push -u origin main

To stop typing the token, let git remember it, for example with git config --global credential.helper osxkeychain on a Mac or store elsewhere. Revoking the token under Settings → Connect an agent cuts off git access at once.

Git LFS works through the same address.

Clone over SSH #

You can also clone and push over SSH with a key instead of a token.

1. If you don't have a key yet, make one: ssh-keygen -t ed25519. It writes ~/.ssh/id_ed25519 (private, never share it) and ~/.ssh/id_ed25519.pub.
2. Open Settings → SSH keys, paste the contents of the .pub file, give it a name and click Add key. Ed25519, ECDSA, RSA and security keys (sk-…) work.
3. Copy the address from the SSH tab of a repository's Clone button. Anvil remembers which tab you used last.

git clone ssh://git@selfhost-test.wicker.life:2222/<owner>/<repo>.git

SSH runs on port 2222; keep the address exactly as shown, with the port. To add SSH to a clone you made over HTTPS:

git remote set-url origin ssh://git@selfhost-test.wicker.life:2222/<owner>/<repo>.git

A key acts as you: git can read and push exactly the repositories you can, as over HTTPS. Removing the key under Settings → SSH keys cuts off its access at once. A key can belong to one account only; Anvil says so if you paste one that's already added.

Check the host key #

The first time you connect, SSH asks whether to trust [selfhost-test.wicker.life]:2222. Compare the fingerprint it shows with one of these before you answer yes:

• Ask the person who runs this server for its fingerprints, or compare with ssh-keyscan output from a network you trust.

If it doesn't match, don't connect. To test your key, run ssh -T -p 2222 git@selfhost-test.wicker.life: it greets you by name and closes.

Browse code #

The repository page shows the files of the default branch, the README, the clone address, languages and recent commits.

• Branch or tag: switch with the selector above the file list. Links keep the ref, so you can share a file at a branch or a commit.
• Files open with syntax highlighting and line numbers. Click a line number to link to it; shift-click another to select a range. Permalink copies a link pinned to the current commit.
• Commits lists the history of a branch, or of one file from the file's History link. Open a commit to see its diff, split or unified.
• Branches lists every branch with its last commit, and starts a pull request from any of them.

Edit files in the browser #

If you have write access, you can change files without cloning:

• Edit: open a file and click Edit. The editor highlights syntax, indents, and finds text with ⌘F (Ctrl+F). Change the name above the editor to rename or move the file. Changes shows what your commit will change; for Markdown it's Preview.
• Create a file: in a folder, Add file → Create new file. Type slashes in the name to make folders (docs/guide/intro.md).
• Upload files: Add file → Upload files, then drag files or whole folders in, or pick them. Up to 100 files and 10 MB per commit; files with the same path replace what's there, and the list says which. Push bigger files with git.
• Delete a file: the bin icon on the file.

Every change is one commit. Below the editor you write the message and choose where it goes:

• Commit to the branch you're on, straight away, or
• Create a new branch (Anvil suggests <you>-patch-1) and, if you like, open a pull request into the branch you started from, so it gets reviewed before it lands. On a protected branch this is the only choice.

If someone else changed the same file after you opened it, the commit is refused so their change isn't overwritten. Copy your edit, reload, and apply it again. Files can only be changed on a branch, not on a tag or a commit.

Search #

• Go to file: press t on any page of a repository (or click Go to file) and type part of a path. Letters can be spread out: sfg finds src/forge.ts.
• Search code: type in the search box in the repository header. Results show each matching line with the match highlighted; switch to File paths to match names instead. Search is plain text, case-insensitive unless you turn on Match case, at the branch or tag you pick.

Anvil reads the files itself, so very large repositories are searched in part: binary files, files over 512 KB, and anything past the first 1,500 files or 24 MB are skipped. The results page says when that happened. Searching across all your repositories isn't available yet.

Releases #

The Releases tab lists every release with its notes and files.

1. New release (needs write access).
2. Pick an existing tag, or type a new one (v1.2.0) and choose the branch it's made from.
3. Give it a title and notes in Markdown, attach files (up to 50 MB each), and mark it a pre-release if it isn't ready for everyone.
4. Publish release, or Save draft to finish later. Drafts are only visible to people with write access.

You can attach more files to a release later, remove files, or delete the release. Deleting a release keeps its tag unless you tick Also delete the tag; the code is never affected.

Issues #

Open the Issues tab of a repository to see open and closed issues, and New issue to file one. Descriptions and comments are Markdown. On an issue you can comment, and close or reopen it if you have write access or opened it. Code → Issues lists issues across all your repositories.

Labels, assignees and milestones #

The column next to an issue shows its labels, assignees and milestone. With write access, click the gear next to each to change it: pick labels and people from the list (the change saves when the list closes), or pick a milestone. Pull requests have the same three on the Overview of the workspace.

• Labels are per repository. Issues → Labels lists them; with write access you can add, rename, recolour and delete them. Deleting a label takes it off every issue and pull request.
• Milestones group work towards a release or date. Issues → Milestones shows each with its due date and how many of its issues are closed; you can add, close, reopen and delete them.
• Assignees can be anyone with write access to the repository.

The Label, Milestone and Assignee buttons above the issue and pull request lists filter them. Filters live in the address, so you can share a filtered list. Clicking a label or milestone on a row filters by it.

Pull requests #

1. Push a branch: git switch -c my-change, commit, git push -u origin my-change.
2. Open Pull requests → New pull request (or the button next to the branch on Branches).
3. Pick the base branch and the branch to merge. Anvil shows the commits between them and, for a single commit, fills in the title and description from its message.
4. Open pull request takes you to the pull request workspace, where the review appears.

Write Closes #12 in the description to close issue 12 when the pull request merges.

Merge #

The workspace header has a Merge button for pull requests in hosted repositories. Its menu offers:

You can delete the branch after merging. The button is greyed out, with the reason in its menu, when the pull request can't merge: it conflicts with the base branch, it's a draft, it's closed, or you don't have write access. If someone pushed to the branch since you loaded the page, the merge is refused so you never merge commits you haven't seen; reload and try again.

Repository settings #

Owners and admins see a Settings tab on the repository.

General

• Name: renaming changes the clone address. Point your clones at the new one with git remote set-url origin https://selfhost-test.wicker.life/git/<owner>/<new-name>.git. Review history stays with the repository.
• Description, default branch (what pull requests target and the repository page shows) and visibility (private or public).
• Anvil review: switches reviews on or off for the repository.
• Archive makes the repository read-only: no pushes, issues or pull requests until you unarchive it.
• Delete removes the code, history, issues and pull requests for good. Type the full name (owner/name) to confirm.

Collaborators

Add people by name and give each a permission:

People need an Anvil account first; an admin can invite them under Settings → Access. In an organisation's repository, the organisation's owners and teams have access too.

Branch protection

A rule applies to a branch name, or to a pattern such as release/* (* stays within one path segment, ** crosses them). Each rule can:

• Require a pull request: nobody pushes to the branch directly.
• Require approvals: a pull request needs that many approving reviews to merge, and a requested change blocks it. Dismiss approvals on new commits asks for approval again after a push.
• Require status checks: named checks (Anvil's review status Anvil, CI jobs such as ci / test (push)) must pass on the latest commit. Leave the list empty to require every check reported on the commit. Checks seen on the default branch are suggested.
• Block force pushes: nobody rewrites the branch's history.

The merge button in the workspace explains why a pull request can't merge when a rule stops it.

Organisations #

An organisation owns repositories together. Open Code → Organisations to see yours and create one: a name (used in addresses, like /code/<org>/<repo>), an optional display name and description, and who can see it (members only, anyone signed in, or everyone). You become its owner.

People join an organisation through teams. On the organisation page:

• New team creates one with read, write or admin access, either to every repository (including later ones) or to repositories you pick. A team can also be allowed to create repositories in the organisation.
• Open a team to add or remove people and repositories.
• The Owners team has full control and always reaches every repository.
• Owners can remove someone from the organisation and all its teams under People.

New repository on the organisation page (or picking the organisation as Owner when you create a repository) creates a repository there.

If Anvil says it needs a new permission when you create an organisation or team, try again in a minute: Anvil updates your account's access on its own the first time it's needed.