| 1 | --- |
| 2 | title: Projects |
| 3 | description: A project is what you build and run. Its code lives in its source; its deployments, secrets and variables belong to the project. |
| 4 | --- |
| 5 | |
| 6 | A project is the thing you are building and running: a site, an API, a |
| 7 | worker, a library. Every project has one **source**, where its code lives, |
| 8 | and everything about running it belongs to the project: |
| 9 | |
| 10 | | Belongs to the project | Belongs to its repository | |
| 11 | | --- | --- | |
| 12 | | [Deployments](/guides/deployments/): production and previews | Branches and commits | |
| 13 | | Its address on g1t.page | Issues and pull requests | |
| 14 | | [Secrets and variables](/guides/secrets-and-variables/) | Review, merge rules and the [merge queue](/guides/merge-queue/) | |
| 15 | | Its name, description and root directory | Webhooks | |
| 16 | |
| 17 | That split is what lets the code live anywhere while the project stays the |
| 18 | same. |
| 19 | |
| 20 | ## Your projects |
| 21 | |
| 22 | Every repository on g1t is a project of its own name, with nothing to set |
| 23 | up: `g1t.sh/acme/web` is the `web` project, built from the `acme/web` |
| 24 | repository. Repositories made before projects existed became projects the |
| 25 | first time their workspace was opened. |
| 26 | |
| 27 | A workspace's page, `g1t.sh/<workspace>`, shows your pinned projects and |
| 28 | its most active ones, each with where it is deployed, its latest build, and |
| 29 | its open issues and pull requests. **All projects** in the sidebar lists |
| 30 | every one, with search, filters and sorting; see |
| 31 | [the Projects page](/guides/workspaces/#the-projects-page). The sidebar keeps |
| 32 | your [pinned and recent projects](/guides/workspaces/#pinned-and-recent-projects). |
| 33 | |
| 34 | ## A project's pages |
| 35 | |
| 36 | | Page | Address | | |
| 37 | | --- | --- | --- | |
| 38 | | **Overview** | `g1t.sh/<workspace>/<project>` | What it is and its links; production wherever it is deployed, or for a library its packages; the steps that apply to it; what is in progress, active branches, the latest commits, and its About. See [the overview](#the-overview). | |
| 39 | | **Code** | `…/code` | The repository's files, commits and branches. | |
| 40 | | **Issues**, **Pull requests**, **Merge queue**, **Plan** | `…/issues` and so on | As they always were. | |
| 41 | | **Actions** | `…/actions` | [GitHub Actions workflows](/guides/actions/). | |
| 42 | | **Deployments** | `…/deployments` | What is up now and every build. | |
| 43 | | **Settings** | `…/settings` | See below. | |
| 44 | |
| 45 | Every address that pointed into a repository before still works: the |
| 46 | project has the repository's name. |
| 47 | |
| 48 | ## The overview |
| 49 | |
| 50 | A project's overview is the first page you see. People with a |
| 51 | [role](/guides/access-and-roles/) on its repository see all of it; anyone |
| 52 | else sees what the project shares publicly. |
| 53 | |
| 54 | | Part | What it shows | |
| 55 | | --- | --- | |
| 56 | | **What it is** | A badge, such as **App, deployed elsewhere** or **Library**, beside its homepage and docs. People who can change its settings open the badge to change [what it is](#what-a-project-is) in one click. | |
| 57 | | **Production** | For an app [deployed on g1t](/guides/deployments/): a screenshot of the live site, which opens it; its address, the commit it runs and when it went up; **Visit** and **Redeploy**. For an app deployed elsewhere: production's address and **Visit**, with the default branch's latest commit. For an app nobody has placed yet: one question, where it runs. | |
| 58 | | **Packages** | For a library or a tool, in place of Production: the packages its repository publishes, each with its latest version and how to install it, or how to publish a first one. | |
| 59 | | **Documentation**, **Homepage** | For docs, where they are read; for anything else, its homepage. | |
| 60 | | **Get to production**, **Ship a release** or **Get started** | The [checklist](#the-checklist) for what the project is, until every step is done or you dismiss it. | |
| 61 | | **Right now** | Agents at work, and open pull requests moving from working to landed. | |
| 62 | | **Needs you** | What is waiting on a person: a failed production build, a pull request to merge or review, a stuck run. | |
| 63 | | **Active branches** | Branches other than the default, newest first. See [active branches](#active-branches). | |
| 64 | | **Recent changes**, **Latest on main**, **Activity**, **Previews** | What landed, the default branch's latest commits, everything that happened, and the previews that are up. | |
| 65 | | **About** | Its description, its [links](#links), what it is, and its latest release (its newest tag). People who can change its settings edit the description and links from here. | |
| 66 | | **Health**, **Dependencies**, **Clone** | How often checks pass, recent builds and open issues by age; what it uses and what uses it; the clone address. | |
| 67 | |
| 68 | ### The checklist |
| 69 | |
| 70 | People with a role on its repository see a card that counts what the |
| 71 | project has done, such as **3/5**. Its steps follow |
| 72 | [what the project is](#what-a-project-is): only an app deployed on g1t is |
| 73 | asked to deploy, add a domain or open a preview. Each step is worked out |
| 74 | from the project itself, and each links to where you do it. The card goes |
| 75 | away when every step is done. To hide it sooner, choose **×** on it. That |
| 76 | hides it for this project in this browser only. |
| 77 | |
| 78 | | What it is | Card | Steps | |
| 79 | | --- | --- | --- | |
| 80 | | App or site, deployed on g1t | **Get to production** | [Below](#get-to-production). | |
| 81 | | Library, tool | **Ship a release** | [Below](#ship-a-release). | |
| 82 | | App, deployed elsewhere | **Get started** | Push code; add production's address; add checks on pull requests; repository instructions; a first issue for g1t. | |
| 83 | | App nobody has placed yet | **Get started** | Push code; say where it runs; add checks on pull requests; repository instructions; a first issue for g1t. | |
| 84 | | Documentation | **Get started** | Push code; add where its docs are read (a docs or homepage address); repository instructions; a first issue for g1t. | |
| 85 | | Something else | **Get started** | Push code; add its links; repository instructions; a first issue for g1t. | |
| 86 | |
| 87 | ### Get to production |
| 88 | |
| 89 | For an app or site deployed on g1t: |
| 90 | |
| 91 | | Step | Done when | Links to | |
| 92 | | --- | --- | --- | |
| 93 | | Connect a source or push code | The default branch has a commit, or the source is a mirror. | **Code**, which shows how to push, or how to have your coding agent start the project. | |
| 94 | | Deploy to production | A production build has gone live. | Deployments settings, or **Deployments** once they are on. | |
| 95 | | Add a custom domain | The project has a [custom domain](/guides/deployments/#custom-domains). | Domain settings. | |
| 96 | | Open a preview | A branch or pull request has had a [preview](/guides/deployments/#previews-of-branches). | A new pull request. | |
| 97 | | Set up repository instructions | `AGENTS.md` or `CLAUDE.md` is at the root of the default branch. | The instructions on the **Agents** page. See [repository instructions](/guides/working-with-g1t/#repository-instructions). | |
| 98 | | Assign a first issue to g1t | g1t has had a run, a pull request or an issue here. | A new issue. | |
| 99 | |
| 100 | ### Ship a release |
| 101 | |
| 102 | A library or a tool does not deploy, so its card counts the steps to a |
| 103 | first release instead: |
| 104 | |
| 105 | | Step | Done when | Links to | |
| 106 | | --- | --- | --- | |
| 107 | | Connect a source or push code | As above. | **Code**. | |
| 108 | | Add checks on pull requests | The repository has a workflow in `.g1t/workflows`. Its runs are every pull request's checks. | **Actions**, which offers to add a starter workflow. | |
| 109 | | Tag a release or publish a package | A package its repository publishes has a version. For [Composer](/guides/composer/) and [Go](/guides/go/), pushing a tag such as `v1.0.0` is the release. | The package's page, or the guide for its registry. | |
| 110 | | Set up repository instructions | As above. | The **Agents** page. | |
| 111 | | Assign a first issue to g1t | As above. | A new issue. | |
| 112 | |
| 113 | ## What a project is |
| 114 | |
| 115 | A project is one of these, and its overview follows: |
| 116 | |
| 117 | | What it is | Its overview shows | |
| 118 | | --- | --- | |
| 119 | | **App or site, deployed on g1t** | Production on g1t.page, with previews and domains, and **Get to production**. | |
| 120 | | **App or site, deployed elsewhere** | Production at the address you give, deployed by your own pipeline, with **Visit**. It is never asked to turn on Deployments; Deployment settings stay one link away. | |
| 121 | | **Library or package** | The packages its repository publishes and how to install them, and **Ship a release**. | |
| 122 | | **Tool or CLI** | The same as a library: its packages and releases. | |
| 123 | | **Documentation** | Where its docs are read. Docs can be published on g1t.page too, by turning on Deployments. | |
| 124 | | **Something else** | Its homepage and links. | |
| 125 | |
| 126 | Its **Deployments** page stays in the sidebar whatever it is. |
| 127 | |
| 128 | ### How g1t works it out |
| 129 | |
| 130 | Until you say, g1t works it out for itself, in this order: |
| 131 | |
| 132 | 1. If [Deployments](/guides/deployments/) are on for the project, it is |
| 133 | an app deployed on g1t. |
| 134 | 2. If its repository publishes a package other than a container image, |
| 135 | such as a [Composer](/guides/composer/) or [npm](/guides/npm/) |
| 136 | package, it is a library. |
| 137 | 3. If the files at the root of its default branch (or of its root |
| 138 | directory) say what it is, it is that: |
| 139 | |
| 140 | | File | Says | |
| 141 | | --- | --- | |
| 142 | | `wrangler.jsonc`, `wrangler.json` or `wrangler.toml` | An app. | |
| 143 | | `mkdocs.yml`, `book.toml`, `docusaurus.config.js` (or `.ts`, `.mjs`) or `antora.yml` | Documentation. | |
| 144 | | `composer.json` | A library when its `type` is anything but `project`, such as `library`; or it has no `type`, has `autoload`, and has no `public/index.php`. | |
| 145 | | `Cargo.toml` | A library when it builds a library (`[lib]` or `src/lib.rs`) and no binary (`[[bin]]` or `src/main.rs`). | |
| 146 | | `go.mod` | A library when no `.go` file at the root is `package main`. | |
| 147 | | `pyproject.toml` | A library when it has a build backend and depends on no app framework, such as Django, Flask or FastAPI. | |
| 148 | | `package.json` | A tool when it has `bin` and nothing to import (no `main`, `module` or `exports`); a library when it has `main`, `exports`, `module`, `files` or `bin`; either way only with no `start` or `dev` script and no app framework such as Next.js, Astro, Nuxt, Remix or SvelteKit. | |
| 149 | |
| 150 | The language's own manifest is read before `package.json`, which many |
| 151 | projects carry only for tooling. An `index.html` at the root makes it |
| 152 | an app. |
| 153 | 4. Anything else is an app. |
| 154 | |
| 155 | The files are read again on every push to the default branch. |
| 156 | |
| 157 | An app found this way runs on g1t only while Deployments are on. Until |
| 158 | you say where it runs, its overview asks, in place of production: |
| 159 | **Deploy on g1t**, **It's deployed elsewhere** (with production's |
| 160 | address), or **It isn't deployed** (a library, a tool, documentation or |
| 161 | something else). |
| 162 | |
| 163 | ### Choosing it yourself |
| 164 | |
| 165 | From the overview, open the badge beside its name, such as **App**, and |
| 166 | choose one. Or open **Settings**, then **General**, and under **What it |
| 167 | is** choose **Detect automatically**, which shows what was detected and |
| 168 | why, or one of the kinds above. **App or site, deployed elsewhere** asks |
| 169 | for production's address. |
| 170 | |
| 171 | Choosing a library, a tool or something else while Deployments are on is |
| 172 | refused: turn them off first under **Settings**, then **Deployments**; |
| 173 | g1t does not turn them off for you. While it is set that way, Deployments |
| 174 | cannot be turned on. Turning Deployments on for an app deployed elsewhere |
| 175 | makes it an app deployed on g1t. |
| 176 | |
| 177 | Changing what it is needs the role that changes the project's settings. |
| 178 | |
| 179 | ### Active branches |
| 180 | |
| 181 | Up to five branches other than the default, the most recently changed |
| 182 | first. Each shows its last commit and who made it, how many commits it is |
| 183 | ahead of the default branch and behind it, and its open pull request, |
| 184 | with its checks, and preview, if it has them. A branch with no pull |
| 185 | request links to opening one, unless it has nothing the default branch |
| 186 | lacks, which says **Nothing to merge**. |
| 187 | |
| 188 | Ahead and behind are exact, merges included. g1t reads up to 1,000 |
| 189 | commits of each history to find where the two meet; a branch that left |
| 190 | the default branch further back than that shows no counts. Ten branches |
| 191 | are read, those with open pull requests first; a project with more says |
| 192 | how many it has. |
| 193 | |
| 194 | ## Links |
| 195 | |
| 196 | A project has a **homepage**, a **docs** address, and up to 10 other |
| 197 | links, each a label and an address, such as a status page or its listing |
| 198 | in a registry. They show in its overview's About and beside what it is, |
| 199 | on its card on its workspace's page, in its workspace's Projects, and on |
| 200 | Explore for a public project. |
| 201 | |
| 202 | To set them, open **Settings**, then **General**, and fill in **Links**; |
| 203 | or choose the pencil on the overview's **About**. Each is an http or |
| 204 | https address; `https://` is added when you leave it out. A label left |
| 205 | empty is the address's host name. Removing every row of other links |
| 206 | clears them. |
| 207 | |
| 208 | A repository's own project shows the repository's website as its |
| 209 | homepage until you give the project one of its own. For an app deployed |
| 210 | on g1t, its g1t.page address still shows as production; set the homepage |
| 211 | to production's own domain if you have one. |
| 212 | |
| 213 | ## Settings |
| 214 | |
| 215 | A project's **Settings** has a tab for each part: |
| 216 | |
| 217 | | Tab | What it holds | |
| 218 | | --- | --- | |
| 219 | | **General** | The project's name and description, its source, its **root directory**, [what it is](#what-a-project-is), and its [links](#links). A project shows its repository's description, and follows it as it changes, until you give the project one of its own; **Use the repository's description** goes back. | |
| 220 | | **Deployments** | Production, previews, build command, output directory and idle days. See [Deployments](/guides/deployments/#settings). | |
| 221 | | **Domains** | Custom domains for production. See [custom domains](/guides/deployments/#custom-domains). | |
| 222 | | **Dependencies** | The projects this one uses, and the ones that use it. See [Dependencies](#dependencies). | |
| 223 | | **Agents** | How g1t's agents pick up work here, and what they read first. | |
| 224 | | **Guardrails** | What agents may reach, run and spend while they work here. See [guardrails](/guides/guardrails/). | |
| 225 | | **Repository** | The repository's name, description, website, [topics](/guides/search/#what-is-indexed) and default branch, and its danger zone: visibility, archive, transfer and delete. See [Managing a repository](/guides/managing-repositories/). | |
| 226 | | **Access** | Who has a [role](/guides/access-and-roles/) on the repository, and invitations. | |
| 227 | | **Branches and merging** | Auto-merge, how g1t's agents review and revise, the CODEOWNERS file's errors, and what the rules hold for the default branch. | |
| 228 | | **Rules** | [Rulesets](/guides/rules/): branch and tag protection, [required status checks](/guides/pull-requests/#required-status-checks), approvals, the merge queue, and rules for agents' changes, with Insights. | |
| 229 | | **Secrets and variables** | The project's rows. See [Secrets and variables](/guides/secrets-and-variables/). | |
| 230 | | **Runners** | The project's own [self-hosted runners](/guides/self-hosted-runners/), and where its agents' work runs. | |
| 231 | | **Webhooks** | The repository's [webhooks](/guides/webhooks/). | |
| 232 | |
| 233 | The **root directory** says where in the repository the project lives, |
| 234 | such as `apps/web`. Builds run there. Leave it empty for the whole |
| 235 | repository. |
| 236 | |
| 237 | Each tab needs a [role](/guides/access-and-roles/) on the project's |
| 238 | repository: |
| 239 | |
| 240 | | Tab | Needs | |
| 241 | | --- | --- | |
| 242 | | **General**, **Dependencies**, **Agents**, and on **Repository** its description, website and topics | Maintain | |
| 243 | | **Branches and merging**, **Rules**, **Guardrails** | Maintain | |
| 244 | | **Access**: seeing who has a role; changing it | Write; Admin | |
| 245 | | **Deployments**, **Domains**, **Secrets and variables**, **Runners**, **Webhooks** | Admin | |
| 246 | | On **Repository**: its name, default branch, and the danger zone (visibility, archive) | Admin | |
| 247 | | Transfer and delete | An owner of the workspace | |
| 248 | |
| 249 | Someone without the role does not see the tab. |
| 250 | |
| 251 | ## Create a project |
| 252 | |
| 253 | 1. Choose **New project** in the sidebar, or go to `g1t.sh/new`. |
| 254 | 2. Choose where its code comes from: |
| 255 | - **Start empty**: a new repository on g1t. |
| 256 | - **Import code**: copy a public repository from GitHub or any git host |
| 257 | into a new one on g1t, with every branch and tag (up to 40 MB of |
| 258 | history). |
| 259 | - **Import from GitHub**: import, mirror or move repositories you can |
| 260 | reach on GitHub, private ones too, with every branch and tag and, |
| 261 | if you like, their issues. See [GitHub](/guides/github/). |
| 262 | 3. Give it a name and say who can see it, then choose **Create project**. |
| 263 | |
| 264 | Pushing a repository that does not exist yet makes one, and with it a |
| 265 | project: |
| 266 | |
| 267 | ```sh |
| 268 | git push https://g1t.sh/acme/my-app.git main |
| 269 | ``` |
| 270 | |
| 271 | ## Sources |
| 272 | |
| 273 | A project's source is a repository hosted on g1t. A repository can be a |
| 274 | **mirror of one on GitHub**: the code stays there, every push to GitHub is |
| 275 | fetched into g1t, and the project gets g1t's deployments, secrets and |
| 276 | agents on it. See [GitHub](/guides/github/#import-mirror-or-move-a-repository). |
| 277 | |
| 278 | Coming next: |
| 279 | |
| 280 | - **Mirrored from GitLab or Bitbucket**, and previews on GitHub's own pull |
| 281 | requests. |
| 282 | - **Several projects on one repository**, each from its own root |
| 283 | directory, with a push building only the projects it touched. |
| 284 | |
| 285 | |
| 286 | ## Dependencies |
| 287 | |
| 288 | A project can depend on others in its workspace: `web` calls `api`'s HTTP |
| 289 | API, or consumes `ui-kit`'s package. Declare it under **Settings → |
| 290 | Dependencies**, or in a `.g1t/project.yml` in the project's root |
| 291 | directory: |
| 292 | |
| 293 | ```yaml |
| 294 | dependsOn: |
| 295 | - project: api |
| 296 | as: API_URL |
| 297 | - project: ui-kit |
| 298 | ``` |
| 299 | |
| 300 | The file is read on every push to the default branch, and its dependencies |
| 301 | replace the ones it declared before; those are marked **project.yml** and |
| 302 | changed only in the file. A dependency that would make a cycle, or names a |
| 303 | project that does not exist, is left out. |
| 304 | |
| 305 | What g1t does with them: |
| 306 | |
| 307 | | | | |
| 308 | | --- | --- | |
| 309 | | **Addresses in builds and apps** | With `as: API_URL`, `web`'s builds and its running app get `API_URL` set to `api`'s address for the same environment: production gets `api`'s production; a preview gets the preview of `api` on the same branch if one is up, else `api`'s production. A secret or variable of the same name on `web` wins. | |
| 310 | | **Preview stacks** | On a pull request of `api` whose preview is up, **Preview them against this change** builds a preview of every project that uses `api`, from its default branch, under the same branch name, so each reaches the change through its variable. A reviewer clicks through the whole change. | |
| 311 | | **Affects** | A pull request lists the projects that use its project, so reviewers see what else a change can break. | |
| 312 | | **Agents** | An agent working on a project is told what it uses and what uses it. If its change alters what those rely on, it keeps it working for them or opens an issue on each saying what to change, and says so in its summary. | |
| 313 | | **The overview** | Each project's overview shows what it depends on and what uses it. | |
| 314 | |
| 315 | ## From the API |
| 316 | |
| 317 | Projects keep their repository's routes: `/repos/{workspace}/{project}/…` |
| 318 | reaches the project's repository, and its secrets and variables are the |
| 319 | project's. See the [API reference](/reference/api/). |
| 320 | |
| 321 | What a project is, where it runs and its links have routes of their own, |
| 322 | and actions on the [MCP](/reference/mcp/) `workspace` tool: |
| 323 | |
| 324 | | Route | MCP action | | |
| 325 | | --- | --- | --- | |
| 326 | | `GET /workspaces/{workspace}/projects` | `list_projects` | The workspace's projects you can see. | |
| 327 | | `GET /workspaces/{workspace}/projects/{project}` | `get_project` | One project, with `kind`, `runs`, `production_url`, `setting`, `detected` and `links`. | |
| 328 | | `PATCH /workspaces/{workspace}/projects/{project}` | `update_project` | Changes `kind`, `runs`, `production_url`, `homepage`, `docs_url`, `links`, or its name, description or root directory. Needs `repo:write`. | |
| 329 | |
| 330 | To say an app is deployed by your own pipeline, with its docs: |
| 331 | |
| 332 | ```sh |
| 333 | curl -X PATCH https://api.g1t.sh/workspaces/acme/projects/web \ |
| 334 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 335 | -H "Content-Type: application/json" \ |
| 336 | -d '{"runs": "elsewhere", "production_url": "https://acme.dev", "docs_url": "https://docs.acme.dev"}' |
| 337 | ``` |