Create a project and connect its repository

A project is what an agent is pointed at. It lives in the active Workspace and it is the thing every other surface hangs off: the tasks you launch against it and their runs, the issues it imports and the backlog they feed, the workflows and automations that act on it, its own environment variables and container image, and its policy — who may work on it, how far unattended, what it may spend. Above all it carries the credentials the agents use: one git credential for the repository, and optionally one tracker credential for an issue source.

No agent runs without one. Creating a project is open to any Workspace member; most of what you can configure on it afterwards is not.

Add the Git credential first

The credential picker on the create form only lists credentials that already exist. Store one under Settings → Git before you start here, and give it write access to the repository — an agent clones, commits and pushes a branch back. See Manage secrets in the UI for the scopes (personal, Workspace, Organization) and which one wins.

Create the project

1. Open Projects in the sidebar and press New Project. On a phone the create action is the round button at the bottom of the list. You land on /projects/new.

2. Fill in the four fields, in this order:

   • Name — how the project appears in every list, and the word you type in the web terminal’s run command. Required.
   • Git Repo URL — required. Both URL forms are accepted; the placeholder shows the SSH form, ssh://git@git.example.com:2222/org/repo.git.
   • Git Provider — Forgejo (the default), Bitbucket, GitHub or GitLab. Changing it clears the credential below, so pick the provider before the credential.
   • Git Credential — the picker lists only credentials that match the provider you just chose, each labelled with its kind: (SSH Key) or (Access Token). With no match it offers just No credential and a link reading Add credentials in Settings.

3. Press Create Project. You land on the new project’s page.

Match the credential kind to the URL form

A Git credential has a kind, and the two kinds are not interchangeable — the create form filters by provider, not by kind, so it will happily let you pair the wrong one with your URL.

• An SSH Key authenticates the git transport. It works with an ssh:// or git@… URL, and it covers clone and push.
• An Access Token authenticates the provider’s HTTP API. That is what browsing issues, opening pull requests and listing repositories go through, and it pairs with an https:// URL.

A project binds exactly one git credential, so the choice is real: an SSH-only project can clone and push but cannot reach the provider’s API. If you want SupaCloud to read issues and open pull requests for you, use an HTTPS URL with an Access Token. What the resulting errors look like is covered in Troubleshoot a stuck or failed run.

There is no branch field on the create form — the Default Branch is set afterwards, in the project’s Configuration tab (below). Set it explicitly if your repository’s default is not main: a branch that does not exist is one of the three things behind the “Git clone failed” message, and it looks exactly like a bad URL or a bad credential from the outside.

Import several repositories at once

If you are onboarding a whole organization rather than one repository, the projects board has an Import action next to New Project (on a phone, an icon in the top bar) that creates one project per repository in a single pass.

1. Press Import. You land on /projects/sync, titled Import Projects.

2. 1. Select Provider — press Forgejo, Bitbucket, GitHub or GitLab.

3. 2. Select Git Credential — pick a credential, then press Fetch Repos. Some providers need one more value next to the picker: Bitbucket wants the Bitbucket workspace name, and Forgejo and GitLab want the host, for example https://git.example.com. GitHub needs neither.

4. 3. Select Repositories — tick the ones you want. Repositories that already have a project are shown greyed out and badged imported, so a second import cannot duplicate them; Select all takes only the importable remainder. Each row shows the repository’s default branch.

5. Press Import projects. Each selected repository becomes a project carrying its name, its clone URL, its provider and its default branch.

Import lists access-token credentials only

This wizard talks to the provider’s API, so it offers only Access Token credentials — an SSH key cannot list repositories. With none stored you get “No matching access-token credentials available” and a link reading Add in Settings. An SSH credential is still fine for clone and push afterwards; swap it in on the project once it exists.

Connect an issue tracker

Where a project’s issues come from is a separate, optional binding, and there are six possible sources: the four git forges’ own issues — Forgejo, GitHub, GitLab and Bitbucket — plus Linear and Notion.

