g1t/apps/docs/src/content/docs/guides/projects.md
| 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 its projects first, each |
| 28 | with where it is deployed, its latest build, and its open issues and pull |
| 29 | requests. The sidebar lists them too. |
| 30 | |
| 31 | ## A project's pages |
| 32 | |
| 33 | | Page | Address | | |
| 34 | | --- | --- | --- | |
| 35 | | **Overview** | `g1t.sh/<workspace>/<project>` | Production and its address, live previews, what is in progress, recent builds, and the source. | |
| 36 | | **Code** | `…/code` | The repository's files, commits and branches. | |
| 37 | | **Issues**, **Pull requests**, **Merge queue**, **Plan** | `…/issues` and so on | As they always were. | |
| 38 | | **Actions** | `…/actions` | [GitHub Actions workflows](/guides/actions/). | |
| 39 | | **Deployments** | `…/deployments` | What is up now and every build. | |
| 40 | | **Settings** | `…/settings` | See below. | |
| 41 | |
| 42 | Every address that pointed into a repository before still works: the |
| 43 | project has the repository's name. |
| 44 | |
| 45 | ## Settings |
| 46 | |
| 47 | A project's **Settings** has a tab for each part: |
| 48 | |
| 49 | | Tab | What it holds | |
| 50 | | --- | --- | |
| 51 | | **General** | The project's name and description, its source, and its **root directory**. | |
| 52 | | **Deployments** | Production, previews, build command, output directory and idle days. See [Deployments](/guides/deployments/#settings). | |
| 53 | | **Dependencies** | The projects this one uses, and the ones that use it. See [Dependencies](#dependencies). | |
| 54 | | **Secrets and variables** | The project's rows. See [Secrets and variables](/guides/secrets-and-variables/). | |
| 55 | | **Repository** | The repository's visibility, branch protection, required approvals, checks, the merge queue and auto-merge. | |
| 56 | | **Webhooks** | The repository's [webhooks](/guides/webhooks/). | |
| 57 | |
| 58 | The **root directory** says where in the repository the project lives, |
| 59 | such as `apps/web`. Builds run there. Leave it empty for the whole |
| 60 | repository. |
| 61 | |
| 62 | ## Create a project |
| 63 | |
| 64 | 1. Choose **New project** in the sidebar, or go to `g1t.sh/new`. |
| 65 | 2. Choose where its code comes from: |
| 66 | - **Start empty**: a new repository on g1t. |
| 67 | - **Import code**: copy a public repository from GitHub or any git host |
| 68 | into a new one on g1t. |
| 69 | 3. Give it a name and say who can see it, then choose **Create project**. |
| 70 | |
| 71 | Pushing a repository that does not exist yet makes one, and with it a |
| 72 | project: |
| 73 | |
| 74 | ```sh |
| 75 | git push https://g1t.sh/acme/my-app.git main |
| 76 | ``` |
| 77 | |
| 78 | ## Sources |
| 79 | |
| 80 | Today a project's source is a repository hosted on g1t. Coming next: |
| 81 | |
| 82 | - **Mirrored from GitHub, GitLab or Bitbucket.** The code stays there; the |
| 83 | project gets g1t's deployments, previews on its pull requests, secrets |
| 84 | and agents. |
| 85 | - **Several projects on one repository**, each from its own root |
| 86 | directory, with a push building only the projects it touched. |
| 87 | |
| 88 | |
| 89 | ## Dependencies |
| 90 | |
| 91 | A project can depend on others in its workspace: `web` calls `api`'s HTTP |
| 92 | API, or consumes `ui-kit`'s package. Declare it under **Settings → |
| 93 | Dependencies**, or in a `.g1t/project.yml` in the project's root |
| 94 | directory: |
| 95 | |
| 96 | ```yaml |
| 97 | dependsOn: |
| 98 | - project: api |
| 99 | as: API_URL |
| 100 | - project: ui-kit |
| 101 | ``` |
| 102 | |
| 103 | The file is read on every push to the default branch, and its dependencies |
| 104 | replace the ones it declared before; those are marked **project.yml** and |
| 105 | changed only in the file. A dependency that would make a cycle, or names a |
| 106 | project that does not exist, is left out. |
| 107 | |
| 108 | What g1t does with them: |
| 109 | |
| 110 | | | | |
| 111 | | --- | --- | |
| 112 | | **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. | |
| 113 | | **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. | |
| 114 | | **Affects** | A pull request lists the projects that use its project, so reviewers see what else a change can break. | |
| 115 | | **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. | |
| 116 | | **The overview** | Each project's overview shows what it depends on and what uses it. | |
| 117 | |
| 118 | ## From the API |
| 119 | |
| 120 | Projects keep their repository's routes: `/repos/{workspace}/{project}/…` |
| 121 | reaches the project's repository, and its secrets and variables are the |
| 122 | project's. See the [API reference](/reference/api/). |