How projects work

A project is one repository that Jaah works on. Every task belongs to one project, and every runner works in a copy of that project's code. The project's settings decide where that work happens, how a runner checks and delivers it, 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	One repository, with the settings Jaah needs to work on it.
Repo URL	The repository's address on your forge.
Worktree	A working copy of the project on one node. A task runs in one.
Integration branch	The branch runners open pull requests into.
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 worktree's settings when a task claims it.
Feature	A folder for related tasks inside a project.

What a project's settings decide

A project's settings are grouped in tabs, as the console names them:

• General — its Name, its Repo URL, and Dispatch enabled: whether runners are sent to work on its tasks at all.
• Access — who may use the project, and with which role. See Who may use it.
• Governance — how runners work in the repository: the Integration branch, an optional Branch prefix, Push enabled, the gate commands, the commands that start and stop the project's local stack, and Agent instructions given to every agent that works on it.
• Worktrees — how many working copies the project may have, and on which nodes.
• Environment — the variables its tasks get. See Environment and credentials.
• Advanced — the Default model, who answers questions inside an epic (Business analyst and Architect), the Jira credential, the Tech stack and Notes.

Commands and agent instructions are readable by anyone who can view the project, so a secret never goes there.

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. The project's Business analyst and Architect answer the questions they raise. See How epics and features work.
• Worktrees and nodes. A project runs on the nodes you assign it, in worktree slots on each. 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 on the project's Access tab, 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 on the Access tab names its Source: Direct for a grant on this project, Via a group, or Inherited 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, on the Environment tab. 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 credential to a project and How credentials work.