Projects

A project is the thing you are building and running: a site, an API, a worker, a library. Every project has one source, where its code lives, and everything about running it belongs to the project:

Belongs to the project	Belongs to its repository
Deployments: production and previews	Branches and commits
Its address on g1t.page	Issues and pull requests
Secrets and variables	Review, merge rules and the merge queue
Its name, description and root directory	Webhooks

That split is what lets the code live anywhere while the project stays the same.

Your projects

Every repository on g1t is a project of its own name, with nothing to set up: g1t.sh/acme/web is the web project, built from the acme/web repository. Repositories made before projects existed became projects the first time their workspace was opened.

A workspace’s page, g1t.sh/<workspace>, shows its projects first, each with where it is deployed, its latest build, and its open issues and pull requests. The sidebar lists them too.

A project’s pages

Page	Address
Overview	g1t.sh/<workspace>/<project>	Production with a screenshot, the steps left to get to production, what is in progress, active branches, live previews, recent builds, and the source. See the overview.
Code	…/code	The repository’s files, commits and branches.
Issues, Pull requests, Merge queue, Plan	…/issues and so on	As they always were.
Actions	…/actions	GitHub Actions workflows.
Deployments	…/deployments	What is up now and every build.
Settings	…/settings	See below.

Every address that pointed into a repository before still works: the project has the repository’s name.

The overview

A project’s overview is the first page you see. People with a role on its repository see all of it; anyone else sees what the project shares publicly.

Part	What it shows
Production	A screenshot of the live site, which opens it; its address, the commit it runs and when it went up; Visit and Redeploy. See the production screenshot.
Get to production	The checklist below, until every step is done or you dismiss it.
Right now	Agents at work, and open pull requests moving from working to landed.
Needs you	What is waiting on a person: a failed production build, a pull request to merge or review, a stuck run.
Active branches	Branches other than the default, newest first. See active branches.
Recent changes, Activity, Previews	What landed, everything that happened, and the previews that are up.
Health, Dependencies, Clone	How often checks pass, recent builds and open issues by age; what it uses and what uses it; the clone address.

Get to production

People with a role on its repository see a card that counts what the project has done towards production, such as 3/6. Each step is worked out from the project itself, and each links to where you do it:

Step	Done when	Links to
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.
Deploy to production	A production build has gone live.	Deployments settings, or Deployments once they are on.
Add a custom domain	The project has a custom domain.	Domain settings.
Open a preview	A branch or pull request has had a preview.	A new pull request.
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.
Assign a first issue to g1t-agent	g1t-agent has had a run, a pull request or an issue here.	A new issue.

The card goes away when every step is done. To hide it sooner, choose × on it. That hides it for this project in this browser only.

Active branches

Up to five branches other than the default, the most recently changed first. Each shows its last commit and who made it, how many commits it is ahead of the default branch and behind it, and its open pull request, with its checks, and preview, if it has them. A branch with no pull request links to opening one.

Ahead and behind are counted from the last 40 commits of the branch and the last 120 of the default branch. A count that runs past that shows as 40+. Ten branches are read, those with open pull requests first; a project with more says how many it has.

Settings

A project’s Settings has a tab for each part:

Tab	What it holds
General	The project’s name and description, its source, and its root directory.
Deployments	Production, previews, build command, output directory and idle days. See Deployments.
Dependencies	The projects this one uses, and the ones that use it. See Dependencies.
Secrets and variables	The project’s rows. See Secrets and variables.
Repository	The repository’s name, description, website, topics and default branch, and its danger zone: visibility, archive, transfer and delete. See Managing a repository.
Branches and merging	Branch protection, required approvals, checks, the merge queue, auto-merge and how g1t’s agents review.
Webhooks	The repository’s webhooks.

The root directory says where in the repository the project lives, such as apps/web. Builds run there. Leave it empty for the whole repository.

Each tab needs a role on the project’s repository:

Tab	Needs
General, Dependencies, and on Repository its description, website and topics	Maintain
Branches and merging, Guardrails	Maintain
Deployments, Domains, Secrets and variables, Webhooks	Admin
On Repository: its name, default branch, and the danger zone (visibility, archive)	Admin
Transfer and delete	An owner of the workspace

Someone without the role does not see the tab.

Create a project

1. Choose New project in the sidebar, or go to g1t.sh/new.
2. Choose where its code comes from:
   • Start empty: a new repository on g1t.
   • Import code: copy a public repository from GitHub or any git host into a new one on g1t.
   • Import from GitHub: import, mirror or move repositories you can reach on GitHub, private ones too, with every branch and tag and, if you like, their issues. See GitHub.
3. Give it a name and say who can see it, then choose Create project.

Pushing a repository that does not exist yet makes one, and with it a project:

git push https://g1t.sh/acme/my-app.git main

Sources

A project’s source is a repository hosted on g1t. A repository can be a mirror of one on GitHub: the code stays there, every push to GitHub is fetched into g1t, and the project gets g1t’s deployments, secrets and agents on it. See GitHub.

Coming next:

• Mirrored from GitLab or Bitbucket, and previews on GitHub’s own pull requests.
• Several projects on one repository, each from its own root directory, with a push building only the projects it touched.

Dependencies

A project can depend on others in its workspace: web calls api’s HTTP API, or consumes ui-kit’s package. Declare it under Settings → Dependencies, or in a .g1t/project.yml in the project’s root directory:

dependsOn:
  - project: api
    as: API_URL
  - project: ui-kit

The file is read on every push to the default branch, and its dependencies replace the ones it declared before; those are marked project.yml and changed only in the file. A dependency that would make a cycle, or names a project that does not exist, is left out.

What g1t does with them:

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.
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.
Affects	A pull request lists the projects that use its project, so reviewers see what else a change can break.
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.
The overview	Each project’s overview shows what it depends on and what uses it.

From the API

Projects keep their repository’s routes: /repos/{workspace}/{project}/… reaches the project’s repository, and its secrets and variables are the project’s. See the API reference.