Projects on a server

A server project is a git repository the server clones (or a checkout it already has) plus its WORKFLOW.md. There are two ways to add one: list it in harnessd.yaml, or, as an admin, add it from the Mac app. Either way it runs exactly like a local project, and the app shows it with the same screens.

Both survive restarts. If a name appears in both, harnessd.yaml wins.

Add a project in harnessd.yaml#

projects:
  - name: shop-storefront
    repo: git@github.com:your-org/shop-storefront.git   # cloned into data_dir/repos/shop-storefront
    workflow: WORKFLOW.md
    auto_start: true
    secrets_file: /etc/harness/projects/shop-storefront.env   # optional, 0600
  - name: shop-api
    path: /srv/checkouts/shop-api                         # an existing checkout, used in place

Restart the server (sudo systemctl restart harnessd). With repo:, the server clones the repository once into data_dir/repos/<name> and reuses that clone while its origin is the same repository. If the folder holds a clone of a different repository, the project fails to load with a message saying so.

Add a project from the app#

1. Open Add Project under the server

   Sign in to the server as an admin. Under the server in the sidebar, click Add Project.

2. Fill in the project
   • Name: 1 to 64 characters: letters, digits, spaces, dots, dashes and underscores. It must be unique on the server.
   • Repository: an https:// URL or an SSH URL (git@github.com:your-org/repo.git or ssh://…). Local paths, file://, plain http://, git's ext:: transports and credentials in the URL are refused.
   • Workflow file: its path inside the repository, default WORKFLOW.md.
   • Start the orchestrator on the server now.
3. Enter a code and add it

   Type a code from your authenticator and press Add Project. The server clones the repository, checks that the workflow file exists and parses, saves the project, and starts it if you asked.

The repository must already contain a committed and pushed WORKFLOW.md: the server clones what's on the remote. Create one with the app's local Add Project first if you need to.

Repository access#

The server clones with only the https and ssh transports allowed, with no submodules and with git hooks and fsmonitor disabled. It needs read access:

• SSH URLs: a deploy key for the harness user.
• https URLs: HARNESS_GITHUB_TOKEN (GitHub) or HARNESS_GITLAB_TOKEN (GitLab) in the server's variables (secrets.env, or Server Settings → Environment). The token is handed to git by a credential helper that reads the environment, never in the command line or on disk.

To push task branches and open pull requests, the same credentials need write access.

Move a local project to a server#

Move to Server hands a project from your Mac to a server, with its variables, test logins and open tasks.

1. Open Move to Server

   Right-click the local project in the sidebar and choose Move to Server → <server>…. The menu appears when you're signed in to at least one server as an admin.

2. Check the prefilled values

   The name, the repository's origin URL and the workflow path are filled in. The Repository section checks:

   • origin is a URL the server can clone;
   • the workflow file is committed;
   • there are no uncommitted changes (the server gets only what's pushed);
   • the branch is pushed (it has an upstream and no unpushed commits).
3. Choose what moves
   • Copy its variables and test logins to the server: the project's environment and saved logins, stored write-only on the server.
   • Move its open tasks from the local board: only for projects on the built-in board (tracker: local). Other trackers keep their tasks where they are, and the server uses the same tracker.
   • Stop it on this Mac afterwards, so the project doesn't run in two places.
4. Enter one code and move it

   One authenticator code covers everything. The app shows progress (Cloning on <server>…, Moving tasks…) and reports any tasks that couldn't be created on the server; those stay on the local board.

Remove a project added from the app#

Right-click the server project in the sidebar and choose Remove from Server…, then enter a code. The server:

• stops the project's orchestrator;
• deletes its variables and test logins on the server;
• keeps its clone in data_dir/repos/<name>, with any saved task branches, so adding it again under the same name picks it up.

Projects listed in harnessd.yaml can't be removed from the app (409 defined_in_config); remove them from the file.

Project secrets#

Each server project can have its own variables, on top of the server's:

• projects[].secrets_file in harnessd.yaml (mode 0600);
• or, as an admin, the project's … menu → Project Secrets & Test Logins… in the app.

See Secrets.

See also#

• Server projects in the app
• harnessd.yaml reference
• HTTP API: projects