Skip to content
GitmoapdocsBeta
Guide· How do I…?

Getting set up

On this page you can4 tasks
2 endpointsTroubleshootingFAQShow tasks as

Overview

The getting-started checklist tells you what is left before your account is genuinely usable: a repository of your own, something pushed into it, and a git client on your machine that can authenticate. It keeps itself up to date from what you actually do — there is no box to tick — and it carries the two facts you need to start, which are where your personal namespace lives and what to clone.

Tell it whether you are here on your own or setting up a team and it records that, which is what retires the first-run welcome. Hide the checklist when you no longer want it on screen.

Before you start

  • A signed-in account of your own.No membership and no access level come into it — the checklist is scoped to whoever is signed in. The address carries no identifier, so there is nothing to point at somebody else's, and no administrator view onto it.
  • A token with the right scope, if you are calling the API or the CLI rather than clicking: onboarding:read to read the checklist, onboarding:manage to set your intent or hide it. Scopes are chosen when you mint a token and cannot be added afterwards, so a script that only reads progress should carry only onboarding:read.
  • Nothing else has to exist.The read answers on a brand-new account with nothing in it — the three deciding steps read as pending, and it never answers 404. You do not create a checklist; you just read one.
  • Your own credentials, not a service account's.A service account has no getting-started journey, so a service-account token gets an inert, permanently empty checklist and its writes change nothing.

How it works

Five steps, of which three decide whether you are set up. The other two record provisioning rather than anything you do, and neither of them holds up completion.

email_verified ──▶ created_namespace ──▶ created_first_repo ──▶ pushed_first_commit ──▶ connected_git_client
account automatic └──────────── these three decide completion ───────────┘
StepWhat it meansWhat satisfies itDecides completion
email_verifiedyour address is confirmedhaving an account at all — the address is confirmed before the account existsno
created_namespaceyou have somewhere of your own to put repositoriescreated for you at sign-up; signing in again creates it if it is missingno
created_first_repoyou own at least one repositorya repository created directly in your personal namespace, not in a group nested inside ityes
pushed_first_committhat repository has something in ityour personal namespace holding bytes — an empty repository holds noneyes
connected_git_clientsomething on your machine can authenticate as youholding at least one personal access tokenyes

next_step names the first of the three deciding steps still pending, in the order above, and goes null when all three are done. completed_at is stamped once, on the first read that sees all three complete, and stays where it is afterwards.

Steps are observed, never claimed. The only two things you can write are your intent and whether the checklist is hidden. There is no field that marks a step done, so nothing you or a script sends can report progress that did not happen.

A timestamp records the first time we saw a step done, and it never moves. Every read recomputes the pending steps from live signals and stamps whichever have finished since last time, so progress you made through git, the CLI or another browser shows up the next time you look. Once a step is stamped it stays stamped even if the thing behind it goes away: revoke your last personal access token and connected_git_client keeps its date while activation.has_access_token flips back to false. The step is a record of what happened; the activation block is the live answer.

Intent is a three-way state, and unknown is the interesting one. A fresh account starts at unknown, and the first-run welcome appears while intent is unknown on a checklist that has been neither completed nor hidden; setting intent to solo or team retires it. Intent records what you are here for and gates nothing — choosing solo leaves you free to create an organisation the same afternoon, and choosing team creates nothing on its own.

Hiding and finishing are independent. You can hide an unfinished checklist and it stays hidden while progress carries on being recorded behind it; finishing one does not hide it.

The activation block on every response carries your personal namespace's current path and id, whether you hold a token, and a suggested git clone command. Both the path and the suggestion stay null until your namespace has been resolved; the suggestion also needs a clone address to build from, so it can be null on a response whose path is not.

How to

See what is left to do

The read gives you every step with its date, the first deciding step still pending in next_step, and the activation block that tells you where your first repository should go. It is safe to poll while you work through the steps: reading twice in a row returns the same dates, and reading after a push returns the newly stamped one.

Sign in and the checklist is the Get started panel on your home page. Each step shows either the date it completed or the action that finishes it, with the suggested next step called out. The panel also shows the namespace path your repositories go under and a git clone line to start from.

Terminalbash
gitmoap onboarding get-user-onboarding
curlbash
curl -X GET https://api.gitmoap.example/user/onboarding \
-H "Authorization: Bearer $GITMOAP_TOKEN"

Say whether you are working solo or with a team

Set intent to solo if you are here for your own work, or team if you are setting up for other people. The write returns the whole checklist, reconciled, so there is no follow-up read to make. The body is a partial update: omit a field and it keeps the value it had, and sending the same value twice changes nothing. Sending unknown puts the record back into its first-run state, which brings the welcome back on a checklist you have neither completed nor hidden.

