Deploy

Agents are YAML files in your repository. Push agents/*.yaml to the default branch to register an agent, or use the dashboard to open the pull request for you.

The deployment model

Ellipsis treats GitHub as the source of truth for agents.

Action	What Ellipsis does
Add `agents/name.yaml` or `agents/name.yml`	Parses the file, validates it, and creates a registered agent.
Edit the file	Updates the existing agent synced from that repository, path, and branch.
Rename or move the file	Keeps the same agent when the content is unchanged, so its identity and history carry over. A move combined with content edits is a delete plus a create.
Delete the file	Soft-deletes the registered agent and removes any cron schedules for it.
Push an invalid file	Records the sync error. If the agent already existed, the last good config remains in place.

The sync runs on pushes to the repository default branch. The canonical directory is agents/; .agents/, ellipsis/, and .ellipsis/ are also accepted, as is any subdirectory under them (for example .ellipsis/agents/). When push file lists are unreliable, such as a forced push or a push with a truncated commit list, Ellipsis reconciles every supported agent config directory instead of trusting the webhook's changed paths.

The default branch is the source of truth

Registered agents are always synced from the default branch. The agents that appear in the dashboard, run on cron schedules, and answer mentions come from the file on the default branch, never from a pull request branch. A pull request branch never registers, edits, or deletes an agent.

A run that has already started keeps the agent it began with. Each run records a snapshot of the agent config it ran, so editing or deleting the file does not change an in-flight run.

Testing config changes in a pull request

On private repositories, Ellipsis previews agent config changes on the pull request that makes them, so you can watch an edited or new agent run before you merge. When a pull request adds, edits, or removes an agent config, runs triggered by that pull request use the pull request's version of the config: the agents you would have once it merges.

The preview is scoped to the pull request and is never registered. It does not create or change cron schedules, it does not appear in the dashboard, and a preview run is not attributed to the stored agent. An edit that fails to parse or validate is skipped for the pull request instead of falling back to the previous version, so a broken change shows up as the agent not running rather than as the old config running.

This applies only to pull requests opened from a branch in the same repository, by an author with write access. Public repositories, pull requests from forks, and pull requests from authors without write access always use the agent as it exists on the default branch, and the change takes effect on the next sync after merge.

Deleting and re-creating an agent

Deleting the file soft-deletes the agent: future cron, react, and mention runs stop, the agent's cron schedules are removed, and it disappears from the dashboard. Nothing about past runs changes. Their config snapshots and history stay intact, so completed runs still render exactly as they did before.

Re-adding a file at the same path revives the same agent rather than creating a new one. It keeps its original identity, so its run history reconnects and its cron schedules come back. This holds even if you restore the exact same file content, for example by reverting the delete commit.

Moving or renaming a file keeps the same agent when its content is unchanged. Ellipsis matches the removed and added files by content and repaths the existing agent, so its identity, run history, and cron schedules carry over. If you also change the content in the same push, or the move is ambiguous because two files share identical content, Ellipsis falls back to a delete plus a create: the old agent stays soft-deleted and the new path registers as a brand-new agent.

Create from the dashboard

Use the dashboard to prototype an agent when you are still iterating on the prompt and schedule. When you create the agent, Ellipsis opens a pull request that adds the YAML file under agents/. The agent stays pending until that pull request merges.

After the pull request merges, the file is the source of truth. Edit the YAML to change the agent, or delete it to remove the agent.

Create by pushing a file

Create a file under agents/. See the Agent config reference for the full agent config source and every supported field, default, and limit.

Commit and push it:

git add agents/daily-issue-triage.yaml
git commit -m "Add daily issue triage agent"
git push

When the push lands on the default branch, Ellipsis registers the agent and starts any cron schedules declared in the file.