Skip to main content

Add a project

A project is what Jaah works on: one or more repositories, or none. Add one before you start tasks on a new codebase. An API and its web app can be one project with two repositories.

Who can do this: adding a project needs the permission to create projects. An Org Owner or Org Admin has it, and so does someone granted Project Maintainer on the whole organization. Without it, the Add project or New project button doesn't appear. With the org admin role, the project is placed on every enabled node; without it, it is placed on none and an admin adds its nodes later.

Create the project​

The New project page on an existing app's Details step

  1. In the sidebar, select Directory, then the Projects tab.

  2. Select Add project, or New project if you have no Git account connected. The New project page opens beside the list and walks you through a few steps, shown in the step bar at the top. Each question is a set of large cards, each with a line on when it fits best. Select a card to move on, or pick one with the keyboard and select Next. Back returns to the step before with your answers kept.

    • What are you making? App / Website (building software or a site) or Business / Sales / Marketing Initiative (a business activity such as sales, marketing, research, content or finance, run with agents, no coding needed). A business initiative is always new, so it goes straight to its details.
    • Is it new or existing? (an app only) New or Existing.
  3. Fill in the details your answer needs:

    • Existing: your repository, then Name. Enter the repository's address in Repo URL and its Integration branch: the branch runners open pull requests into. If Jaah can't tell which forge the repository is on, a Forge list appears: pick yours. To add another repository, select Add another repository; the first one is the primary. Picking a listed repository fills in Name, until you type a name yourself.

      The first time, with no Git account connected, the page says so above Repo URL. Select Connect to open New Git account, then pick the account's Type and how to connect. Signing in opens a window; once the account lands you are back on New project with what you entered kept, and your repositories are listed. You can also skip it and paste the address.

      If the repository has no branches yet, Jaah says so under Repo URL, and Create project gives it a main branch (a README and a .gitignore) and a develop branch, the project's integration branch.

      To start on a new repository instead, select Create a new repository, pick its Owner and enter a Repository name. Create project makes it private, with main and develop, through your own git connection. The owners offered are those your connected forges list repositories under. Where Jaah's GitHub App may not create repositories under an owner, Create project first opens a GitHub window to approve Jaah once; it then makes the repository with your own access and keeps that approval as your GitHub connection. Allow pop-ups for the console if your browser blocks the window. Where no such approval is set up, a Create it on GitHub link opens GitHub's new-repository page filled in instead: create it there, empty and private, then Create project here adds main and develop.

    • New app: Name, then What kind of app?: Web app (runs in a browser, hosted by Jaah; picked to start) or Something else (mobile, desktop, scripts).

    • Web app: Name, the Address the app will get, and Describe your app: what it does and who it's for, in your own words. You pick no technology. Jaah makes the repository, hosts the app and opens the app's build epic, where the App Wizard asks a few plain questions about anything your description left out; then Jaah designs, plans and builds the first version.

    • Something else: Name. Jaah makes a private repository with main and develop.

    • Business: Name and Describe the initiative: what it is, who it's for and what you want done. Jaah makes a private repository with main and develop.

    Under the fields, What happens next says what Create project starts.

  4. Select Create project, or Cancel to go back where you came from. With the org admin role, the project is placed on every enabled node the page names, online or not; a task on an offline node waits until it is online. Change the nodes later in the project's Settings tab, section Nodes. A new web app in an organization with a shared node runs on that node instead.

The page asks nothing about the pipeline: Jaah picks it from your answers, see The pipeline a new project starts with.

Creating an app project also starts a Repo Wizard task on it, in Guided mode: it finds out how the project runs, sets it up to run in Jaah, fills in its tech stack and environment, and asks you, in plain words, only what it cannot find out itself. For a new app, it asks what the project is about. On an existing app, you land on the project's tasks with that task open; if Jaah could not reach the repository from a node, the project's Settings › General opens instead, with the warning. A new app opens the project itself.

A business project starts a Business Wizard task instead, and you land on it. It asks plain business questions — your offer and customers, the goal and how you measure it, how the work runs today, who approves what, and what to hand over first — never again what your description says. Then it records all of it in the project, adds what its agents need for the jobs you want to hand over, and files those first jobs as draft tasks for you to start. The project now appears in the list. Once it has a node, runners take its tasks. Its tasks run on the first free engine (Any) until you set a Default agent in the project's Settings › General.

Check how runners deliver​

Before the first task, check that runners will work the way your team does.

  1. Select the project's name in the list to open its settings.
  2. In General, select each repository's name on the Repository line to check its Integration branch, then Done or Cancel. The primary's branch is the project's integration branch: only someone who can change Settings › Branches can change it.
  3. Select the Settings tab.
  4. Select Testing and check Quick gate command: the check a runner runs as it works, in the primary repository. Check Full gate command too: the full check, run before a change merges. On a custom pipeline it is the Merge step's gate on Pipeline instead.
  5. Select Branches and turn on Read only if runners may work in the repositories but must never push to them.
  6. Select Save.

Commands and agent instructions are readable by anyone who can view the project, so never put a password or a token in them. To hand a project a secret, use an environment variable read from a credential.

Next steps​