The first time you sign in, the welcome asks what brings you here and offers Just me and My team. Choosing one records your intent and closes the welcome. To change it later, pick the other option in your account settings.

Terminalbash
gitmoap onboarding patch-user-onboarding
curlbash
curl -X PATCH https://api.gitmoap.example/user/onboarding \
-H "Authorization: Bearer $GITMOAP_TOKEN"

Finish the three deciding steps

  1. Create a repository in your personal namespace. Use the path from activation.personal_namespace_path, and put the repository in that namespace itself — one created inside an organisation, or inside a group nested under your namespace, is counted against that group instead. created_first_repo is stamped on the next read.

  2. Push a commit into it. Creating a repository leaves it empty, and an empty repository is what keeps pushed_first_commit pending. Clone with the command from activation.clone_hint, commit something, and push; the step is stamped on the next read after the push lands.

  3. Mint a personal access token. This is what connected_git_client counts, and it is what lets git on your machine authenticate without a browser. Signing in to the CLI stores a session rather than a token, so it leaves this step where it was.

With all three stamped, next_step reads null and completed_at carries the moment it happened.

Hide the checklist

Set dismissed to true and the checklist stops being shown. Nothing stops being recorded — steps carry on being stamped, and setting dismissed back to false brings it back with your progress intact.

Note

Hiding is not the same as finishing. A completed checklist stays on screen until you hide it, and a hidden one keeps tracking. If it reappeared after you thought you had hidden it, check that the call went out with your own credentials rather than a service account's — a service-account write is accepted and changes nothing.

Open the Get started panel and choose Dismiss. The panel leaves your home page, and the same preference in your account settings brings it back.

Terminalbash
gitmoap onboarding patch-user-onboarding
curlbash
curl -X PATCH https://api.gitmoap.example/user/onboarding \
-H "Authorization: Bearer $GITMOAP_TOKEN"

Reference

2 endpoints

GET/user/onboardingonboarding:read

Read the caller's personal onboarding state (the getting-started checklist)

get_user_onboardingGET /user/onboardingOpen in the API reference

Token scope

onboarding:read

Send

Nothing — the address is the whole request.

Refuses

  • 401Unauthorized
  • 403Forbidden — the caller's access level or token scope is insufficient

Receive

  • activationobject4 fields
    • clone_hintobjectoptionalA suggested git clone command for a new repo in the namespace.
    • has_access_tokenbooleanWhether the caller holds any personal access token (a connected git client).
    • personal_group_idobjectoptional
    • personal_namespace_pathobjectoptionalThe personal namespace's current path to clone into.
  • completed_atobjectoptional
  • dismissedboolean
  • intentsoloteamunknownThe person's stated goal, captured by the first-run Welcome. Unknown is the canonical "the Welcome has not been completed" signal — a fresh record starts here, and the first PATCH to Solo/Team retires the Welcome. There is deliberately no separate "onboarded" flag.
  • next_stepobjectoptional
  • stepsobject5 fields
    • connected_git_clientobjectoptional
    • created_first_repoobjectoptional
    • created_namespaceobjectoptional
    • email_verifiedobjectoptional
    • pushed_first_commitobjectoptional
PATCH/user/onboardingonboarding:manage

Set the caller's onboarding intent or dismiss the checklist

patch_user_onboardingPATCH /user/onboardingOpen in the API reference

Token scope

onboarding:manage

Send

Body
  • dismissedobjectoptional
  • intentobjectoptional

Refuses

  • 400Invalid request
  • 401Unauthorized
  • 403Forbidden — the caller's access level or token scope is insufficient
  • 409The request conflicts with the resource's current state; `reason` says how

Receive

The same shape get_user_onboarding returns — 6 fields. Go to it

Show it here
  • activationobject4 fields
    • clone_hintobjectoptionalA suggested git clone command for a new repo in the namespace.
    • has_access_tokenbooleanWhether the caller holds any personal access token (a connected git client).
    • personal_group_idobjectoptional
    • personal_namespace_pathobjectoptionalThe personal namespace's current path to clone into.
  • completed_atobjectoptional
  • dismissedboolean
  • intentsoloteamunknownThe person's stated goal, captured by the first-run Welcome. Unknown is the canonical "the Welcome has not been completed" signal — a fresh record starts here, and the first PATCH to Solo/Team retires the Welcome. There is deliberately no separate "onboarded" flag.
  • next_stepobjectoptional
  • stepsobject5 fields
    • connected_git_clientobjectoptional
    • created_first_repoobjectoptional
    • created_namespaceobjectoptional
    • email_verifiedobjectoptional
    • pushed_first_commitobjectoptional

