| 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, creating repositories, and writing code, issues, pull requests and notifications | |
| 45 | | Creates a repository | Yes | Yes, with `repo:create` | |
| 46 | |
| 47 | The plugin's skills and hooks use the CLI, so Claude reaches for `g1t` |
| 48 | commands first. A plugin signed in before the Agent preset gave |
| 49 | `repo:create` keeps the scopes it had: open |
| 50 | [Settings → Connected applications](https://g1t.sh/settings/applications), |
| 51 | choose **Change access** on Claude Code, tick `repo:create` and choose |
| 52 | **Save access**, or sign it in again with `/mcp`. |
| 53 | |
| 54 | ## Build and ship the first version |
| 55 | |
| 56 | <Steps> |
| 57 | |
| 58 | 1. **Ask for the app** |
| 59 | |
| 60 | Make an empty folder, start Claude Code in it, and ask: |
| 61 | |
| 62 | ```text |
| 63 | Build a small static site for my-app in this folder: an index page and |
| 64 | an about page, with a build script. Commit it, then create a private |
| 65 | repository for it on g1t at acme/my-app and push it. |
| 66 | ``` |
| 67 | |
| 68 | To create the repository and push, the agent runs: |
| 69 | |
| 70 | ```sh |
| 71 | g1t repo create acme/my-app --source . --description "Our app's website" |
| 72 | ``` |
| 73 | |
| 74 | A repository is private unless `--public` is given. `--source .` adds |
| 75 | the new repository as the `origin` remote of this folder and pushes the |
| 76 | current branch to it. The CLI prints `✓ Made acme/my-app` and the |
| 77 | repository's address, `https://g1t.sh/acme/my-app`. The description is |
| 78 | its [project's](/guides/projects/): every repository has a project of |
| 79 | its own name. |
| 80 | |
| 81 | Through MCP, the same is the `repository` tool's `create` action with |
| 82 | `workspace`, `name` and `description`. There too a repository is |
| 83 | private unless `private: false` is given. The agent then pushes with |
| 84 | git. |
| 85 | |
| 86 | <Aside title="Record the session from here"> |
| 87 | The plugin records a session only when it starts in a working copy |
| 88 | whose remote is on g1t, and this folder had none when the session |
| 89 | started. Start Claude Code again with `claude --continue`: the |
| 90 | conversation carries on, and from then on the session is recorded, shows |
| 91 | in **Live now** on the project's **Work** page, and is tied to the |
| 92 | commits and pull requests it makes. To record it all, create the |
| 93 | repository first yourself, `g1t repo create acme/my-app --clone`, and |
| 94 | start Claude Code in the clone. |
| 95 | </Aside> |
| 96 | |
| 97 | 2. **Open and merge a pull request** |
| 98 | |
| 99 | The first version is on the default branch. Every change after it goes |
| 100 | through a pull request. Ask: |
| 101 | |
| 102 | ```text |
| 103 | Add a contact page to my-app. Open an issue for it, work on a branch, |
| 104 | open a pull request on g1t, wait for its checks, and merge it when they |
| 105 | pass. |
| 106 | ``` |
| 107 | |
| 108 | The agent works as the plugin's `/g1t:work-on-issue` skill says: |
| 109 | |
| 110 | | The agent | With the CLI | With MCP | |
| 111 | | --- | --- | --- | |
| 112 | | Opens an issue and claims it for this session | `g1t work claim --title "Add a contact page"` | `issue` `claim` with a `title` | |
| 113 | | 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"` | | |
| 114 | | Opens a draft pull request early | `g1t pr create --issue 1 --draft --fill` | `pull_request` `create` | |
| 115 | | Watches the checks | `g1t pr checks --watch --fail-fast` | `pull_request` `get` | |
| 116 | | Marks it ready, with what changed and why | `g1t pr ready --summary "…"` | `pull_request` `ready` | |
| 117 | | Merges it | `g1t pr merge` | `pull_request` `merge` | |
| 118 | |
| 119 | `g1t work claim` prints `Opened #1 Add a contact page.` and |
| 120 | `Claimed #1.`; `g1t pr merge` prints `Merged acme/my-app#2`. Merging |
| 121 | into the default branch closes the issue. The trailer ties each commit, |
| 122 | and the pull request it lands in, to the session; the pull request's |
| 123 | **Session** tab shows how it was made. See |
| 124 | [Sessions, claims and dependencies](/guides/sessions/). |
| 125 | |
| 126 | With no workflows in `.g1t/workflows` there are no checks to wait for. |
| 127 | To have the agent add CI, ask for it; pushing a workflow file needs the |
| 128 | `workflow_files:write` scope, which the CLI's sign-in has. See |
| 129 | [GitHub Actions](/guides/actions/). |
| 130 | |
| 131 | 3. **Turn on deployments** |
| 132 | |
| 133 | This is yours to do, once. No API route or MCP tool turns deployments |
| 134 | on, and none starts a plan. |
| 135 | |
| 136 | 1. If the workspace is not on the g1t plan, an owner opens |
| 137 | **Settings → Billing and plans**, `g1t.sh/acme/-/billing`, and |
| 138 | chooses **Start the g1t plan**. |
| 139 | 2. Open the project, `g1t.sh/acme/my-app`. Its overview asks **Where |
| 140 | does my-app run?**: choose **Deploy on g1t**. (An overview that says |
| 141 | **Deployments are off** has **Turn on deployments** instead.) Both |
| 142 | open the project's **Settings → Deployments**, |
| 143 | `g1t.sh/acme/my-app/settings/deployments`. |
| 144 | 3. Choose **Turn on deployments**. You need the Admin role on the |
| 145 | repository. |
| 146 | |
| 147 | The page says **Deployments are on. Production is building.** |
| 148 | Production builds from the default branch and goes up at |
| 149 | `https://my-app-acme.g1t.page`. [Deployments](/guides/deployments/#what-deploys) |
| 150 | says what g1t builds a project as, and what it costs. |
| 151 | |
| 152 | </Steps> |
| 153 | |
| 154 | ## Every change after that |
| 155 | |
| 156 | Ask for the next change the same way. Now each pull request also gets a |
| 157 | preview: |
| 158 | |
| 159 | 1. The agent opens the pull request and pushes. A preview builds, at an |
| 160 | address that follows the branch, such as |
| 161 | `https://my-app-git-2-pricing-page-acme.g1t.page`. |
| 162 | 2. The pull request shows it as the check **g1t / deploy**: **Building**, |
| 163 | then **Preview is live** with a link to the preview, or |
| 164 | **Deployment failed** with a link to the build's log. The agent sees it |
| 165 | among the checks it watches, reads why a build failed, and pushes a fix. |
| 166 | 3. You open the preview and read the pull request's **Changes** and |
| 167 | **Session**. |
| 168 | 4. The merge lands on the default branch, and production builds again on |
| 169 | its own. The overview shows the new commit as **Live** once it is up. |
| 170 | |
| 171 | The agent can follow what it shipped: `g1t deploy list --env production` |
| 172 | (or the `workflow` tool's `list_deployments`) lists production's |
| 173 | deployments, and `g1t logs` (or the `observability` tool) reads what the |
| 174 | app logged and the errors it threw in production. See |
| 175 | [Observability](/guides/observability/). |
| 176 | |
| 177 | ### When the repository has rules |
| 178 | |
| 179 | Required checks, approvals and the merge queue hold for the agent's pull |
| 180 | requests exactly as for yours. An admin sets them under the repository's |
| 181 | **Settings → Rules**; see [Rules](/guides/rules/). |
| 182 | |
| 183 | | The repository has | What the agent's merge does | |
| 184 | | --- | --- | |
| 185 | | A draft pull request | Refused until it is marked ready: `g1t pr ready`. | |
| 186 | | [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. | |
| 187 | | Required approvals | Waits for someone else to approve. The agent works as you, and nobody approves their own pull request. | |
| 188 | | A rule that it be up to date | Refused when the default branch has moved: `g1t pr update-branch`, then merge again. | |
| 189 | | A required deployment | Waits for the pull request's head to deploy, such as its preview. | |
| 190 | | 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. | |
| 191 | |
| 192 | The agent merges as you, so whatever you may bypass, it may too: |
| 193 | `g1t pr merge --admin` (`ignore_checks` and `bypass_rules` on |
| 194 | `pull_request` `merge`) merges past required checks and rules where you |
| 195 | have the Admin role and a rule lets you. To keep that, or merging at all, |
| 196 | to yourself, say so in the repository's `CLAUDE.md`, and leave |
| 197 | `g1t pr merge` to ask in Claude Code's permissions. |
| 198 | |
| 199 | ## What the agent can and can't do |
| 200 | |
| 201 | | | The agent | How | Needs | |
| 202 | | --- | --- | --- | --- | |
| 203 | | Create a repository | Yes | `g1t repo create`, or `repository` `create` | `repo:create`, which the Agent preset gives | |
| 204 | | 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` | |
| 205 | | Open and claim an issue | Yes | `g1t work claim`, or `issue` `claim` | `issues:write` | |
| 206 | | 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` | |
| 207 | | Watch checks and the preview | Yes | `g1t pr checks --watch`, or `pull_request` `get` | `pull_requests:read` | |
| 208 | | Merge | Yes, within the repository's rules | `g1t pr merge`, or `pull_request` `merge` | `pull_requests:write`, and the Write role | |
| 209 | | Approve its own pull request | No | Someone else approves | | |
| 210 | | Read deployments, logs and errors | Yes | `g1t deploy list` and `g1t logs`, or `workflow` `list_deployments` and `observability` | `deployments:read`, `observability:read` | |
| 211 | | Start the g1t plan | No | An owner, under **Settings → Billing and plans** | | |
| 212 | | Turn deployments on or off, or change their settings | No | You, under the project's **Settings → Deployments**, with the Admin role, or by starting [Ask's card for a new repository](/guides/ask/#building-something-new) | | |
| 213 | | Build production again | No | **Redeploy** on the project's overview, with the Write role, or a push to the default branch | | |
| 214 | |
| 215 | Scopes are explained under [scopes](/guides/authentication/#scopes); |
| 216 | [MCP tools](/reference/mcp/) and the [CLI reference](/reference/cli/) list |
| 217 | every action and command. |
| 218 | |
| 219 | ## Or start from Ask |
| 220 | |
| 221 | [Ask](/guides/ask/), and `@g1t` in Chat, reads g1t as you and changes |
| 222 | nothing itself: it cannot push, merge or deploy. Ask it to build something |
| 223 | that has no repository yet, though, and it proposes a session for a new |
| 224 | one. When you choose **Start session** or **Copy Claude Code command** on |
| 225 | that card, your click creates the repository, turns on its deployments |
| 226 | (with the g1t plan), opens the issue and starts the session, which pushes |
| 227 | the first version and watches it go live. See |
| 228 | [Building something new](/guides/ask/#building-something-new). |