Skip to content
Sign up

flagon-io/g1t

public
00

Where people and agents ship software together. The open-source git platform for the whole job: issues, agents, checks and deploys to the edge.

gitagentscloudflarerustforgemcp

Commit

A guide to building and shipping an app with an agent (#52)

guides/build-and-ship.mdx walks Claude Code, with g1t's plugin, from an empty folder to a merged pull request: it creates the repository (g1t repo create --source ., or the repository tool's create), pushes, opens an issue and claims it, opens a pull request, watches its checks and merges. You start the g1t plan and turn deployments on once, under the project's Settings → Deployments; after that every pull request gets a preview (the g1t / deploy check) and every merge rebuilds production. It says which CLI command and MCP action the agent uses at each step and the scope each needs, what the agent's merge does under required checks, approvals, an up-to-date rule, a required deployment and the merge queue, that it merges as you (so --admin, ignore_checks and bypass_rules bypass whatever you may), and closes with a table of what the agent can and can't do and a note that Ask only reads. Two catches people would hit are spelled out: the MCP sign-in's Agent preset has no repo:write, so creating a repository goes through the CLI or Change access under Connected applications; and the plugin records nothing in a session that started before the folder had a g1t remote, so it says to resume with claude --continue, or create the repository first and start in the clone. The guide is second under Coding agents in the sidebar and a card on the docs home.

