Skip to main content
Version: 0.1.151 – 0.1.152

Creating a project

A project modernizes a legacy app, maintains an existing one, or builds a new one. A modernization project pairs one legacy codebase with the modern codebase being built from it. A maintenance project has only your app's own codebase, and you add features to it. A new app starts with no code at all: Repave builds its foundation from your description, and you add features to that. Everything else — the specification, the implementations, the test runs — hangs off the project's codebases.

Before you start​

You need edit access to create a project, and your installation needs a valid licence. An unlicensed installation will tell you so on every screen and explain how to get one.

Start from New project on the dashboard (or, before you have any projects, from the dashboard's empty state). The page first asks which kind of project it is: Modernize a legacy app (the default), Maintain an existing app or Build a new app. To modernize, it asks for the legacy codebase, then where the modernized codebase comes from. To maintain, it asks only for your app's repository; see Maintaining an existing app. To build a new app, it asks for a description of the app, its stack and its repository; see Building a new app. Whichever you choose, Create project takes you straight to the new project.

The legacy codebase​

Drop the legacy source as one or more ZIP archives. The project name is filled in from the first archive's file name until you type one of your own. A file that is not a ZIP, or one you have already added, is skipped and the page says so. A few things happen to the archives on the way in, and it is worth knowing about them because they change what you see afterwards.

If the project is created but its archives fail to upload, the page says so and keeps what you entered: pressing Create project again retries the upload into the same project rather than creating a second one.

  • Oversized uploads are refused, not truncated. If the archive exceeds the limit your operator configured, the upload fails and nothing is stored. A partially ingested codebase would produce a specification with holes in it and no sign that anything was missing.
  • An archive that expands without bound is refused mid-extraction, and a refused upload leaves nothing behind.
  • A single wrapping folder is flattened. If your archive contains one top-level directory with the project inside it, that directory is unwrapped rather than treated as the codebase root.
  • Non-UTF-8 source is converted before anything reads it. Legacy code in a regional encoding would otherwise reach the analysis as mojibake. The originals are kept, and a project ingested before conversion existed is found and offered one.

The modernized codebase​

The choice is made when the project is created, from four options.

Start a new app. The platform generates a new application on the target stack you choose, and owns its structure from the start.

Upload a ZIP. An existing modernized application, imported as-is.

Clone one repository or Combine several repositories. You point the project at code you already have — on GitHub, Azure DevOps, Team Foundation Server, GitLab or Gitea — and the platform clones it. You do not declare its toolchain: the platform detects what it is built with from its build files and tells the agents, and every project runs on one environment that carries Node, Java and .NET, so Repave IDE and previews open whatever the stack. What a provided codebase needs that a scaffolded one does not is:

  • Its unit test configuration — where the suites are, how to run them, how coverage is reported. The platform detects this by running the suites, and reports why it will not run if detection fails rather than guessing.

Connecting to a repository​

GitHub and Azure DevOps connect with a personal access token. A classic GitHub token needs the repo and read:user scopes; a fine-grained one needs Contents, Pull requests and Issues: Read and write, the last so that Repave can open a GitHub issue for each change it builds. Team Foundation Server connects without deployment configuration, and where your server presents a private certificate authority you can trust it from the UI, or skip TLS verification for that one connection if you must.

GitLab connects with a personal access token that has the api scope, which Repave needs to open merge requests. The address starts as https://gitlab.com; change it only for a self-managed GitLab, to the address you open GitLab at. For a self-managed GitLab, Certificate options lets you supply a private certificate authority or skip TLS verification, as for Team Foundation Server, and opens on its own if your server's certificate isn't trusted. Projects in subgroups are listed by their full path. In pull-request mode, a GitLab project's pull requests are merge requests on GitLab.

Gitea connects with an access token (in Gitea, Settings → Applications) and the address you open your Gitea at. It works the same way with Forgejo. The token needs three scopes: User: Read, Repository: Read and Write, and Issue: Read. Connect checks each one, and if one is missing it tells you which to add. Certificate options lets you supply a private certificate authority or skip TLS verification, as for Team Foundation Server, and opens on its own if your server's certificate isn't trusted. Gitea 1.22 or later and Forgejo 7 or later are supported. To let Repave create the repository a combined workspace is built in, the token also needs Organization: Read and Write for an organization, or User: Read and Write for your own account; without it, use an existing empty repository instead.

Each project uses its own personal access token, entered when you create the project; a token you gave another project is never offered or shared. So a project in another organization simply gets a token for that organization. Once connected, the page names what the token reaches, such as GitHub · jsmith · acme; Use another token swaps it before you create the project. A GitHub fine-grained token reaches one owner; a classic token reaches everything your account can, and with the read:org scope Repave also offers the organizations that have no repository yet as places to create a new app's repository. When a project's token expires, replace it from the project's settings: Integrations → Git connection → Replace token. The new token must belong to the same account (for Azure DevOps, it must open the same organization).

Projects that combine several repositories​

A system split across several repositories can be one project. Choose Combine several repositories, pick the git connection, and tick the repositories. Every repository comes from that one connection. Each gets a folder in the combined workspace, named after the repository, and its default branch; you can change either. A repository with no branches yet can't be combined.

The combined workspace is built in a workspace repository. By default Repave creates it for you, empty and private, named after the project, in the same owner, group or team project as the first repository you ticked; you can change the name and where it goes. If you would rather use one you have made, choose Use an existing empty repository: it must have no commits, and Repave says so before creating the project if it has any. One workspace repository serves one project. The folder where the shared BDD features and end-to-end scripts live is under Advanced; most projects keep its default.

After creation, the source repositories are managed from project settings, changes are pulled in from each, and work done in the combined workspace is pushed back out to the repositories it belongs to.

The combined workspace is rebuilt from the repositories each time they change, so a change made directly in it, under one repository's folder, would be overwritten. When Repave finds one it stops the sync and the banner on the project page reads "Changes were made under … on the combined branch that haven't been sent to those repositories." Send to source repositories opens a pull request for the change in each repository it touches, takes it off the combined branch, and syncs again; review and merge the pull requests, then sync to bring the change back. Nothing is merged or discarded: the change stays in the combined branch's history and in the pull requests. You need edit access to the project to send changes.

Maintaining an existing app​

Choose Maintain an existing app when there is no legacy system to migrate: your app already exists, and you want Repave to build new features in it.

The page asks for Your codebase, from one of two sources:

The project name is filled in from the first repository you choose until you type one of your own. There is nothing to upload. A maintenance project takes its codebase from git only: Repave works on a branch of your repository and opens a pull request for each feature, which an uploaded ZIP could not take. A maintenance project never takes a legacy codebase later either.

Once the project is created, Repave clones your codebase, and the banner on the project page shows progress. Add feature waits for the clone, and its tooltip says so; if the clone fails, retry it from the banner. Then describe each feature you want, and Repave writes its scenarios from your codebase for you to review; see Adding a feature to an existing app.

Feature files already in your repository​

If your repository already describes its behaviour in Gherkin, those features are where the project starts. As soon as the clone finishes, Repave reads every .feature file directly in the project's BDD Features Path (features unless you change it) on your base branch, and each file becomes a feature on the Features page, which fills while the import runs. Each one is already Merged, with every scenario approved and implemented, and its scenarios are stored exactly as the file has them: Repave adds nothing to your files, and never writes to your repository to import them.

  • Files in a subfolder of the features folder are not imported; neither is a file you have not committed. Repave reads what is on the base branch.
  • If the features folder holds no feature files, Repave looks for the folder that does. When exactly one folder has them, it uses that folder and saves it as BDD Features Path. When several do, the Features page asks Where are this app's feature files? and imports from the folder you choose; that folder is also where your tests run and where new features are written.
  • A file that cannot be read (no Feature: line, text that is not UTF-8, or a Gherkin syntax error) is listed above the features with the reason, and the rest are imported. Fix it in the repository; it is imported once the fix reaches your base branch.
  • Changes on your base branch are picked up within about ten minutes: a new file becomes a feature, a changed file updates its feature (changed scenarios are marked Updated or New, and a scenario you deleted is deleted), and a renamed file keeps its feature.
  • A file you delete removes its feature only if nobody has worked on it in Repave: no module, owner, tags, labels, comments, reviews, journeys or bug reports, no edit to its scenarios, and it has not been reopened. Otherwise the feature stays, and its Gherkin tab says the file is missing.
  • Changing BDD Features Path re-imports from the new folder, and removes the untouched features the old folder brought in.
  • If the import itself fails (Repave cannot fetch your base branch, or the folder cannot be read), the Features page says so, with a link to the log and Retry import.

Imported features are the project's starting point, not work Repave delivered: the delivery figures on the Costs page and the progress workbook do not count them.

A maintenance project has no legacy codebase to discover, so the pages that only a legacy codebase could fill (the source files, the as-is architecture, discovered requirements and user journeys) are not shown, and there is no application shell to design before the first feature: your app already has one.

Your repository's own instructions​

Repave works the way your team does. Every agent that works on a maintenance project follows the agent instructions file your repository keeps for coding agents, whether it is written for Claude Code or for Codex, and can use the skills your repository keeps for them. Where your repository and Repave's own guidance disagree on a convention, a command, a test or how scenarios are written, your repository wins. Repave still decides where its own output goes, how it is saved, and everything to do with git, issues and pull requests: an instruction in your repository to push, open a pull request or deploy is left to your team. An agent that could not follow a step your repository asks for says so at the end of its run, in a line starting Left out from the codebase's instructions:.

Some of your repository's skills are not offered to agents:

  • a skill with the same name as one of Repave's own skills;
  • a skill whose author marked it as not for the model (disable-model-invocation: true);
  • in a project that combines several repositories, a skill name more than one of them uses;
  • a skill that, by its name and description, pushes, merges, opens issues or pull requests, deploys, releases, signs, or reaches a server or any system outside the codebase. Repave checks each skill once, and again only when its name or description changes. When the check is unsure, the skill is not offered.

Repave reads your agent instructions file and never changes it: you edit it in your repository like any other file. A maintenance project's Project Settings have no cards for agent instructions, and the agent instructions setup step does not apply to it.

Building a new app​

Choose Build a new app when there is no code yet: you know what the app should do, and you want Repave to build it.

The page asks for three things:

  • Your app. The project's name, and a description of the app: who uses it, what they do in it, and anything it must work with. Type it, attach a document (.pdf, .docx, .txt or .md), or both.
  • Target stack. The stack the app is built on, from the same choices a modernization project offers. It starts on Next.js full stack.
  • Repository. Where the app's code lives. Pick a git connection, then either let Repave create a new repository (it is named after the project, in your own account, and created private and empty), or choose an existing repository with no commits. When the connection offers nowhere to create one, such as an Azure DevOps connection with no repositories yet, type the group, team project or owner it belongs in. A repository that already has commits is refused, so nothing in it is overwritten.

A new app always works through pull requests: its foundation, and then every feature, reaches your repository as a pull request for your team to review and merge.

The foundation​

Create project takes you to the project's Features page, where a Your app's foundation panel shows Repave planning the foundation from your description. If your description never reached Repave, the panel says so and asks for it again. The foundation is everything your features will share: the app's screens and the navigation between them, its look and feel, how people sign in and the roles they sign in as, and the data it keeps. It is not the features themselves; each screen starts empty, and features fill them later.

When the plan is ready, read it in the panel:

  • Approve and build starts the build from the plan exactly as shown.
  • Ask for changes lets you say what should be different. Repave writes a revised plan, and you review that one instead.

Repave then builds the foundation on the stack you chose, checks that it builds and that its first test passes, and opens a pull request titled Foundation: followed by your project's name. Review it like any other pull request; Repave answers review comments on it. If the build fails, the panel says why and offers Try again, or Ask for changes to revise the plan first. If you close the pull request without merging it, Rebuild opens a new one from the approved plan.

Adding features​

Add feature waits until the foundation pull request has merged, and its tooltip says so. Once it has merged, the panel goes away and the project works like a maintenance project: describe each feature you want, and Repave writes its scenarios against your app's code for you to review. See Adding a feature to an existing app. A new app has no legacy codebase, so the pages that only a legacy codebase could fill are not shown.

What runs on upload​

Ingestion is not the end of it. The platform indexes the codebase, counts what is there, and begins the analysis that produces the as-is specification. You can watch this on the Analysis Jobs page — see Jobs — and you do not have to wait on that page for it to proceed.

The code index is a separate thing worth knowing about: two project settings decide whether it runs, it says what state it is in, and it can be rebuilt. Each codebase in a project is indexed separately and each is kept current as commits land.

When it is ready​

The project summary shows lines of code for the legacy and modernized codebases, and feature coverage closure — how much of what was discovered has been decided and built. When features start appearing under Discovered Features, the analysis has produced something to review.

Lines of code count every recognised programming language, including Delphi/Pascal and SQL scripts saved as UTF-16. Tests, third-party folders, hidden folders, documentation, data files (JSON, SVG, CSV), comments and blank lines are left out. The legacy count is the one your licence tier measures.

Next: Reading the analysis.