Skip to content

Git designed for AI agents.

graft: create repositories from the SDK and the CLI

Federico Eliafeccf69b0b77
diff --git a/cmd/graft/main.go b/cmd/graft/main.go
index a570921..4b470fa 100644
--- a/cmd/graft/main.go
+++ b/cmd/graft/main.go
@@ -99,6 +99,7 @@ func commandTable() map[string]command {
"search": newSearchCommand(),
"review": reviewCommand(),
"storage": storageCommand(),
+ "repo": repoCommand(),
}
}
@@ -273,6 +274,8 @@ commands:
search QUERY search file contents (--regex, -i, --path, --context, -n, --rev, --json)
review SUBCOMMAND create, show, list, comment, approve, request-changes, update, close (--branch, --title, --json)
storage SUBCOMMAND import, state, verify, checkpoint, gc a repository in the storage core; gc --removed for a storage (--connectivity, --dry-run, --json)
+ repo create REPO create a repository, with the shared token (--default-branch, --object-format,
+ --initial-commit [--branch NAME], --json)
environment: GRAFT_ADDRESS, GRAFT_TOKEN, GRAFT_STORAGE, GRAFT_USER, GRAFT_AUTHOR
diff --git a/cmd/graft/repo.go b/cmd/graft/repo.go
new file mode 100644
index 0000000..fac1c82
--- /dev/null
+++ b/cmd/graft/repo.go
@@ -0,0 +1,193 @@
+package main
+
+import (
+ "context"
+ "flag"
+ "fmt"
+ "io"
+ "path"
+ "strings"
+
+ "google.golang.org/grpc/codes"
+
+ "github.com/feder-cr/git-ai/sdk"
+)
+
+// repoSynopsis is the command line of graft repo.
+const repoSynopsis = "usage: graft repo create REPO [--default-branch NAME] [--object-format sha1|sha256] [--initial-commit [--branch NAME]...] [--json]"
+
+// repoUsage lists the subcommands of graft repo.
+const repoUsage = "repo requires a subcommand: create (" + repoSynopsis + ")"
+
+// initialCommitMessage is the message of the commit of --initial-commit.
+const initialCommitMessage = "Initial commit"
+
+// repoFlags holds the flags of graft repo create.
+type repoFlags struct {
+ defaultBranch string
+ objectFormat string
+ initialCommit bool
+ branches stringList
+}
+
+// stringList is a flag that may be given several times.
+type stringList []string
+
+func (l *stringList) String() string { return strings.Join(*l, ",") }
+
+func (l *stringList) Set(value string) error {
+ *l = append(*l, value)
+ return nil
+}
+
+// repoCreateResult is the JSON output of graft repo create.
+type repoCreateResult struct {
+ Repository string `json:"repository"`
+ Storage string `json:"storage"`
+ // Created is false when the repository existed already, empty, and the
+ // command only added the initial commit.
+ Created bool `json:"created"`
+ DefaultBranch string `json:"default_branch"`
+ InitialCommit string `json:"initial_commit,omitempty"`
+ Branches []string `json:"branches,omitempty"`
+}
+
+// repoCommand returns the repo command, the operator's creation of
+// repositories.
+func repoCommand() command {
+ f := &repoFlags{}
+ return command{
+ bind: func(fs *flag.FlagSet, o *options) {
+ fs.Usage = func() {
+ fmt.Fprintf(fs.Output(), "%s\n\nCreating a repository needs the shared (operator) token.\n\nflags:\n", repoSynopsis)
+ fs.PrintDefaults()
+ }
+ fs.StringVar(&f.defaultBranch, "default-branch", "main", "the branch HEAD points to, and the branch of the initial commit")
+ fs.StringVar(&f.objectFormat, "object-format", "", "the object hash, sha1 or sha256 (default: the server's)")
+ fs.BoolVar(&f.initialCommit, "initial-commit", false, "also make a first commit (README.md) on the default branch, so that the repository can be cloned; on an existing repository without branches, only make that commit")
+ fs.Var(&f.branches, "branch", "with --initial-commit, also create this branch at the initial commit (may be repeated)")
+ fs.BoolVar(&o.jsonOut, "json", false, "print the result as one JSON object")
+ },
+ run: func(ctx context.Context, out io.Writer, o *options, args []string) error {
+ return cmdRepo(ctx, out, o, f, args)
+ },
+ }
+}
+
+// cmdRepo dispatches a repo subcommand. Arguments are checked before the
+// server is contacted.
+func cmdRepo(ctx context.Context, out io.Writer, o *options, f *repoFlags, args []string) error {
+ if len(args) == 0 {
+ return usagef("%s", repoUsage)
+ }
+ if args[0] != "create" {
+ return usagef("unknown repo subcommand %q: %s", args[0], repoUsage)
+ }
+ return repoCreate(ctx, out, o, f, args[1:])
+}
+
+func repoCreate(ctx context.Context, out io.Writer, o *options, f *repoFlags, args []string) error {
+ if len(args) != 1 || args[0] == "" {
+ return usagef("repo create takes one repository path: %s", repoSynopsis)
+ }
+ relativePath := args[0]
+ defaultBranch := strings.TrimPrefix(f.defaultBranch, "refs/heads/")
+ switch {
+ case defaultBranch == "":
+ return usagef("repo create: --default-branch must not be empty")
+ case f.objectFormat != "" && f.objectFormat != "sha1" && f.objectFormat != "sha256":
+ return usagef("repo create: --object-format must be sha1 or sha256, not %q", f.objectFormat)
+ case len(f.branches) > 0 && !f.initialCommit:
+ return usagef("repo create: --branch creates a branch at the initial commit and requires --initial-commit")
+ case o.address == "":
+ return usagef("repo create needs the server address: -address or GRAFT_ADDRESS")
+ }
+ author, err := parseAuthor(o.author)
+ if err != nil {
+ return err
+ }
+
+ dialOpts := []sdk.DialOption{sdk.WithStorage(pick(o.storage, defaultStorage))}
+ if o.token != "" {
+ dialOpts = append(dialOpts, sdk.WithToken(o.token))
+ }
+ client, err := sdk.Dial(ctx, o.address, dialOpts...)
+ if err != nil {
+ return err
+ }
+ registerCloser(ctx, client)
+ repo := client.Repo(relativePath)
+
+ res := repoCreateResult{Repository: relativePath, Storage: client.Storage(), Created: true, DefaultBranch: defaultBranch}
+ err = repo.Create(ctx, sdk.CreateOptions{DefaultBranch: defaultBranch, ObjectFormat: f.objectFormat})
+ switch {
+ case sdk.IsAlreadyExists(err) && f.initialCommit:
+ // A repository without branches is the one an earlier run created before
+ // its initial commit failed: make that commit now.
+ hasBranches, checkErr := repo.HasBranches(ctx)
+ if checkErr != nil {
+ return withOperatorHint(checkErr)
+ }
+ if hasBranches {
+ return fmt.Errorf("repository %s exists already and has branches", displayText(relativePath))
+ }
+ res.Created = false
+ case sdk.IsAlreadyExists(err):
+ return fmt.Errorf("repository %s exists already", displayText(relativePath))
+ case err != nil:
+ return withOperatorHint(err)
+ }
+
+ if f.initialCommit {
+ user := sdk.User{ID: pick(o.user, anonymousUser), Username: pick(o.user, anonymousUser), Name: author.Name, Email: author.Email}
+ commit, err := repo.CommitFiles(ctx, sdk.CommitOptions{
+ Branch: defaultBranch,
+ Message: initialCommitMessage,
+ Author: sdk.Signature{Name: author.Name, Email: author.Email},
+ User: user,
+ Actions: []sdk.Action{sdk.Put{Path: "README.md", Content: []byte("# " + repositoryName(relativePath) + "\n")}},
+ })
+ if err != nil {
+ return fmt.Errorf("repository %s has no initial commit: %w (run the same command again to add it)", displayText(relativePath), withUserHint(err, o.user))
+ }
+ res.InitialCommit = commit.CommitID
+
+ for _, branch := range f.branches {
+ if _, err := repo.Land(ctx, sdk.LandOptions{Branch: branch, Commit: commit.CommitID, CreateBranch: true, User: user}); err != nil {
+ return fmt.Errorf("creating branch %s at the initial commit %s: %w", displayText(branch), commit.CommitID, withUserHint(err, o.user))
+ }
+ res.Branches = append(res.Branches, branch)
+ }
+ }
+
+ if o.jsonOut {
+ return writeStorageJSON(out, res)
+ }
+ if res.Created {
+ fmt.Fprintf(out, "created repository %s on storage %s\n", displayText(relativePath), displayText(res.Storage))
+ } else {
+ fmt.Fprintf(out, "repository %s exists without branches: adding the initial commit\n", displayText(relativePath))
+ }
+ if res.InitialCommit != "" {
+ fmt.Fprintf(out, "initial commit %s on %s\n", res.InitialCommit, displayText(defaultBranch))
+ }
+ for _, branch := range res.Branches {
+ fmt.Fprintf(out, "created branch %s at %s\n", displayText(branch), res.InitialCommit)
+ }
+ return nil
+}
+
+// repositoryName is the name of the repository at relativePath, for its
+// README: the last path element without .git.
+func repositoryName(relativePath string) string {
+ return strings.TrimSuffix(path.Base(relativePath), ".git")
+}
+
+// withOperatorHint explains a refused creation: agents may never create
+// repositories.
+func withOperatorHint(err error) error {
+ if sdk.Code(err) != codes.PermissionDenied {
+ return err
+ }
+ return fmt.Errorf("%w\nhint: creating a repository needs the shared (operator) token in GRAFT_TOKEN (or -token), not an agent token", err)
+}
diff --git a/cmd/graft/repo_test.go b/cmd/graft/repo_test.go
new file mode 100644
index 0000000..7bc24fb
--- /dev/null
+++ b/cmd/graft/repo_test.go
@@ -0,0 +1,226 @@
+package main
+
+import (
+ "encoding/json"
+ "path/filepath"
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/feder-cr/git-ai/internal/featureflag"
+ "github.com/feder-cr/git-ai/internal/git/gittest"
+ "github.com/feder-cr/git-ai/internal/gitaly/config"
+ "github.com/feder-cr/git-ai/internal/gitaly/service/setup"
+ "github.com/feder-cr/git-ai/internal/gitlab"
+ "github.com/feder-cr/git-ai/internal/graft/corestore"
+ "github.com/feder-cr/git-ai/internal/graft/corestore/coretest"
+ "github.com/feder-cr/git-ai/internal/testhelper"
+ "github.com/feder-cr/git-ai/internal/testhelper/testcfg"
+ "github.com/feder-cr/git-ai/internal/testhelper/testserver"
+ "github.com/feder-cr/git-ai/sdk"
+)
+
+// repoCreated is the JSON output of graft repo create.
+type repoCreated struct {
+ Repository string `json:"repository"`
+ Storage string `json:"storage"`
+ Created bool `json:"created"`
+ DefaultBranch string `json:"default_branch"`
+ InitialCommit string `json:"initial_commit"`
+ Branches []string `json:"branches"`
+}
+
+// TestCLIRepoCreateAgainstServer drives graft repo create against a server
+// without a storage core: an empty repository, a repository that exists
+// already, a repository with its initial commit and a second branch that the
+// CLI then clones, and the retry that adds the initial commit to an existing
+// empty repository. It runs serially because the CLI tests share the
+// package-level backend factory.
+func TestCLIRepoCreateAgainstServer(t *testing.T) {
+ env := startServer(t)
+ server := []string{"-address", env.addr, "-storage", env.storage}
+ create := func(args ...string) (int, string, string) {
+ return runCLI(t, append(append([]string{"repo", "create"}, args...), server...)...)
+ }
+ b := env.backend(t)
+
+ code, stdout, stderr := create("empty.git")
+ require.Equal(t, exitOK, code, stderr)
+ require.Equal(t, "created repository empty.git on storage "+env.storage+"\n", stdout)
+ require.DirExists(t, filepath.Join(env.cfg.Storages[0].Path, "empty.git"))
+
+ code, _, stderr = create("empty.git")
+ require.Equal(t, exitError, code)
+ require.Contains(t, stderr, "repository empty.git exists already\n")
+
+ // The initial commit and a second branch make the repository clonable.
+ code, stdout, stderr = create("seeded.git", "--initial-commit", "--branch", "feature/demo", "--json")
+ require.Equal(t, exitOK, code, stderr)
+ var seeded repoCreated
+ require.NoError(t, json.Unmarshal([]byte(stdout), &seeded))
+ require.Equal(t, repoCreated{
+ Repository: "seeded.git",
+ Storage: env.storage,
+ Created: true,
+ DefaultBranch: "main",
+ InitialCommit: seeded.InitialCommit,
+ Branches: []string{"feature/demo"},
+ }, seeded)
+ repo := b.client.Repo("seeded.git")
+ for _, branch := range []string{"main", "feature/demo"} {
+ commit, err := repo.ResolveRevision(env.ctx, branch)
+ require.NoError(t, err, branch)
+ require.Equal(t, seeded.InitialCommit, commit, branch)
+ }
+ readme, err := repo.ReadFile(env.ctx, "main", "README.md")
+ require.NoError(t, err)
+ require.Equal(t, "# seeded\n", string(readme))
+
+ dir := filepath.Join(t.TempDir(), "seeded")
+ code, _, stderr = runCLI(t, "clone", env.addr, "seeded.git", dir, "-storage", env.storage, "--branch", "feature/demo")
+ require.Equal(t, exitOK, code, stderr)
+ require.FileExists(t, filepath.Join(dir, "README.md"))
+
+ // An earlier run that created the repository but not its initial commit is
+ // completed by running the command again.
+ code, _, stderr = create("empty.git", "--initial-commit")
+ require.Equal(t, exitOK, code, stderr)
+ code, stdout, stderr = create("resumed.git")
+ require.Equal(t, exitOK, code, stderr)
+ code, stdout, stderr = create("resumed.git", "--initial-commit", "--default-branch", "trunk")
+ require.Equal(t, exitOK, code, stderr)
+ require.Regexp(t, `^repository resumed.git exists without branches: adding the initial commit\ninitial commit [0-9a-f]+ on trunk\n$`, stdout)
+ _, err = b.client.Repo("resumed.git").ResolveRevision(env.ctx, "trunk")
+ require.NoError(t, err)
+
+ // A repository with branches is not touched again.
+ code, _, stderr = create("resumed.git", "--initial-commit")
+ require.Equal(t, exitError, code)
+ require.Contains(t, stderr, "repository resumed.git exists already and has branches\n")
+
+ code, stdout, stderr = create("sha256.git", "--object-format", "sha256", "--initial-commit", "--json")
+ require.Equal(t, exitOK, code, stderr)
+ var sha256Repo repoCreated
+ require.NoError(t, json.Unmarshal([]byte(stdout), &sha256Repo))
+ require.Len(t, sha256Repo.InitialCommit, 64)
+}
+
+// TestCLIRepoCreateOperatorOnly checks that only the shared token creates a
+// repository: an agent token is refused with a hint, and the operator's initial
+// commit passes the access policy as the configured user.
+func TestCLIRepoCreateOperatorOnly(t *testing.T) {
+ ctx := featureflag.OutgoingCtxWithFeatureFlag(testhelper.Context(t), featureflag.GPGSigning, false)
+ cfg := testcfg.Build(t)
+ cfg.Auth.Token = "operator-secret"
+ cfg.Graft.Standalone = true
+ cfg.Graft.Agents = []config.GraftAgent{{Name: "alice", Token: "alice-secret"}}
+ cfg.Graft.Policy = []config.GraftPolicyRule{
+ {Actor: "alice", Refs: []string{"refs/heads/main"}, Allow: true},
+ {Actor: "*", Allow: false},
+ }
+ testcfg.BuildGitalySSH(t, cfg)
+ testcfg.BuildGitalyHooks(t, cfg)
+ addr := testserver.RunGitalyServer(t, cfg, setup.RegisterAll,
+ testserver.WithGitLabClient(gitlab.NewStandaloneClient(cfg.Graft, testhelper.SharedLogger(t))))
+ server := []string{"-address", addr, "-storage", cfg.Storages[0].Name}
+
+ code, _, stderr := runCLI(t, append([]string{"repo", "create", "a.git", "-token", "alice-secret"}, server...)...)
+ require.Equal(t, exitError, code)
+ require.Contains(t, stderr, "PermissionDenied")
+ require.Contains(t, stderr, "hint: creating a repository needs the shared (operator) token")
+ require.NoDirExists(t, filepath.Join(cfg.Storages[0].Path, "a.git"))
+
+ code, stdout, stderr := runCLI(t, append([]string{"repo", "create", "a.git", "--initial-commit", "-token", "operator-secret", "-user", "alice"}, server...)...)
+ require.Equal(t, exitOK, code, stderr)
+ require.Contains(t, stdout, "created repository a.git")
+
+ client, err := sdk.Dial(ctx, addr, sdk.WithStorage(cfg.Storages[0].Name), sdk.WithAgentToken("alice-secret"))
+ require.NoError(t, err)
+ t.Cleanup(func() { _ = client.Close() })
+ readme, err := client.Repo("a.git").ReadFile(ctx, "main", "README.md")
+ require.NoError(t, err)
+ require.Equal(t, "# a\n", string(readme))
+}
+
+// TestCLIRepoCreateAuthoritative checks that a repository created by graft repo
+// create on a server whose storage core is authoritative is registered there,
+// with its initial commit, and that the storage core's verification finds the
+// local copy equal to the database. It runs serially because the CLI tests
+// share the package-level backend factory.
+func TestCLIRepoCreateAuthoritative(t *testing.T) {
+ cfg := testcfg.Build(t)
+ cfg.Graft.Standalone = true
+ testcfg.BuildGitalySSH(t, cfg)
+ testcfg.BuildGitalyHooks(t, cfg)
+ core := coretest.Open(t, coretest.Options{Mode: corestore.ModeAuthoritative})
+ addr := testserver.RunGitalyServer(t, cfg, setup.RegisterAll, testserver.WithGraftStorage(core))
+ target := []string{"-address", addr, "-storage", cfg.Storages[0].Name}
+
+ code, stdout, stderr := runCLI(t, append([]string{"repo", "create", "core.git", "--initial-commit", "--branch", "feature/demo", "--json"}, target...)...)
+ require.Equal(t, exitOK, code, stderr)
+ var created repoCreated
+ require.NoError(t, json.Unmarshal([]byte(stdout), &created))
+
+ code, stdout, stderr = runCLI(t, append([]string{"storage", "state", "--json", "-repo", "core.git"}, target...)...)
+ require.Equal(t, exitOK, code, stderr)
+ var state sdk.StorageState
+ require.NoError(t, json.Unmarshal([]byte(stdout), &state))
+ require.True(t, state.Tracked)
+ require.EqualValues(t, 3, state.HeadSequence, "the creation, the initial commit and the branch")
+
+ code, stdout, stderr = runCLI(t, append([]string{"storage", "verify", "--connectivity", "-repo", "core.git"}, target...)...)
+ require.Equal(t, exitOK, code, stderr)
+ require.Equal(t, "head sequence 3\nconnectivity ok\nconsistent\n", stdout)
+ format := gittest.Exec(t, cfg, "-C", filepath.Join(cfg.Storages[0].Path, "core.git"), "rev-parse", "--show-ref-format")
+ require.Equal(t, "reftable", strings.TrimSpace(string(format)), "authoritative mode creates reftable repositories")
+}
+
+// TestCLIRepoUsageErrorsDoNotContactServer checks the arguments of graft repo
+// before any server call: the address points nowhere, so a server call would
+// fail with a different error.
+func TestCLIRepoUsageErrorsDoNotContactServer(t *testing.T) {
+ nowhere := []string{"-address", "unix://" + filepath.Join(t.TempDir(), "missing.sock")}
+
+ cases := map[string][]string{
+ "no subcommand": {"repo"},
+ "unknown subcommand": {"repo", "delete", "a.git"},
+ "no repository": {"repo", "create"},
+ "two repositories": {"repo", "create", "a.git", "b.git"},
+ "branch without initial commit": {"repo", "create", "a.git", "--branch", "x"},
+ "unknown object format": {"repo", "create", "a.git", "--object-format", "md5"},
+ "empty default branch": {"repo", "create", "a.git", "--default-branch", ""},
+ "author without name": {"repo", "create", "a.git", "-author", "<[email protected]>"},
+ }
+ for name, args := range cases {
+ code, _, stderr := runCLI(t, append(args, nowhere...)...)
+ require.Equal(t, exitUsage, code, "%s: %s", name, stderr)
+ }
+
+ code, _, stderr := runCLI(t, "repo", "create", "a.git", "-address", "")
+ require.Equal(t, exitUsage, code, stderr)
+ require.Contains(t, stderr, "needs the server address")
+}
+
+// TestCLIRepoHelp checks that graft help lists the repo command and that its
+// help shows the synopsis.
+func TestCLIRepoHelp(t *testing.T) {
+ code, stdout, _ := runCLI(t, "help")
+ require.Equal(t, exitOK, code)
+ require.Contains(t, stdout, " repo create REPO ")
+
+ code, _, stderr := runCLI(t, "repo", "-h")
+ require.Equal(t, exitOK, code, stderr)
+ require.Contains(t, stderr, repoSynopsis)
+ require.Contains(t, stderr, "shared (operator) token")
+
+ code, _, stderr = runCLI(t, "repo")
+ require.Equal(t, exitUsage, code, stderr)
+ require.Contains(t, stderr, repoSynopsis)
+}
+
+func TestRepositoryName(t *testing.T) {
+ require.Equal(t, "demo", repositoryName("demo.git"))
+ require.Equal(t, "demo", repositoryName("group/demo.git"))
+ require.Equal(t, "plain", repositoryName("plain"))
+}
diff --git a/doc/graft/LIMITATIONS.md b/doc/graft/LIMITATIONS.md
index f62bd8c..0fa7f15 100644
--- a/doc/graft/LIMITATIONS.md
+++ b/doc/graft/LIMITATIONS.md
@@ -134,12 +134,13 @@ Git hooks use private.
### Repositories
-- The `graft` CLI and the SDK cannot create a repository. The upstream
- `RepositoryService.CreateRepository` RPC works, but needs a raw gRPC client
- and the shared token (agents may not call it). `graft-bench --create-repo`
- does this. The quickstart creates a bare repository on disk and seeds it
- with a push.
-- `graft clone` needs the branch to exist. An empty repository cannot be cloned.
+- Creating a repository (`graft repo create`, `Repo.Create` in the SDK) needs
+ the shared token: agents may not create repositories. In shadow mode the new
+ repository is not tracked until `graft storage import`.
+- `graft clone` needs the branch to exist. An empty repository cannot be cloned:
+ `graft repo create --initial-commit` gives it a first commit. The CLI and the
+ workspace cannot make the first commit of a repository created without it;
+ the SDK can (`CommitFiles` onto the default branch, without `StartRev`).
- Durability of written objects assumes a local journaling filesystem, ext4 (in
any `data=` mode) or xfs, not NFS. The objects of a write are made durable by
their writer, and the migration of the write's quarantine into the repository
@@ -315,21 +316,19 @@ Git hooks use private.
Ordered roughly by the order we intend to work on them. None of this is a
commitment.
-1. Repository creation in the SDK and the CLI, so that the quickstart no longer
- creates repositories on disk.
-2. Live policy reload, with a file watch or a signal, and a dry-run mode that
+1. Live policy reload, with a file watch or a signal, and a dry-run mode that
reports what a policy change would allow.
-3. Eager derived data for `lastmod` and blame when a change lands, with metrics
+2. Eager derived data for `lastmod` and blame when a change lands, with metrics
for hit rates. Phase 3 computes `graph` and `changed-paths` eagerly.
-4. Changeset log retention and an index by sequence, so long logs can be
+3. Changeset log retention and an index by sequence, so long logs can be
followed without a sequential read.
-5. Client-side help for the conflicts that the server's resolver does not
+4. Client-side help for the conflicts that the server's resolver does not
handle: the `merge_conflict` error already lists the conflicting files and
commits, but the CLI cannot yet materialize them in the workspace for an
agent to fix (phase 2 added server-side resolution, see
[RESOLVE](RESOLVE.md)).
-6. Multi-node cache tiers with explicit invalidation for mutable keys.
-7. Signed changesets and a verifiable export of the log.
+5. Multi-node cache tiers with explicit invalidation for mutable keys.
+6. Signed changesets and a verifiable export of the log.
## Phase 4b limitations
diff --git a/doc/graft/QUICKSTART.md b/doc/graft/QUICKSTART.md
index b826699..7d00589 100644
--- a/doc/graft/QUICKSTART.md
+++ b/doc/graft/QUICKSTART.md
@@ -62,22 +62,24 @@ access check is answered from the policy.
## 4. Create a repository
-There is no create command yet. A repository is a bare Git repository under the
-storage path, found by its relative path. Give it a first commit, because a
-clone needs an existing branch:
+Creating a repository is an operator action: it needs the shared token of the
+`[auth]` section, and an agent token is refused. `--initial-commit` gives the
+repository a first commit (a `README.md`) on its default branch, `main`,
+because a clone needs an existing branch:
```shell
-git init --bare /var/lib/graft/repos/demo.git
-git init seed && cd seed
-git symbolic-ref HEAD refs/heads/main
-printf 'seed\n' > README.md
-git add README.md
-git -c user.name=seed -c [email protected] commit -m "Seed"
-git push /var/lib/graft/repos/demo.git HEAD:refs/heads/main HEAD:refs/heads/feature/demo
-cd ..
+GRAFT_ADDRESS=unix:/var/lib/graft/run/gitaly.sock \
+GRAFT_TOKEN=change-me-shared-token \
+GRAFT_USER=planner \
+GRAFT_AUTHOR="planner <[email protected]>" \
+graft repo create demo.git --initial-commit --branch feature/demo
```
-The seed also creates `feature/demo`, which the builder lands on below.
+The initial commit passes the policy like any write, as the user of
+`GRAFT_USER`: here `planner`, who may write `main`. `--branch feature/demo`
+also creates `feature/demo` at the initial commit, which the builder lands on
+below. If the initial commit fails, run the same command again: on a
+repository without branches it only adds the commit.
## 5. Start the cache daemon
diff --git a/examples/graft/quickstart.sh b/examples/graft/quickstart.sh
index 8cc2eb1..c72853c 100644
--- a/examples/graft/quickstart.sh
+++ b/examples/graft/quickstart.sh
@@ -6,7 +6,7 @@
# Usage: examples/graft/quickstart.sh [WORKDIR]
# Requires: the Gitaly build dependencies (Go, make, and what the bundled Git
# needs to compile, see "Installation" in the Gitaly part of README.md),
-# openssl, git, and curl (optional, for the cache statistics).
+# openssl, and curl (optional, for the cache statistics).
# WORKDIR defaults to a fresh temporary directory.
#
# The steps mirror doc/graft/QUICKSTART.md. The script assumes a Git checkout
@@ -65,19 +65,14 @@ log "Starting Gitaly in standalone mode"
gitaly_pid=$!
wait_for_socket "$work/run/gitaly.sock"
-log "Creating the demo repository with a seed commit on main and feature/demo"
-# There is no create command yet, so the repository is made on disk and seeded
-# with a plain push. Gitaly finds it by its relative path, demo.git.
-git init -q --bare "$work/repos/demo.git"
-git init -q "$work/seed"
-(
- cd "$work/seed"
- git symbolic-ref HEAD refs/heads/main
- printf 'seed\n' > README.md
- git add README.md
- git -c user.name=seed -c [email protected] commit -qm "Seed"
- git push -q "$work/repos/demo.git" HEAD:refs/heads/main HEAD:refs/heads/feature/demo
-)
+log "Creating the demo repository with an initial commit on main and feature/demo"
+# Creating a repository is an operator action: it needs the shared token of
+# [auth] in the configuration. The initial commit passes the policy as
+# GRAFT_USER, here planner, who may write main.
+shared_token="$(sed -n 's/^token = "\(.*\)"$/\1/p' "$work/config.toml")"
+GRAFT_ADDRESS="unix:$work/run/gitaly.sock" GRAFT_STORAGE=default \
+ GRAFT_TOKEN="$shared_token" GRAFT_USER=planner GRAFT_AUTHOR="planner <[email protected]>" \
+ "$work/bin/graft" repo create demo.git --initial-commit --branch feature/demo
log "Starting the graft-cache daemon tier"
"$work/bin/graft-cache" \
diff --git a/internal/gitaly/server/auth/agent_allowlist_test.go b/internal/gitaly/server/auth/agent_allowlist_test.go
index 6ee54dd..6181ee7 100644
--- a/internal/gitaly/server/auth/agent_allowlist_test.go
+++ b/internal/gitaly/server/auth/agent_allowlist_test.go
@@ -451,11 +451,14 @@ var sdkCLIDriftAllowance = map[string]string{}
// rather than agent actions, with the gRPC service they may use outside the agent
// allowlist. The storage core's administration (`graft storage import|state|verify`,
// sdk/storage.go) runs with the server's shared token (doc/graft/STORAGE.md), so
-// agents are not meant to be allowed its RPCs. The scan checks these files
-// separately: every RPC they call must be agent-allowed or belong to the listed
-// service, and each file must still call that service (so an entry cannot go stale).
+// agents are not meant to be allowed its RPCs. So does the creation of a repository
+// (`graft repo create`, sdk/repository.go), which agents may never call. The scan
+// checks these files separately: every RPC they call must be agent-allowed or belong
+// to the listed service, and each file must still call that service (so an entry
+// cannot go stale).
var operatorOnlySources = map[string]string{
- "sdk/storage.go": "gitaly.StorageCoreService",
+ "sdk/storage.go": "gitaly.StorageCoreService",
+ "sdk/repository.go": "gitaly.RepositoryService",
}
// sourceMethodCall matches a Go method call such as `refs.DeleteRefs(ctx, ...)`
diff --git a/internal/graft/e2e/repo_create_test.go b/internal/graft/e2e/repo_create_test.go
new file mode 100644
index 0000000..c422703
--- /dev/null
+++ b/internal/graft/e2e/repo_create_test.go
@@ -0,0 +1,76 @@
+package e2e
+
+import (
+ "bytes"
+ "encoding/json"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+// TestRepoCreateWithTheCLI runs the operator's graft repo create with the real
+// graft binary against a real server in authoritative mode, as the quickstart
+// does: the repository is created with its initial commit and a second branch,
+// registered in the storage core, and an agent then clones it and lands a
+// change. An agent token cannot create a repository.
+func TestRepoCreateWithTheCLI(t *testing.T) {
+ t.Parallel()
+
+ n := newRealNode(t)
+ n.start(t)
+ bin := buildGraftCLI(t)
+
+ const rel = "demo.git"
+ base := append(os.Environ(),
+ "GRAFT_ADDRESS="+n.clientCfg.SocketPath,
+ "GRAFT_STORAGE="+n.cfg.Storages[0].Name,
+ "GRAFT_USER="+workerName(0),
+ "GRAFT_AUTHOR="+workerName(0)+" <"+workerName(0)+"@example.com>",
+ )
+ operator := append(append([]string{}, base...), "GRAFT_TOKEN="+sharedTestToken)
+ agent := append(append([]string{}, base...), "GRAFT_TOKEN="+n.tokens[workerName(0)])
+
+ // An agent may never create a repository.
+ var stderr bytes.Buffer
+ cmd := exec.Command(bin, "repo", "create", rel, "--initial-commit")
+ cmd.Env = agent
+ cmd.Stderr = &stderr
+ require.Error(t, cmd.Run())
+ require.Contains(t, stderr.String(), "PermissionDenied")
+ require.Contains(t, stderr.String(), "creating a repository needs the shared (operator) token")
+
+ var created struct {
+ Repository string `json:"repository"`
+ Created bool `json:"created"`
+ DefaultBranch string `json:"default_branch"`
+ InitialCommit string `json:"initial_commit"`
+ Branches []string `json:"branches"`
+ }
+ out := runGraft(t, bin, operator, "repo", "create", rel, "--initial-commit", "--branch", "feature/demo", "--json")
+ require.NoError(t, json.Unmarshal([]byte(out), &created))
+ require.True(t, created.Created)
+ require.Equal(t, "main", created.DefaultBranch)
+ require.NotEmpty(t, created.InitialCommit)
+ require.Equal(t, []string{"feature/demo"}, created.Branches)
+
+ state, err := n.operator(t, rel).StorageState(n.ctx)
+ require.NoError(t, err)
+ require.True(t, state.Tracked, "the gate registers the repository it creates")
+
+ // The agent clones the new repository and lands a change on main.
+ dir := filepath.Join(t.TempDir(), "demo")
+ runGraft(t, bin, agent, "clone", n.clientCfg.SocketPath, rel, dir, "--branch", "main")
+ readme, err := os.ReadFile(filepath.Join(dir, "README.md"))
+ require.NoError(t, err)
+ require.Equal(t, "# demo\n", string(readme))
+ require.NoError(t, os.WriteFile(filepath.Join(dir, "hello.txt"), []byte("hello\n"), 0o644))
+ runGraft(t, bin, agent, "commit", "-C", dir, "-m", "Add hello", "--land", "main")
+
+ landed, err := n.agent(t, rel).ResolveRevision(n.ctx, "main")
+ require.NoError(t, err)
+ require.NotEqual(t, created.InitialCommit, landed)
+ n.requireServed(t, rel, map[string]string{"main": landed, "feature/demo": created.InitialCommit})
+}
diff --git a/sdk/doc.go b/sdk/doc.go
index e6029ce..43adcb1 100644
--- a/sdk/doc.go
+++ b/sdk/doc.go
@@ -15,6 +15,9 @@
// calls the server answers with Unavailable (see UnavailableRetry).
// - Blame and PathHistory answer history questions from derived data.
// - Changesets and WatchChangesets read the repository's changeset log.
+// - Create creates an empty repository, and HasBranches tells whether it
+// is still empty (RepositoryService; operators only, with the shared
+// token).
//
// Errors are standard gRPC errors. Structured details of landing and commit
// failures are available through LandError, CommitFilesError and the Is*
diff --git a/sdk/errors.go b/sdk/errors.go
index bef5866..7afb545 100644
--- a/sdk/errors.go
+++ b/sdk/errors.go
@@ -23,6 +23,12 @@ func IsNotFound(err error) bool {
return Code(err) == codes.NotFound
}
+// IsAlreadyExists reports whether err is an AlreadyExists error, for example
+// Create of a repository that exists already.
+func IsAlreadyExists(err error) bool {
+ return Code(err) == codes.AlreadyExists
+}
+
// LandError returns the structured details of a failed Land call, if any.
func LandError(err error) (*gitalypb.UserLandError, bool) {
return detailOf[*gitalypb.UserLandError](err)
diff --git a/sdk/repository.go b/sdk/repository.go
new file mode 100644
index 0000000..f462bb9
--- /dev/null
+++ b/sdk/repository.go
@@ -0,0 +1,79 @@
+package sdk
+
+import (
+ "context"
+
+ "google.golang.org/grpc/codes"
+ "google.golang.org/grpc/status"
+
+ "github.com/feder-cr/git-ai/proto/go/gitalypb"
+)
+
+// CreateOptions describes a repository created by Create.
+type CreateOptions struct {
+ // DefaultBranch is the branch that HEAD of the new repository points to,
+ // without the refs/heads/ prefix. If empty, the server's default (main) is
+ // used.
+ DefaultBranch string
+ // ObjectFormat is the object hash of the new repository: "sha1" or
+ // "sha256". If empty, the server's default is used.
+ ObjectFormat string
+}
+
+// Create creates the repository on the server, empty. Only an operator may
+// create repositories: the call needs the shared token (WithToken), and an
+// agent token fails with PermissionDenied. A repository that exists already
+// fails with AlreadyExists (see IsAlreadyExists).
+//
+// With the storage core in authoritative mode the server registers the new
+// repository in the storage core; in shadow mode it is created untracked and
+// StorageImport brings it in (see doc/graft/STORAGE.md).
+//
+// An empty repository has no branch to clone: CommitFiles onto its default
+// branch, without StartRev, makes its first commit.
+func (r *Repo) Create(ctx context.Context, opts CreateOptions) error {
+ format, err := objectFormat(opts.ObjectFormat)
+ if err != nil {
+ return err
+ }
+
+ _, err = r.repositories().CreateRepository(ctx, &gitalypb.CreateRepositoryRequest{
+ Repository: r.repository(),
+ DefaultBranch: []byte(trimBranchPrefix(opts.DefaultBranch)),
+ ObjectFormat: format,
+ })
+ return err
+}
+
+// HasBranches reports whether the repository has at least one branch. It
+// fails with NotFound if the repository does not exist. Like Create, it needs
+// the shared token.
+func (r *Repo) HasBranches(ctx context.Context) (bool, error) {
+ resp, err := r.repositories().HasLocalBranches(ctx, &gitalypb.HasLocalBranchesRequest{
+ Repository: r.repository(),
+ })
+ if err != nil {
+ return false, err
+ }
+ return resp.GetValue(), nil
+}
+
+// objectFormat maps the object format of CreateOptions to its protobuf value.
+func objectFormat(format string) (gitalypb.ObjectFormat, error) {
+ switch format {
+ case "":
+ return gitalypb.ObjectFormat_OBJECT_FORMAT_UNSPECIFIED, nil
+ case "sha1":
+ return gitalypb.ObjectFormat_OBJECT_FORMAT_SHA1, nil
+ case "sha256":
+ return gitalypb.ObjectFormat_OBJECT_FORMAT_SHA256, nil
+ default:
+ return gitalypb.ObjectFormat_OBJECT_FORMAT_UNSPECIFIED,
+ status.Errorf(codes.InvalidArgument, "object format %q: want sha1 or sha256", format)
+ }
+}
+
+// repositories returns the repository service client on the connection of the client.
+func (r *Repo) repositories() gitalypb.RepositoryServiceClient {
+ return gitalypb.NewRepositoryServiceClient(r.client.conn)
+}
diff --git a/sdk/repository_test.go b/sdk/repository_test.go
new file mode 100644
index 0000000..fb64426
--- /dev/null
+++ b/sdk/repository_test.go
@@ -0,0 +1,52 @@
+package sdk
+
+import (
+ "context"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+ "google.golang.org/grpc/codes"
+ "google.golang.org/grpc/status"
+
+ "github.com/feder-cr/git-ai/proto/go/gitalypb"
+)
+
+func TestObjectFormat(t *testing.T) {
+ t.Parallel()
+
+ for format, expected := range map[string]gitalypb.ObjectFormat{
+ "": gitalypb.ObjectFormat_OBJECT_FORMAT_UNSPECIFIED,
+ "sha1": gitalypb.ObjectFormat_OBJECT_FORMAT_SHA1,
+ "sha256": gitalypb.ObjectFormat_OBJECT_FORMAT_SHA256,
+ } {
+ got, err := objectFormat(format)
+ require.NoError(t, err, format)
+ require.Equal(t, expected, got, format)
+ }
+
+ _, err := objectFormat("SHA1")
+ require.Equal(t, codes.InvalidArgument, Code(err))
+}
+
+// TestCreateRejectsAnUnknownObjectFormat checks that Create refuses an unknown
+// object format before it contacts the server, which the address of the client
+// does not lead to.
+func TestCreateRejectsAnUnknownObjectFormat(t *testing.T) {
+ t.Parallel()
+
+ client, err := Dial(context.Background(), "unix:///nonexistent/graft.sock")
+ require.NoError(t, err)
+ t.Cleanup(func() { _ = client.Close() })
+
+ err = client.Repo("a.git").Create(context.Background(), CreateOptions{ObjectFormat: "md5"})
+ require.Equal(t, codes.InvalidArgument, Code(err))
+ require.Contains(t, err.Error(), `object format "md5": want sha1 or sha256`)
+}
+
+func TestIsAlreadyExists(t *testing.T) {
+ t.Parallel()
+
+ require.True(t, IsAlreadyExists(status.Error(codes.AlreadyExists, "repository exists already")))
+ require.False(t, IsAlreadyExists(status.Error(codes.NotFound, "x")))
+ require.False(t, IsAlreadyExists(nil))
+}