A project you just created is already wired to the first kind: with no tracker set, its issues are the ones in the repository you bound. Setting a tracker replaces that source rather than adding to it — whenever Issue tracker source is Linear or Notion, that is where every issue read, comment and status transition goes, and the forge’s own issue list is no longer consulted. So leaving the field on None is a real choice, not an unconfigured state.

1. Open the project, then the Configuration tab, then the Repository & source row. The tracker block sits directly under the repository fields.

2. Set Issue tracker source. None (use git provider) keeps the forge’s own issues; Linear and Notion switch the source.

3. Identify the collection to read. Linear asks for a Team key — Linear’s own identifier for the group the issues belong to; Notion asks for a Database id.

4. Press Connect Linear or Connect Notion. This is a full-page OAuth authorization: you approve at the provider and come back to the project with a confirmation. Then pick the resulting connection under Tracker credential.

5. Optionally override the state names SupaCloud writes back when a task finishes — success, failure and in progress. Leave a field empty and the documented default applies; an empty failure means SupaCloud comments and leaves the item open.

6. Press Save at the bottom of the Configuration tab.

Binding a tracker makes its issues browsable in the project’s Issues tab and launchable: you can start a task straight from an issue, with the title and prompt seeded and the run linked back to it. See Launch a task from an issue.

Underneath the state names sits Enable issue-tracker auto-developer and a webhook secret. That is a different question — not where issues come from but whether SupaCloud works them on its own. Leave it off until you have read Choose the autodev mode.

Tracker connections are not personal

Unlike API keys and Git credentials, a Linear or Notion connection has no personal tier — it is Workspace- or Organization-scoped only. Switching the provider clears the credential and the state overrides, so a Linear connection can never be persisted under Notion by accident.

Configure the project

Everything else about a project lives in one place: the Configuration tab on the project page (deep-linkable as ?tab=config, and the destination of both the row kebab’s and the footer’s Settings). It is a single inline accordion — there are no separate read-only settings tabs and no edit dialog any more.

It opens on a plain-language sentence describing the project’s current policy; each clause in it is a link that opens the row that owns it. Below that, a one-press Set up safe backlog automation shortcut seeds a known-good starting point, and every field it touches stays editable.

The seven rows:

Row	What it holds	Where it is documented
Repository & source	Name, provider, Default Branch, repo URL, git credential — and the issue tracker above	This page
Who & how far	Autonomy level, effort, which agent profiles may take the work	Set the autonomy level
Approvals & merge	The concept and draft-PR gates, and the merge policy	Choose the autodev mode
Automation	The autodev mode, the classifier, the PR-review lane, the review loop	Choose the autodev mode, Run the backlog
Closeout	What an agent does at the end of every task, and memory governance	Configure the standard closeout, Manage memories
Guardrails	Environment scope, denied tools, required reviewers, budgets, concurrency, worker groups	Below, and Track usage and budget
Environment & build	Project environment variables and the project’s container image	—

One Save at the bottom persists the project itself. Three controls save independently through their own endpoints — the concurrency limit, the image build, and the environment variables — so pressing their own buttons is what commits them.

A member sees this read-only

The Configuration tab is editable by a Workspace owner or admin. A member sees the same rows with the banner “You have read-only access to these settings.”, no Save button, and the rows inert.

Cap what the project may spend

The Guardrails row carries the project’s own money limits, so one noisy repository cannot drain a Workspace budget.

• Daily budget cap ($) and Monthly budget cap ($) are project totals. They bind every task launch against the project — hand-launched, backlog and PR-review alike, not only backlog runs — and they compose under the Workspace budget: both must allow the spend. Leave a field blank for no project cap.
• The backlog-specific limits sit alongside them: a backlog daily budget, a backlog concurrency cap and a required reviewers bar, which apply only to autonomously dispatched work.

Both caps are a hard stop, not a warning. When the day’s or the month’s spend has reached one, the next launch is refused outright with “Project daily AI budget exhausted” or “Project monthly AI budget exhausted”, naming the figure and the cap; raise the cap or wait for the window to roll over. The two windows are independent — either one being full is enough to refuse.

