Plan: Projects, the home of everything about running software
A project is one deployable thing with one source: a repository hosted on g1t, mirrored or connected from GitHub, GitLab or Bitbucket, later anything behind the same port, and a root directory in it, so one repository can carry several projects. Deployments, environments, domains, secrets, dependencies, owners, health and upkeep move to the project; branches, pull requests and review stay with the repository. Groups organise projects for people; dependencies (in the UI or .g1t/project.yml) drive reference variables, preview stacks, release order, impact on pull requests and agents' context. The old use of 'project' for a brief's issue graph is now 'outcome'.
1 file+154−30/1 viewed
| 316 | 316 | | --- | --- | | |
| 317 | 317 | | **Workspace** | A company or team: its people, repos, agents, budget and policies. | | |
| 318 | 318 | | **Initiative** | A business outcome with an owner and measurable results, e.g. "move billing to usage-based pricing". Spans any number of repos. | | |
| 319 | − | | **Project** | One deliverable inside an initiative: a brief and its graph of issues. | | |
| 319 | + | | **Outcome** | One deliverable inside an initiative: a brief and its graph of issues (shown as **Plan**). Called "project" before 2026-10-04; that name now means what [Projects](#projects) describes. | | |
| 320 | 320 | | **Issue / Pull request** | As above. An issue may touch several repos; a pull request for it then holds one fork per repo and they land together. | | |
| 321 | 321 | ||
| 322 | 322 | How it feeds up, and what is built: | |
| 436 | 436 | ||
| 437 | 437 | - **Mission control.** The signed-in home page: every running session, every | |
| 438 | 438 | issue waiting on a decision, and what merged, across all repos. | |
| 439 | − | - **Projects.** Group issues across repos toward one outcome and track how | |
| 440 | − | many are open, racing, or merged. | |
| 439 | + | - **Outcomes.** Group issues across repos toward one result and track how | |
| 440 | + | many are open, racing, or merged. (What [Projects](#projects) means is | |
| 441 | + | below.) | |
| 441 | 442 | - **Steering.** Send a message to a running pull request, or to all pull requests on an | |
| 442 | 443 | issue at once, without stopping them. | |
| 443 | 444 | - **Automations.** Rules that start work without a person (next section). | |
| 567 | 568 | Later, toward GitLab's DevOps breadth: environment protection rules, | |
| 568 | 569 | package and container registries, releases, container hosting. | |
| 569 | 570 | ||
| 571 | + | ## Projects | |
| 572 | + | ||
| 573 | + | > **2026-10-04:** the user: "an extra dimension of Projects so it's not | |
| 574 | + | > just repositories … where a lot of things can live", "very Vercel | |
| 575 | + | > like", with dependencies across projects "the Platform Engineering / | |
| 576 | + | > Port route", and "the repository is *part* of a project: you could be | |
| 577 | + | > mirroring it from GitHub/GitLab/Bitbucket, or you could let us host it | |
| 578 | + | > for you", with room for Mercurial or anything else later. | |
| 579 | + | ||
| 580 | + | **A project is the thing you are building and running; a repository is | |
| 581 | + | where some of its code lives.** Everything that is about running software | |
| 582 | + | (deployments, environments, domains, secrets, dependencies, owners, | |
| 583 | + | health, upkeep) belongs to the project. What is about the code itself | |
| 584 | + | (branches, pull requests, review, merge rules) stays with the repository. | |
| 585 | + | That split is what lets the code live anywhere. | |
| 586 | + | ||
| 587 | + | ### The model | |
| 588 | + | ||
| 589 | + | | | What it is | Like | | |
| 590 | + | | --- | --- | --- | | |
| 591 | + | | **Workspace** | The company or team. Members, billing, plans, shared secrets. | Vercel team, GitLab group, GitHub org | | |
| 592 | + | | **Group** | An optional named set of projects, one level: "Payments", "Mobile". For browsing, ownership and shared settings. | GitLab subgroup, Backstage system, Port domain | | |
| 593 | + | | **Project** | One deployable thing: a site, an API, a worker, a library. Has exactly one **source**. | Vercel project, Port service, Backstage component | | |
| 594 | + | | **Source** | Where its code is: a repository and a **root directory** in it. | Vercel's connected repo + root directory | | |
| 595 | + | | **Dependency** | Project A uses project B: calls its API, consumes its package, reads its queue. | Port relations, Backstage `dependsOn` | | |
| 596 | + | ||
| 597 | + | - **One project, one source; one repository, any number of projects.** A | |
| 598 | + | project builds from exactly one place, which keeps it as simple as | |
| 599 | + | Vercel's. A monorepo is several projects on one repository, each with | |
| 600 | + | its own root directory (`apps/web`, `services/api`), and a push builds | |
| 601 | + | only the projects whose root it touched. The common case stays 1:1, and | |
| 602 | + | every existing repository gets a project of its own name when this | |
| 603 | + | ships, so nobody has to set anything up. | |
| 604 | + | - **Groups are for people; dependencies are for software.** Groups decide | |
| 605 | + | where a project shows up and who owns it. Dependencies decide what | |
| 606 | + | happens when one changes. Neither replaces the other, and a dependency | |
| 607 | + | can cross groups. | |
| 608 | + | ||
| 609 | + | ### Sources: where the code lives | |
| 610 | + | ||
| 611 | + | A source is an adapter behind one interface (`SourcePort`: clone URL, | |
| 612 | + | branches, commits, pushes as events, pull requests if it has them): | |
| 613 | + | ||
| 614 | + | | Source | Code lives | g1t gets pushes by | Pull requests | | |
| 615 | + | | --- | --- | --- | --- | | |
| 616 | + | | **Hosted on g1t** (today) | Artifacts | its own events | g1t's, with agents, the queue, review | | |
| 617 | + | | **Mirrored** from GitHub, GitLab or Bitbucket | Both; g1t keeps a copy | the provider's webhook, then fetch | The provider's, read into g1t; agents open theirs there | | |
| 618 | + | | **Connected, not copied** | The provider only | webhook | The provider's | | |
| 619 | + | | **Later:** Mercurial, Perforce, a tarball upload | Behind the same port | per adapter | per adapter | | |
| 620 | + | ||
| 621 | + | A mirrored or connected project still gets everything that is the | |
| 622 | + | project's: previews on its pull requests (a status and a comment on | |
| 623 | + | GitHub's), production on its default branch, secrets, dependencies, | |
| 624 | + | upkeep agents. That is the on-ramp: a team keeps GitHub and gets g1t's | |
| 625 | + | deployments and agents first, and moves the code later or never. | |
| 626 | + | Bring-your-own-git is also why the project, not the repository, holds the | |
| 627 | + | URL `g1t.sh/<workspace>/<project>`. | |
| 628 | + | ||
| 629 | + | ### What lives on a project | |
| 630 | + | ||
| 631 | + | | | Today it is on | Moves to the project | | |
| 632 | + | | --- | --- | --- | | |
| 633 | + | | Deployments: production, previews, build settings, root directory, framework | The repository | Yes | | |
| 634 | + | | Environments: production, preview, and custom ones (`staging`) with protection rules (required approvers, branch limits) | Nowhere yet | New, on the project | | |
| 635 | + | | Domains: `<project>--<workspace>.g1t.page`, and custom domains | The repository's name | Yes | | |
| 636 | + | | Secrets and variables | The repository | Yes. Workspace rows link to projects instead of repositories. A repository's workflows read the rows of its project (with several projects on one repository, the one marked as the repository's default). | | |
| 637 | + | | Dependencies | Nowhere | New | | |
| 638 | + | | Owners, on-call, links (docs, dashboards, runbooks) | Nowhere | New: the catalog's metadata | | |
| 639 | + | | Health: scorecards (has an owner, CI passes, dependencies current, no open security alerts, deploys within N days) | Nowhere | New | | |
| 640 | + | | Upkeep agents: dependency updates, security alerts | The plan | Scoped per project | | |
| 641 | + | | Logs and analytics of the running app | Nowhere | New: requests, errors and CPU per environment, from Workers analytics | | |
| 642 | + | | Branches, pull requests, review, merge rules, the queue, webhooks | The repository | Stay | | |
| 643 | + | ||
| 644 | + | ### Dependencies: why this gets powerful | |
| 645 | + | ||
| 646 | + | Declared in the UI, or in the source as `.g1t/project.yml` (which wins | |
| 647 | + | when present, as `catalog-info.yaml` does in Backstage): | |
| 648 | + | ||
| 649 | + | ```yaml | |
| 650 | + | name: web | |
| 651 | + | root: apps/web | |
| 652 | + | dependsOn: | |
| 653 | + | - project: api # calls its HTTP API | |
| 654 | + | as: API_URL # its URL, per environment, as a variable | |
| 655 | + | - project: ui-kit # consumes its package | |
| 656 | + | ``` | |
| 657 | + | ||
| 658 | + | What g1t does with them: | |
| 659 | + | ||
| 660 | + | 1. **Reference variables.** `API_URL` above resolves to `api`'s production | |
| 661 | + | URL in production and to the matching preview in a preview, the way | |
| 662 | + | Railway's `${{ api.URL }}` references work. No hard-coded URLs. | |
| 663 | + | 2. **Preview stacks.** A pull request on `api` gets its own preview, and | |
| 664 | + | **Preview with dependents** builds `web`'s preview pointed at it, so a | |
| 665 | + | reviewer clicks through the whole change across projects. A change that | |
| 666 | + | spans repositories (one issue, one fork per repository) gets one stack. | |
| 667 | + | 3. **Release order.** Production deploys go out in dependency order; a | |
| 668 | + | change set across projects lands through the queue together or not at | |
| 669 | + | all. | |
| 670 | + | 4. **Impact on every pull request.** "Changes `api`; `web` and `mobile` | |
| 671 | + | depend on it." Agents get the graph in their context: an agent | |
| 672 | + | changing an API opens follow-up issues on the projects that call it, | |
| 673 | + | and reviewers see what else could break. | |
| 674 | + | 5. **Upkeep across the graph.** A vulnerable package in `ui-kit` opens | |
| 675 | + | issues, assigned to agents, on every project that consumes it. | |
| 676 | + | 6. **Scorecards turn into work.** A project failing a scorecard check | |
| 677 | + | ("no owner", "dependencies 90 days old") gets an issue an agent can fix. | |
| 678 | + | That is the Port idea with the work done for you. | |
| 679 | + | 7. **The map.** A workspace's projects as a graph, coloured by health and | |
| 680 | + | by what is deploying now. | |
| 681 | + | ||
| 682 | + | ### Pages | |
| 683 | + | ||
| 684 | + | - `g1t.sh/<workspace>`: projects first (grouped, with health and | |
| 685 | + | production status), then repositories. | |
| 686 | + | - `g1t.sh/<workspace>/<project>`: overview (production, latest previews, | |
| 687 | + | health, owners, dependencies both ways), **Deployments**, | |
| 688 | + | **Environments**, **Secrets and variables**, **Logs**, **Settings** | |
| 689 | + | (source, root directory, build, domains, groups, owners). | |
| 690 | + | - A hosted repository keeps its code pages; from a project they are its | |
| 691 | + | **Code** tab. A repository page lists the projects built from it. | |
| 692 | + | ||
| 693 | + | ### Services | |
| 694 | + | ||
| 695 | + | - `services/projects` (new): projects, groups, sources, dependencies, | |
| 696 | + | owners, scorecards. Events `project.created`, `project.updated`, | |
| 697 | + | `dependency.changed`. | |
| 698 | + | - `services/deployments`: keyed by project instead of repository. | |
| 699 | + | - Secrets and variables: the scope becomes workspace → project. | |
| 700 | + | - Sources: the hosted adapter wraps `services/repos`; a mirror adapter | |
| 701 | + | per provider in `services/integrations`, which already holds those | |
| 702 | + | connections. | |
| 703 | + | ||
| 704 | + | ### Build order | |
| 705 | + | ||
| 706 | + | 1. **Projects as the home of deployments and secrets**, 1:1 with every | |
| 707 | + | existing repository: the service, the pages, deployments and secrets | |
| 708 | + | moved to the project, `<project>--<workspace>.g1t.page`. | |
| 709 | + | 2. **Dependencies:** declared in the UI and `.g1t/project.yml`, reference | |
| 710 | + | variables, impact on pull requests and in agents' context, the map. | |
| 711 | + | 3. **Preview stacks** and cross-project change sets. | |
| 712 | + | 4. **Monorepos:** several projects on one repository, each with a root | |
| 713 | + | directory, building only what a push touched. | |
| 714 | + | 5. **Mirrored sources:** GitHub first, then GitLab and Bitbucket. | |
| 715 | + | 6. **Groups, owners, scorecards** feeding the upkeep agents. | |
| 716 | + | 7. **Environments** with protection rules; custom domains; logs. | |
| 717 | + | ||
| 718 | + | 1 and 2 serve the competition directly (multi-agent coordination across | |
| 719 | + | projects is 25% of the score); 3 is the demo's best moment if time allows. | |
| 720 | + | ||
| 570 | 721 | ## Agents and models | |
| 571 | 722 | ||
| 572 | 723 | ### Defining an agent |