Troubleshooting

400 BAD_REQUESTnaming intent
Cause
The value is something other than solo, team or unknown
What to do
Send one of the three. unknown is accepted and puts you back into the first-run state, so use it deliberately
400 BAD_REQUESTnaming a field you sent
Cause
The body accepts intent and dismissed and rejects anything else outright, including a step name
What to do
Remove the extra field. Steps cannot be set by hand — finish the step and the next read stamps it
401 UNAUTHORIZED
Cause
No credentials on the request, an expired session, or a token that has been revoked
What to do
Sign in again, or mint a replacement token. A token that worked yesterday and fails today has usually been revoked rather than expired
403 INSUFFICIENT_SCOPE
Cause
The token is valid but was minted without the scope this call needs
What to do
Mint a new token carrying onboarding:read, or onboarding:manage for the write. Scopes are fixed at mint time and cannot be added to a token you already have
Every step is pending and every activation field is null, on an account that has repositories
Cause
The call went out with a service-account token, which has no getting-started journey
What to do
Repeat the call with your own credentials
created_first_repo is pending after you created a repository
Cause
The repository sits in an organisation, or in a group nested under your namespace, rather than in the namespace itself
What to do
Check activation.personal_namespace_path and create one directly there, or leave the step pending if the other group is where your work belongs
pushed_first_commit is pending after you created a repository
Cause
Creating a repository leaves it empty, and an empty repository holds nothing to count
What to do
Clone it, commit, and push. The step is stamped on the next read after the push lands
pushed_first_commit is pending after a push
Cause
The push went to a repository outside your personal namespace, or it was rejected before it landed
What to do
Read the push output — a rejected push leaves nothing behind. Then push to a repository under the namespace path in the activation block
connected_git_client is pending after gitmoap login
Cause
Signing in stores a session; the step counts personal access tokens
What to do
Mint a personal access token. That is also what git on your machine needs to push without a browser
activation.clone_hint and personal_namespace_path are both null
Cause
Your personal namespace has not been provisioned
What to do
Sign out and back in — signing in creates a missing personal namespace. If both stay null after that, clone from your repository's own page instead and carry on
The first-run welcome keeps appearing
Cause
Your intent is still unknown on a checklist that has been neither completed nor hidden — closing the welcome without answering it leaves intent where it was
What to do
Set intent to solo or team, which is what retires the welcome. Hiding the checklist retires it too, but leaves your intent unrecorded
The checklist is complete but still on the page
Cause
Completing does not hide anything
What to do
Hide it, by setting dismissed to true
A step's date is later than when you did the thing
Cause
The date records the first time we observed the step done, which is the first read after it happened
What to do
Nothing to fix. For the exact moment, use the repository's or the token's own creation date
429 TOO_MANY_REQUESTScreating that first repository
Cause
The group you are creating in is at its repository cap — 20 repositories per group on the Free plan
What to do
Delete a repository you are not using, or request a limit increase for the namespace; on your own namespace you are the Owner, which is the level that can ask. Nothing was partially created
The first push is refused for quota
Cause
The namespace is at its storage limit — 5 GiB on the Free plan — or the push itself is over the 2 GiB single-push limit
What to do
Remove large files from the history and push again, or push it in smaller pieces; request a limit increase if the namespace itself is full. Refs roll back on refusal, so nothing lands

FAQ

Can anyone else see my checklist?

No. There is no identifier in the address to point at another person's, and no administrator view onto it. Your progress is yours.

Can I mark a step done myself?

No, and that is deliberate: a step is stamped because the platform saw the thing happen. If a step looks wrong, the fix is in the Troubleshooting table above rather than in the request body.

Does hiding the checklist stop it tracking?

No. Steps carry on being stamped while it is hidden, so bringing it back shows where you actually got to.

Does choosing team create an organisation?

No. Intent is a statement about what you are here for; creating an organisation is a separate, deliberate act.

What happens if I delete the repository I made?

The steps keep their dates and completion does not reverse. The checklist records that you got there, not that you are still there.

Related

  • Repositoriescreating the repository the checklist asks for, and the namespace it has to go in
  • Access tokensminting the personal access token that connects a git client, and choosing its scopes
  • Groupsnamespaces, including the organisation you would create if you are setting up for a team
  • Your accountyour username, your profile, and the namespace path they determine
  • Your dashboardwhat replaces the checklist once you are set up: what needs your attention and what changed
  • Billing and plansthe plan behind the repository and storage limits, and how to ask for more