| 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; 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** | `…/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. It says what the project |
| 51 | is, whether it is running and healthy, and who is working on it right now. |
| 52 | Its files, branches and commits are on **Code**; its pull requests and the |
| 53 | merge queue on **Pull requests** and **Work**. The overview links to them |
| 54 | rather than repeating them. |
| 55 | |
| 56 | People with a [role](/guides/access-and-roles/) on its repository see all |
| 57 | of it; anyone else sees what the project shares publicly: production, its |
| 58 | checks, who is working on it, its deployments and About. |
| 59 | |
| 60 | | Part | What it shows | |
| 61 | | --- | --- | |
| 62 | | **What it is** | A badge, such as **App, deploys itself** 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. | |
| 63 | | **Production** | [Production's picture](#productions-picture), which opens the live site, beside the rest. For an app [hosted on g1t.page](/guides/deployments/): its address, the commit it runs and when it went up; **Visit** and **Redeploy**. For an app that deploys itself: production's address and **Visit**, with its latest reported production deployment (and the workflow run that made it, when g1t Actions did) or the default branch's latest commit. For an app nobody has placed yet: one question, where it runs. | |
| 64 | | **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. | |
| 65 | | **Documentation**, **Homepage** | For docs, where they are read; for anything else, its homepage. | |
| 66 | | **Facts** | Under production: its latest release (or, where the card does not already say it, production's state), how often checks pass, and either how many changes pass on the first try and what is open, or, for people with a role when [Observability](/guides/observability/) has data, requests and the error rate over the last day with how many errors are open. | |
| 67 | | **Code** | One line to the repository: its name, default branch and when it was last pushed to, linking to **Code**. | |
| 68 | | **Needs you** | For someone signed in: what is waiting on them, such as a failed production build or a pull request to merge or review. | |
| 69 | | **Live now** | The people and coding agents working on it: each issue with its [claims and sessions](/guides/sessions/), the harness each came from and who it acts for, and sessions on no issue yet. **Work** has everything. With nobody working, people with a role see how to [connect a coding agent](/guides/bring-your-own-agent/). | |
| 70 | | **Previews** | For people with a role: the pull requests' previews that are up. | |
| 71 | | **Deployments** | Each environment's latest deployment and when. | |
| 72 | | **Observability** | For people with a role, when there is data: the last day's requests, an hour a bar, latency, and the newest open errors. | |
| 73 | | **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. | |
| 74 | | **Health** | For people with a role, its recent builds; and its open issues by age. | |
| 75 | |
| 76 | ### Production's picture |
| 77 | |
| 78 | The production card always has a picture of the app, wherever it runs. |
| 79 | It is the first of these there is: |
| 80 | |
| 81 | 1. **A screenshot of production.** For an app hosted on g1t.page, g1t takes |
| 82 | one each time production goes live (see |
| 83 | [the production screenshot](/guides/deployments/#the-production-screenshot)); |
| 84 | people with a role on the repository see it, like the rest of its |
| 85 | deployments. For an app that deploys itself, g1t takes one of |
| 86 | production's address: the address its latest production deployment |
| 87 | reported to g1t gives, or else the one set for it under **What it is**. |
| 88 | Anyone who can see the project sees it. |
| 89 | 2. **An image someone uploaded**, under **Settings** → **General** → |
| 90 | **Production image**. |
| 91 | 3. **A plain frame** with production's address. People who can change |
| 92 | the project's settings see **Add an image of your app** on it, which |
| 93 | opens **Production image**. |
| 94 | |
| 95 | A screenshot of an app that deploys itself is taken: |
| 96 | |
| 97 | - when its address is set or changed; |
| 98 | - when a production deployment of it is reported to g1t and succeeds, |
| 99 | through the [API](/guides/deployments/) or by a workflow job with an |
| 100 | `environment:`; |
| 101 | - otherwise about once a day, when the one kept is a day old. Opening the |
| 102 | overview after that also takes a new one, in the background, while the |
| 103 | old one shows. |
| 104 | |
| 105 | g1t waits up to 12 seconds for the page to settle, as a 1280 by 800 |
| 106 | browser window sees it, then takes it as it is. Only public `http` and |
| 107 | `https` addresses on their usual ports are visited: an address on a |
| 108 | private network, a loopback or link-local address, or one of g1t's own |
| 109 | service addresses (other than `g1t.sh` itself) gets the uploaded image |
| 110 | or the frame instead. Screenshots are not charged. |
| 111 | |
| 112 | #### Uploading an image |
| 113 | |
| 114 | **Production image** takes a PNG, JPEG or WebP of at most 5 MB; wide |
| 115 | images fit best, such as 1280 by 800. It is checked by its contents, not |
| 116 | its name, and served from g1t's user-content address |
| 117 | (`g1tusercontent.com` on g1t.sh), never from the site itself. Its address |
| 118 | is made from its contents, so the card shows a new image as soon as it |
| 119 | is uploaded. Anyone with an image's address can open it, even for a |
| 120 | private project, so upload only what you would show. |
| 121 | |
| 122 | - The uploaded image shows whenever there is no screenshot: before the |
| 123 | first one, when one cannot be taken, or for an app with no production |
| 124 | address. |
| 125 | - **Use the uploaded image instead of a screenshot** shows it in place of |
| 126 | any screenshot. While it is on, g1t takes no screenshots of an app |
| 127 | that deploys itself. |
| 128 | - **Remove** takes it away; the card goes back to the screenshot or the |
| 129 | frame. |
| 130 | |
| 131 | Anyone who can change the project's settings (the **Maintain** role on |
| 132 | its repository and up, as for production's address) can upload, replace |
| 133 | or remove it. |
| 134 | |
| 135 | ## What a project is |
| 136 | |
| 137 | A project is one of these, and its overview follows: |
| 138 | |
| 139 | | What it is | Its overview shows | |
| 140 | | --- | --- | |
| 141 | | **App or site, hosted on g1t.page** | g1t builds and hosts it: production on g1t.page, with previews and domains. | |
| 142 | | **App or site that deploys itself** | Its own [workflows](/guides/deployments/#deploying-from-a-workflow) on g1t Actions, or another pipeline, deploy it to hosting of its own. Production at the address its deployments report or you give, with **Visit**. It is never asked to turn on Deployments; Deployment settings stay one link away. | |
| 143 | | **Library or package** | The packages its repository publishes and how to install them. | |
| 144 | | **Tool or CLI** | The same as a library: its packages and releases. | |
| 145 | | **Documentation** | Where its docs are read. Docs can be published on g1t.page too, by turning on Deployments. | |
| 146 | | **Something else** | Its homepage and links. | |
| 147 | |
| 148 | Its **Deployments** page stays in the sidebar whatever it is. |
| 149 | |
| 150 | ### How g1t works it out |
| 151 | |
| 152 | Until you say, g1t works it out for itself, in this order: |
| 153 | |
| 154 | 1. If [Deployments](/guides/deployments/) are on for the project, it is |
| 155 | an app hosted on g1t.page. |
| 156 | 2. If its repository publishes a package other than a container image, |
| 157 | such as a [Composer](/guides/composer/) or [npm](/guides/npm/) |
| 158 | package, it is a library. |
| 159 | 3. If the files at the root of its default branch (or of its root |
| 160 | directory) say what it is, it is that: |
| 161 | |
| 162 | | File | Says | |
| 163 | | --- | --- | |
| 164 | | `wrangler.jsonc`, `wrangler.json` or `wrangler.toml` | An app. | |
| 165 | | `mkdocs.yml`, `book.toml`, `docusaurus.config.js` (or `.ts`, `.mjs`) or `antora.yml` | Documentation. | |
| 166 | | `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`. | |
| 167 | | `Cargo.toml` | A library when it builds a library (`[lib]` or `src/lib.rs`) and no binary (`[[bin]]` or `src/main.rs`). | |
| 168 | | `go.mod` | A library when no `.go` file at the root is `package main`. | |
| 169 | | `pyproject.toml` | A library when it has a build backend and depends on no app framework, such as Django, Flask or FastAPI. | |
| 170 | | `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. | |
| 171 | |
| 172 | The language's own manifest is read before `package.json`, which many |
| 173 | projects carry only for tooling. An `index.html` at the root makes it |
| 174 | an app. |
| 175 | 4. Anything else is an app. |
| 176 | |
| 177 | The files are read again on every push to the default branch. |
| 178 | |
| 179 | An app found this way runs on g1t only while Deployments are on. Until |
| 180 | you say where it runs, its overview asks, in place of production: |
| 181 | **Deploy on g1t**, **It deploys itself** (with production's |
| 182 | address), or **It isn't deployed** (a library, a tool, documentation or |
| 183 | something else). |
| 184 | |
| 185 | ### Choosing it yourself |
| 186 | |
| 187 | From the overview, open the badge beside its name, such as **App**, and |
| 188 | choose one. Or open **Settings**, then **General**, and under **What it |
| 189 | is** choose **Detect automatically**, which shows what was detected and |
| 190 | why, or one of the kinds above. **App or site that deploys itself** asks |
| 191 | for production's address. |
| 192 | |
| 193 | Choosing a library, a tool or something else while Deployments are on is |
| 194 | refused: turn them off first under **Settings**, then **Deployments**; |
| 195 | g1t does not turn them off for you. While it is set that way, Deployments |
| 196 | cannot be turned on. Turning Deployments on for an app that deploys itself |
| 197 | makes it an app hosted on g1t.page. |
| 198 | |
| 199 | Changing what it is needs the role that changes the project's settings. |
| 200 | |
| 201 | ## Links |
| 202 | |
| 203 | A project has a **homepage**, a **docs** address, and up to 10 other |
| 204 | links, each a label and an address, such as a status page or its listing |
| 205 | in a registry. They show in its overview's About and beside what it is, |
| 206 | on its card on its workspace's page, in its workspace's Projects, and on |
| 207 | Explore for a public project. |
| 208 | |
| 209 | To set them, open **Settings**, then **General**, and fill in **Links**; |
| 210 | or choose the pencil on the overview's **About**. Each is an http or |
| 211 | https address; `https://` is added when you leave it out. A label left |
| 212 | empty is the address's host name. Removing every row of other links |
| 213 | clears them. |
| 214 | |
| 215 | A repository's own project shows the repository's website as its |
| 216 | homepage until you give the project one of its own. For an app deployed |
| 217 | on g1t, its g1t.page address still shows as production; set the homepage |
| 218 | to production's own domain if you have one. |
| 219 | |
| 220 | ## Settings |
| 221 | |
| 222 | A project's **Settings** has a tab for each part: |
| 223 | |
| 224 | | Tab | What it holds | |
| 225 | | --- | --- | |
| 226 | | **General** | The project's name and description, its source, its **root directory**, [what it is](#what-a-project-is), its [links](#links), and its [production image](#uploading-an-image). Only projects have descriptions: a repository has none of its own, and search, link previews and lists of repositories show its project's. A fork's project starts with the description of the project it was forked from. | |
| 227 | | **Deployments** | Production, previews, build command, output directory and idle days. See [Deployments](/guides/deployments/#settings). | |
| 228 | | **Domains** | Custom domains for production. See [custom domains](/guides/deployments/#custom-domains). | |
| 229 | | **Guardrails** | How long g1t's checks, merge queue and merge checks may run here. See [guardrails](/guides/guardrails/). | |
| 230 | | **Repository** | The repository's name, 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/). | |
| 231 | | **Access** | Who has a [role](/guides/access-and-roles/) on the repository, and invitations. | |
| 232 | | **Branches and merging** | Auto-merge, the CODEOWNERS file's errors, and what the rules hold for the default branch. | |
| 233 | | **Rules** | [Rulesets](/guides/rules/): branch and tag protection, [required status checks](/guides/pull-requests/#required-status-checks), approvals and the merge queue, with Insights. | |
| 234 | | **Secrets and variables** | The project's rows. See [Secrets and variables](/guides/secrets-and-variables/). | |
| 235 | | **Runners** | The project's own [self-hosted runners](/guides/self-hosted-runners/). | |
| 236 | | **Webhooks** | The repository's [webhooks](/guides/webhooks/). | |
| 237 | |
| 238 | The **root directory** says where in the repository the project lives, |
| 239 | such as `apps/web`. Builds run there. Leave it empty for the whole |
| 240 | repository. |
| 241 | |
| 242 | Each tab needs a [role](/guides/access-and-roles/) on the project's |
| 243 | repository: |
| 244 | |
| 245 | | Tab | Needs | |
| 246 | | --- | --- | |
| 247 | | **General**, **Dependencies**, **Branches and merging**, and on **Repository** its website and topics | Maintain | |
| 248 | | **Rules**, **Guardrails** | Admin | |
| 249 | | **Access**: seeing who has a role; changing it | Write; Admin | |
| 250 | | **Deployments**, **Domains**, **Secrets and variables**, **Runners**, **Webhooks** | Admin | |
| 251 | | On **Repository**: its name, default branch, and the danger zone (visibility, archive) | Admin | |
| 252 | | Transfer and delete | An owner of the workspace | |
| 253 | |
| 254 | Someone without the role does not see the tab. |
| 255 | |
| 256 | ## Create a project |
| 257 | |
| 258 | 1. In the workspace the project belongs to, choose **New project** in the |
| 259 | sidebar, or go to `g1t.sh/new`. It's made in the workspace you're in; to |
| 260 | make one somewhere else, switch workspaces first. |
| 261 | 2. Choose where its code comes from: |
| 262 | - **Start empty**: a new repository on g1t. |
| 263 | - **Import code**: copy a public repository from GitHub or any git host |
| 264 | into a new one on g1t, with every branch and tag (up to 40 MB of |
| 265 | history). |
| 266 | - **Import from GitHub**: import repositories you can reach on GitHub, |
| 267 | private ones too, with every branch and tag and, if you like, their |
| 268 | issues. See [GitHub](/guides/github/). |
| 269 | 3. Give it a name and say who can see it, then choose **Create project**. |
| 270 | |
| 271 | Pushing a repository that does not exist yet makes one, and with it a |
| 272 | project: |
| 273 | |
| 274 | ```sh |
| 275 | git push https://g1t.sh/acme/my-app.git main |
| 276 | ``` |
| 277 | |
| 278 | ## Sources |
| 279 | |
| 280 | A project's source is a repository hosted on g1t: one you pushed, or one |
| 281 | imported from GitHub or any git host. See |
| 282 | [GitHub](/guides/github/#import-a-repository). |
| 283 | |
| 284 | Coming next: |
| 285 | |
| 286 | - **Several projects on one repository**, each from its own root |
| 287 | directory, with a push building only the projects it touched. |
| 288 | |
| 289 | ## From the API |
| 290 | |
| 291 | Projects keep their repository's routes: `/repos/{workspace}/{project}/…` |
| 292 | reaches the project's repository, and its secrets and variables are the |
| 293 | project's. See the [API reference](/reference/api/). |
| 294 | |
| 295 | What a project is, where it runs and its links have routes of their own, |
| 296 | and actions on the [MCP](/reference/mcp/) `workspace` tool: |
| 297 | |
| 298 | | Route | MCP action | | |
| 299 | | --- | --- | --- | |
| 300 | | `GET /workspaces/{workspace}/projects` | `list_projects` | The workspace's projects you can see. | |
| 301 | | `GET /workspaces/{workspace}/projects/{project}` | `get_project` | One project, with `kind`, `runs`, `production_url`, `setting`, `detected` and `links`. | |
| 302 | | `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`. | |
| 303 | |
| 304 | Its g1t.page deployment settings, on the `workflow` tool, are at |
| 305 | `GET` and `PATCH /workspaces/{workspace}/projects/{project}/deployments/settings` |
| 306 | (`get_deployment_settings`, `update_deployment_settings`): `enabled: true` |
| 307 | turns its deployments on. See [Turn on deployments](/guides/deployments/#without-the-site). |
| 308 | |
| 309 | To say an app is deployed by your own pipeline, with its docs: |
| 310 | |
| 311 | ```sh |
| 312 | curl -X PATCH https://api.g1t.sh/workspaces/acme/projects/web \ |
| 313 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 314 | -H "Content-Type: application/json" \ |
| 315 | -d '{"runs": "elsewhere", "production_url": "https://acme.dev", "docs_url": "https://docs.acme.dev"}' |
| 316 | ``` |