How projects work
A project is where Jaah works. Usually that is one or more repositories, such as an API and its UI, and every runner works in a copy of each; a project can also hold work outside a codebase, with no repository at all. Every task belongs to one project. The project's settings decide where that work happens, how a runner checks and delivers it, what it remembers between tasks, and who in your organization may use it.
This page explains the ideas behind projects. For the steps, see Add a project, Give someone access to a project and Add an environment variable. For every field on every tab, see Projects.
Terms
| Term | Meaning |
|---|---|
| Project | A place Jaah works, usually one or more repositories, with the settings Jaah needs to work there. |
| Repo | Whether the project has a repository. Cleared, the project is for work outside a codebase. |
| Repo URL | A repository's address on your forge. |
| Primary | The one repository the gate commands, the stack and the ports run in. A project with repositories has exactly one. |
| Slot | A working space for the project on one node, also called a worktree. A task runs in one. With a repository, a slot holds a copy of its code; without one, a task starts in an empty slot. |
| Integration branch | The branch runners open pull requests into. Each repository has its own; the primary's is the project's. |
| Gate command | A check a runner runs: the Quick gate command as it works, the Full gate command before it opens a pull request. |
| Environment variable | A value written into a slot's settings when a task claims it. |
| Memory unit | One thing a runner learned about the project, such as a gotcha or a recipe, which later tasks can be given. |
| Feature | A folder for related tasks inside a project. |
What a project's settings decide
A project's page opens on its Settings tab. Its settings are grouped in sections, General first and the rest in alphabetical order, as the console names them:
- General: its stages' addresses, its Repository line (each repository's address and integration branch, and which is primary), Default persona and Agent instructions. Its Advanced fold holds the Default agent and Default model, Routing, Run jobs as, the Tech stack and Notes. The project's name is renamed in place, above the tabs.
- Access: who may use the project, and with which role. See Who may use it.
- Branches: each repository's Read only, optional Branch prefix and Allow force push, and the project's Squash task PRs.
- CI Pipeline: the basic or custom pipeline. On a custom pipeline, the stages work moves through and the steps between them are edited here too.
- Issue trackers, Live Cast, MCP, Memory (the Project memory setting), Merge lanes, MicroVM and Nodes (the Node groups that run the project).
- Testing: the quick and full gates and the commands that start and stop the project's local stack.
- Variables: the variables its tasks get. See Environment and credentials.
Beside Settings, Owners and Admins of your organization see a Schedules tab: the automations that file tasks into the project. A project can also have Production QA, Benchmark and Budget tabs when its plan and settings include them. On the Tasks page, with the project picked in the sidebar, its Settings tab opens the same sections.
Two views of a project live under Audit, filtered to it: Merge lanes, its merge lane's runs, and Memory, what its runners have learned (see Project memory).
Commands and agent instructions are readable by anyone who can view the project, so a secret never goes there.
Projects with and without a repository
Most projects have Repo ticked: runners clone each repository into a slot, run the gate commands in the primary one, and deliver their work as a pull request into each changed repository's integration branch.
Clear Repo for work outside a codebase, such as research or writing. The project then has no repository-only settings: no repositories, no branch policy, gate or stack commands, and no port settings. Their values are kept, so ticking Repo again brings them back. A task starts in an empty slot on one of the project's nodes, and its outcome is its report rather than a merged pull request.
Languages and tools
A project can use any language, framework or build tool. Jaah doesn't detect or limit the stack: the project's settings tell a runner how to work with it.
- Gate commands are your stack's own checks, such as
npm test,pytest,go test ./...ormvn verify. A runner runs them, so they decide what "checked" means. - Stack commands start and stop what your tests need, such as a database.
- Agent instructions tell runners anything else, such as a code style or a tool to use.
- Tech stack, under Advanced, records what the project uses.
The tools those commands call must be on the project's nodes. A runner isn't an administrator, so it can't install system packages itself. See Languages and frameworks.
A project's lifecycle
- Created. Someone who can create projects selects Add project. It runs on All, every enabled node of your organization, unless someone who can edit it later picks its node groups.
- Dispatching. Once the project has a node, runners take its tasks.
- Hidden, for you. Hide takes the project out of your sidebar and its tasks off your board; everyone else still sees them.
- Deleted. An org admin deletes a project from its row menu, after typing its name. Its slots are deleted first.
How a project relates to the rest of Jaah
- Tasks and features. A task always belongs to one project and works in its repository. Inside a project, related tasks can be filed under a feature. See How tasks work.
- Epics. An epic belongs to a project too, and its subtasks run there. A subtask's question goes to the person it or its epic is assigned to, else to whoever created it, as for any task. See How epics and features work.
- Slots and nodes. A project runs on All or on its node groups, in a slot per task. A task needs a free slot, so the number of slots bounds how many of the project's tasks run at once. See How worktrees work and How nodes work.
- Personas. The persona a task uses decides how the runner works; the project's agent instructions add what's specific to this repository. See Personas and playbooks.
Who may use it
Your access to a project decides whether you see its tasks and what you may do with them. A role is granted under the project's Settings › Access, to a person or to a group:
| Role | What it allows |
|---|---|
| Project Viewer | Look at the project and its tasks. |
| Project Developer | Also run tasks on it. |
| Project Maintainer | Also change the project's settings. |
Each row under Access names its Source: Direct for a grant on this project, Via a group, or From the organization. A direct grant can carry an expiry date. See How team and access work.
Environment and credentials
A project hands its tasks two kinds of configuration:
- Environment variables, in Settings › Variables. Each value is either A literal you type in, or a field read from A credential, so a secret is never shown on the project. A variable applies to Everyone, or Only me: where you have your own value, your tasks get it instead of the project's.
- Attached credentials. A credential attached to the project is given to every task that starts on it. You attach one from the credential's own Access tab. See Attach a secret to a project and How secrets work.
Project memory
As runners work on a project, Jaah keeps what they learn as memory units: where things are in the code, gotchas, recipes, environment facts, and answers to questions. A later task in the same project can be given the units that matter to it, so it doesn't relearn them. On a project with more than one repository, the code map covers every repository, and each unit names the repository it belongs to.
Whether the project's tasks use memory is the project's own Project memory setting, in its Settings tab, section Memory: Default, On or Off. Default follows System Settings. Each task's page shows how memory was used.
A unit moves through statuses: proposed when it is first recorded, accepted once it passes review (an accepted unit tasks can be given reads injectable), flagged when it may be wrong, which stops it being given, stale when the code it describes has moved on, which ranks it lower, retired when it is no longer used, and graduated when it has been promoted into the project's standing guidance. Promotion is automatic: once a unit is trusted, used by several tasks and two weeks old, the nightly memory pass files a hidden Make a runner note permanent task that starts on its own, and a runner moves the note into the repo as a check, a rule or a lesson. The work pushes as the project's creator, or as an Owner or Admin of the org when the project has no creator. If the org has neither, the task waits on the board as a draft instead: Start it or Delete it. Audit > Memory, with the project picked, lists every unit with how many tasks were given it, read it and cited it. Anyone who can edit the project can Retire a unit, or Purge one that holds sensitive data, which deletes it for good. See Audit.