Checked:
create_repo needs repo:write (crates/contracts/src/scopes.rs) and the Agent preset adds only code, issues, pull_requests and notifications writes (Preset::scopes), while CLI device sign-in carries every scope (services/identity/src/device.rs); create_repo is public unless private is true (apps/api/src/operations.rs) and g1t repo create sends private unless --public, pushing HEAD with --source (crates/g1t/src/commands/repo.rs), and the description goes to the project; deployments are turned on only by deployments.updateSettings from the web app's settings-deployments.tsx and deployments.tsx routes (labels Deploy on g1t, Turn on deployments, "Deployments are on. Production is building."), with no DeploymentsOp, project or billing operation that does it, update_project's runs never turning them on (services/projects/src/index.ts), Admin (manage_integrations) and the plan's deployments feature required (services/deployments/src/index.ts); the g1t / deploy check and its Building, Preview is live and Deployment failed states (services/deployments/src/index.ts); merge refusals, auto-merge and the queue message and --admin flags (apps/api/src/operations.rs, crates/g1t/src/commands/pr.rs); workflow files need workflow_files:write; the plugin's SessionStart returns nothing outside a g1t remote (plugins/claude-code/hooks/g1t.mjs) and its work-on-issue skill's steps; Ask's credential reads only and every non-read is refused (services/identity/src/ask_tokens.rs, services/integrations/src/ask_tools.rs). The docs build (544 pages), with every link and anchor the guide uses present in dist.
G1t-Session:
ses_01m4ynr1peevvs8zwaqakycv2e
syntaqxcommitted Parent2e90f6fBrowse files
3 files+231−00/3 viewed
+1−0
156156 label: 'Coding agents',
157157 items: [
158158 { label: 'Connect a coding agent', slug: 'guides/bring-your-own-agent' },
159+ { label: 'Build and ship an app with an agent', slug: 'guides/build-and-ship' },
159160 { label: 'Claude Code plugin', slug: 'guides/claude-code-plugin' },
160161 { label: 'Sessions, claims and dependencies', slug: 'guides/sessions' },
161162 { label: 'Sessions and why-blame', slug: 'guides/why-blame' },
+224−0
1+---
2+title: Build and ship an app with an agent
3+description: Have Claude Code, with g1t's plugin, create a repository, push an app, open a pull request and merge it. Turn deployments on once, and every change after that ships through the same loop. What the agent does at each step, the access each needs, and what stays with you.
4+---
5+
6+import { Steps } from '@astrojs/starlight/components';
7+import Aside from '../../../components/Aside.astro';
8+
9+Claude Code, with g1t's [plugin](/guides/claude-code-plugin/), can take an
10+app from an empty folder to a merged pull request on g1t: it creates the
11+repository, pushes the code, opens a pull request, watches its checks and
12+merges it. Two things stay with you, because no agent can do them: putting
13+the workspace on the g1t plan, and turning deployments on for the project.
14+You do both once. From then on, every pull request the agent opens gets a
15+live preview, and every merge goes to production on its own.
16+
17+The examples use the workspace `acme` and the app `my-app`. Put your own
18+names in their place.
19+
20+## Before you start
21+
22+- **Claude Code with g1t's plugin**, and the g1t CLI 0.3.2 or later,
23+ signed in with git set up to use it:
24+
25+ ```sh
26+ g1t auth login --git
27+ ```
28+
29+ [Claude Code plugin](/guides/claude-code-plugin/#install) covers
30+ installing both, and signing in the plugin's MCP server with `/mcp`.
31+- **A workspace you can create repositories in.** Whoever creates a
32+ repository gets the Admin [role](/guides/access-and-roles/) on it, which
33+ turning deployments on needs.
34+- **The g1t plan**, for deployments. An owner of the workspace starts it;
35+ see step 3 below.
36+
37+### How the agent reaches g1t
38+
39+The agent acts as you, in one of two ways, and they carry different access:
40+
41+| | The g1t CLI | g1t's MCP tools |
42+| --- | --- | --- |
43+| Signed in by | `g1t auth login` | `/mcp`, **plugin:g1t:g1t** |
44+| What it may do | Everything you can: the sign-in carries every scope, bounded by your roles | The [Agent preset](/guides/authentication/#presets), unless you change it: reading across g1t, and writing code, issues, pull requests and notifications |
45+| Creates a repository | Yes | Only once you add `repo:write` |
46+
47+The plugin's skills and hooks use the CLI, so Claude reaches for `g1t`
48+commands first. To let the MCP tools create repositories too, open
49+[Settings → Connected applications](https://g1t.sh/settings/applications),
50+choose **Change access** on Claude Code, tick `repo:write` and choose
51+**Save access**.
52+
53+## Build and ship the first version
54+
55+<Steps>
56+
57+1. **Ask for the app**
58+
59+ Make an empty folder, start Claude Code in it, and ask:
60+
61+ ```text
62+ Build a small static site for my-app in this folder: an index page and
63+ an about page, with a build script. Commit it, then create a private
64+ repository for it on g1t at acme/my-app and push it.
65+ ```
66+
67+ To create the repository and push, the agent runs:
68+
69+ ```sh
70+ g1t repo create acme/my-app --source . --description "Our app's website"
71+ ```
72+
73+ A repository is private unless `--public` is given. `--source .` adds
74+ the new repository as the `origin` remote of this folder and pushes the
75+ current branch to it. The CLI prints `✓ Made acme/my-app` and the
76+ repository's address, `https://g1t.sh/acme/my-app`. The description is
77+ its [project's](/guides/projects/): every repository has a project of
78+ its own name.
79+
80+ Through MCP, the same is the `repository` tool's `create` action with
81+ `workspace`, `name`, `description` and `private: true`. There a
82+ repository is public unless `private` is true. The agent then pushes
83+ with git.
84+
85+ <Aside title="Record the session from here">
86+ The plugin records a session only when it starts in a working copy
87+ whose remote is on g1t, and this folder had none when the session
88+ started. Start Claude Code again with `claude --continue`: the
89+ conversation carries on, and from then on the session is recorded, shows
90+ in **Live now** on the project's **Work** page, and is tied to the
91+ commits and pull requests it makes. To record it all, create the
92+ repository first yourself, `g1t repo create acme/my-app --clone`, and
93+ start Claude Code in the clone.
94+ </Aside>
95+
96+2. **Open and merge a pull request**
97+
98+ The first version is on the default branch. Every change after it goes
99+ through a pull request. Ask:
100+
101+ ```text
102+ Add a contact page to my-app. Open an issue for it, work on a branch,
103+ open a pull request on g1t, wait for its checks, and merge it when they
104+ pass.
105+ ```
106+
107+ The agent works as the plugin's `/g1t:work-on-issue` skill says:
108+
109+ | The agent | With the CLI | With MCP |
110+ | --- | --- | --- |
111+ | Opens an issue and claims it for this session | `g1t work claim --title "Add a contact page"` | `issue` `claim` with a `title` |
112+ | Makes a branch named for the issue, such as `1-contact-page`, and commits with the trailer `G1t-Session: $G1T_SESSION` | `git commit --trailer "G1t-Session: $G1T_SESSION"` | |
113+ | Opens a draft pull request early | `g1t pr create --issue 1 --draft --fill` | `pull_request` `create` |
114+ | Watches the checks | `g1t pr checks --watch --fail-fast` | `pull_request` `get` |
115+ | Marks it ready, with what changed and why | `g1t pr ready --summary "…"` | `pull_request` `ready` |
116+ | Merges it | `g1t pr merge` | `pull_request` `merge` |
117+
118+ `g1t work claim` prints `Opened #1 Add a contact page.` and
119+ `Claimed #1.`; `g1t pr merge` prints `Merged acme/my-app#2`. Merging
120+ into the default branch closes the issue. The trailer ties each commit,
121+ and the pull request it lands in, to the session; the pull request's
122+ **Session** tab shows how it was made. See
123+ [Sessions, claims and dependencies](/guides/sessions/).
124+
125+ With no workflows in `.g1t/workflows` there are no checks to wait for.
126+ To have the agent add CI, ask for it; pushing a workflow file needs the
127+ `workflow_files:write` scope, which the CLI's sign-in has. See
128+ [GitHub Actions](/guides/actions/).
129+
130+3. **Turn on deployments**
131+
132+ This is yours to do, once. No API route or MCP tool turns deployments
133+ on, and none starts a plan.
134+
135+ 1. If the workspace is not on the g1t plan, an owner opens
136+ **Settings → Billing and plans**, `g1t.sh/acme/-/billing`, and
137+ chooses **Start the g1t plan**.
138+ 2. Open the project, `g1t.sh/acme/my-app`. Its overview asks **Where
139+ does my-app run?**: choose **Deploy on g1t**. (An overview that says
140+ **Deployments are off** has **Turn on deployments** instead.) Both
141+ open the project's **Settings → Deployments**,
142+ `g1t.sh/acme/my-app/settings/deployments`.
143+ 3. Choose **Turn on deployments**. You need the Admin role on the
144+ repository.
145+
146+ The page says **Deployments are on. Production is building.**
147+ Production builds from the default branch and goes up at
148+ `https://my-app-acme.g1t.page`. [Deployments](/guides/deployments/#what-deploys)
149+ says what g1t builds a project as, and what it costs.
150+
151+</Steps>
152+
153+## Every change after that
154+
155+Ask for the next change the same way. Now each pull request also gets a
156+preview:
157+
158+1. The agent opens the pull request and pushes. A preview builds, at an
159+ address that follows the branch, such as
160+ `https://my-app-git-2-pricing-page-acme.g1t.page`.
161+2. The pull request shows it as the check **g1t / deploy**: **Building**,
162+ then **Preview is live** with a link to the preview, or
163+ **Deployment failed** with a link to the build's log. The agent sees it
164+ among the checks it watches, reads why a build failed, and pushes a fix.
165+3. You open the preview and read the pull request's **Changes** and
166+ **Session**.
167+4. The merge lands on the default branch, and production builds again on
168+ its own. The overview shows the new commit as **Live** once it is up.
169+
170+The agent can follow what it shipped: `g1t deploy list --env production`
171+(or the `workflow` tool's `list_deployments`) lists production's
172+deployments, and `g1t logs` (or the `observability` tool) reads what the
173+app logged and the errors it threw in production. See
174+[Observability](/guides/observability/).
175+
176+### When the repository has rules
177+
178+Required checks, approvals and the merge queue hold for the agent's pull
179+requests exactly as for yours. An admin sets them under the repository's
180+**Settings → Rules**; see [Rules](/guides/rules/).
181+
182+| The repository has | What the agent's merge does |
183+| --- | --- |
184+| A draft pull request | Refused until it is marked ready: `g1t pr ready`. |
185+| [Required checks](/guides/checks/#required-checks) | Refused while one is failing or has not reported yet; the refusal names the first rule not met. `g1t pr merge --auto` (`pull_request` `enable_auto_merge`) has it merge on its own, as you, once they pass. |
186+| Required approvals | Waits for someone else to approve. The agent works as you, and nobody approves their own pull request. |
187+| A rule that it be up to date | Refused when the default branch has moved: `g1t pr update-branch`, then merge again. |
188+| A required deployment | Waits for the pull request's head to deploy, such as its preview. |
189+| The [merge queue](/guides/merge-queue/) | Adds it to the queue, which tests it with the pull requests ahead of it and lands it. The CLI says `acme/my-app#2 lands once it is brought up to date or through the merge queue`. If the queue takes it out, the agent is [told why](/guides/merge-queue/#who-is-told), and the plugin's `/g1t:fix-integration` skill fixes and queues it again. |
190+
191+The agent merges as you, so whatever you may bypass, it may too:
192+`g1t pr merge --admin` (`ignore_checks` and `bypass_rules` on
193+`pull_request` `merge`) merges past required checks and rules where you
194+have the Admin role and a rule lets you. To keep that, or merging at all,
195+to yourself, say so in the repository's `CLAUDE.md`, and leave
196+`g1t pr merge` to ask in Claude Code's permissions.
197+
198+## What the agent can and can't do
199+
200+| | The agent | How | Needs |
201+| --- | --- | --- | --- |
202+| Create a repository | Yes | `g1t repo create`, or `repository` `create` | `repo:write`, which the Agent preset leaves out |
203+| Push code | Yes | git, with the CLI's credentials (`g1t auth setup-git`) or an [access token](/guides/authentication/#access-tokens) | `code:write`; a workflow file also needs `workflow_files:write` |
204+| Open and claim an issue | Yes | `g1t work claim`, or `issue` `claim` | `issues:write` |
205+| Open a pull request and mark it ready | Yes | `g1t pr create` and `g1t pr ready`, or `pull_request` `create` and `ready` | `pull_requests:write` |
206+| Watch checks and the preview | Yes | `g1t pr checks --watch`, or `pull_request` `get` | `pull_requests:read` |
207+| Merge | Yes, within the repository's rules | `g1t pr merge`, or `pull_request` `merge` | `pull_requests:write`, and the Write role |
208+| Approve its own pull request | No | Someone else approves | |
209+| Read deployments, logs and errors | Yes | `g1t deploy list` and `g1t logs`, or `workflow` `list_deployments` and `observability` | `deployments:read`, `observability:read` |
210+| Start the g1t plan | No | An owner, under **Settings → Billing and plans** | |
211+| Turn deployments on or off, or change their settings | No | You, under the project's **Settings → Deployments**, with the Admin role | |
212+| Build production again | No | **Redeploy** on the project's overview, with the Write role, or a push to the default branch | |
213+
214+Scopes are explained under [scopes](/guides/authentication/#scopes);
215+[MCP tools](/reference/mcp/) and the [CLI reference](/reference/cli/) list
216+every action and command.
217+
218+## Ask g1t only reads
219+
220+[Ask](/guides/ask/), and `@g1t` in Chat, reads g1t as you with read-only
221+access: it cannot create a repository, push, merge or deploy. Asked to do
222+work, it proposes a session in your own harness instead, with **Start
223+session** or **Copy Claude Code command**; see
224+[Asking for work](/guides/ask/#asking-for-work).
+6−0
5252 href="/guides/bring-your-own-agent/"
5353 />
5454 <LinkCard
55+ title="Build and ship an app with an agent"
56+ icon="rocket"
57+ description="Your agent creates the repository, pushes the app and merges its pull requests. You turn deployments on once, and every merge ships."
58+ href="/guides/build-and-ship/"
59+ />
60+ <LinkCard
5561 title="Bring a repository"
5662 icon="git-branch"
5763 description="Push any git repository, or import one from another host, and your workflows run here."

Comments

Sign in to comment.