Only a Workspace owner or admin may set them, and only on an existing project — they are not fields on the create form. For the Workspace-level budget these sit under, and for reading what has actually been spent, see Track usage and budget.

Keep a repository and the Workspace in sync

This is worth naming because the words look alike and the features are not: Import Projects (above) reads many repositories once, to create projects. Repo Sync binds one repository to the Workspace as a durable, two-way home for what you build inside SupaCloud. It is Workspace-level, not per-project, and it lives under Settings → Data & sync → Repo Sync — where you set the repo URL, the branch and a credential Resource, and get Push to repo and Pull from repo buttons plus a log of recent sync activity.

What travels: workflows, scripts, apps, resources and memories, each serialized to a file in its own directory. Resource secrets and workflow trigger secrets are stripped on the way out; personal-scoped memories are never serialized and a personal memory in the repository is refused on the way in.

Three things about it are worth knowing before you press either button:

• Sync direction is a setting. Bidirectional (the default) allows both; Repo only makes git the source of truth and disables Push; UI only makes the UI the source of truth and disables Pull. The disabled button carries a tooltip saying which.
• Conflicts resolve last-write-wins, per item. Pull from repo opens a Pull preview first, listing what would be created, updated or skipped and showing each conflicting file with both versions and a badge naming the winner. Per file you can press Use remote (override) to force the repository’s version, or Keep local, which just confirms the default outcome and changes nothing. Apply pull then commits the rest.
• Deletions do not travel — with one exception. For workflows, scripts, apps, resources and memories, removing a file from the repository does not remove the row on pull, and deleting an item in the UI does not remove its file on push; tidy up on both sides yourself. The exception is the shared code library (lib/): a pull does remove a file you deleted in the repository, because a shared library whose deletions never arrive is a cache rather than a source. A library file you edited more recently in the interface survives that prune. See Share code between code nodes.

Push uses a username/token pair read from a Workspace Resource you nominate, so give it an HTTPS repository URL; leaving the credential empty is only for a public repository. Configuring and running sync requires Workspace admin rights. Auto-push is an opt-in toggle that pushes workflow, script and app changes on a short delay; resource and memory edits, and every deletion, still need a manual push. How memories in particular travel is covered in Manage memories.

Archive or delete a project

Two different actions live in the project row’s kebab menu on the projects board, and only one of them is reversible.

Archive project takes it out of the active board without destroying anything. It reappears under the Archived tab, where Restore project brings it back. Archiving is not merely cosmetic: an archived project is excluded from the autonomous backlog scan, so it stops picking up and dispatching work of its own accord. No confirmation is asked, because nothing is lost. This is what you want for a repository you are done with for now.

Delete asks “Are you sure you want to delete this project?” and is permanent. It is worth knowing precisely what goes and what stays:

• Destroyed with the project — its workflows (and the runs of those workflows), its backlog items, its automation configuration, its project environment variables, its scheduled reports and its agent permission grants.
• Kept, but detached — its tasks and their agent runs, its task schedules, its cost and outcome records, its audit history and its project-scoped memories. These survive with the project link cleared, so the record of what happened remains even though the project that framed it is gone.
• Untouched — the repository and the issue tracker. No commit, branch, issue or pull request is changed; SupaCloud only drops its own side.

Delete is not gated, and does not wait

The confirmation dialog is the only thing standing in front of the delete: it is not restricted to owners and admins the way the Configuration tab is, so any Workspace member who can see the project can remove it. Nor does an in-flight task block it — deleting a project with work running does not refuse and does not stop that work. Since archiving is free and reversible, archive first whenever you are not certain.

See also

• Get started with SupaCloud — the tutorial that hands off to this page
• Your first agent run — what to do with the project you just made
• Manage secrets in the UI
• Launch a task from an issue
• Choose the autodev mode
• Workspaces and Organizations