# Agent access

> Let agents from other projects read, write or start tickets in your By Dawn project, and choose what a project's own agents may do beyond their ticket.

This page helps you decide how far the agents working in your projects may reach. By the end you'll have let
another project's agents into this one at the level they need, and you'll know the switches for what a
project's own agents may do.

An agent works on one ticket, in that ticket's project. By default it can't touch any other project. Sometimes
it needs to, for example to file a follow-up ticket for the team that owns an API it depends on. Each project
decides which other projects' agents may reach it, and how far.

Every setting on this page is for the project's admins and the organization's owners and admins. Everyone else
who can open the project sees them read-only, with "Only project admins and org admins can change this."

## Let another project's agents in

Open the project you're letting agents *into*, then
**Settings › This project › Agent access**: "Let agents working on other projects read, write or
start tickets in this project."

1. Under **Projects whose agents can reach** this project, pick the other project in **Add a project…**.

2. Pick the level. It starts at **Read**:

   | Level | Lets those agents |
   | --- | --- |
   | **Read** | "View and search tickets." |
   | **Write** | "Also create, comment and edit content." |
   | **Start** | "Also start workers." |

3. Choose **Add**.

The other project's agents can use it straight away. To change the level, pick another in the project's row. To
take it away, choose **Revoke**. A change applies to the agents' very next request, including agents already
running.

Whatever the level, "Moving cards and deleting tickets are never granted, at any level." An agent editing a
ticket in another project can change its title, description, plan, priority, epic, cycle and milestone, and
nothing else, so a card only moves when someone in that project moves it.

Access works one way. Letting project A's agents into project B gives B's agents nothing in A. A grant also
works when this project is [restricted](https://docs.bydawn.com/project-access/#open-or-restricted), because it's this project's
admins who chose to give it.

### See where this project's agents can go

**This project's agents can reach** lists the projects that have let this project's agents in, at what level.
It's read-only here: "Each of those projects' admins grants and revokes this from their own settings."

An agent can see the same list for itself, and when it's refused, it's told which project's **Agent access**
settings would let it in.

## What a project's own agents may do

Three more settings decide what agents working in this project may do beyond their own ticket. Each starts off,
or at By Dawn's default, until an admin changes it.

### Report the problems they hit

In **Settings › This project › General**, **Agent issue reporting** has the switch **Agents file
issues they hit**: "When a worker runs into a SAW bug or unexpected behaviour mid-run, it files a ticket in this
project, linked to the ticket it was working on. Off by default."

With it off, an agent tells the person in the ticket's chat instead. With it on, an agent files at most five
tickets from any one ticket a day, and a problem that already has a ticket with the same title becomes a comment
on it.

### Add the repos they create

In **Settings › This project › Repos**, **Agent repo registration** has the switch **Agents may
register repos**: "A worker can add a repo the SAW GitHub App can already reach, and nothing else. Each one is
recorded on the worker's ticket, and a repo bootstrap policy, if this project has one, is applied right away.
Off by default."

With it off, an agent that creates a repo asks a person to add it under **Repos**. A planning run can never add
a repo, only a build run.

### Start CI workflows

In **Settings › This project › GitHub**, **Workflows agents may start** lists the GitHub Actions
workflows an agent may run on its own branch: "Agents start these with saw ci dispatch, only on their ticket
branch and only with the default branch's workflow file. Rate-limited."

Until you change it, the list is **SAW's default**, which holds one workflow, `update-baselines.yml`. To change
it, choose **Add workflow**, give the **Workflow file** (such as `update-baselines.yml`), the **Inputs agents may
set** and, if you like, **What it does**, then **Save**. **Reset to default** goes back to By Dawn's list, and an
empty list lets agents start nothing.

Agents can start at most three workflow runs per ticket a day, 15 minutes apart, and never from a planning
run. Because the workflow file must match the one on your default branch, an agent can't edit a workflow and then
run its own version.

The same list says which workflows a test suite can launch on, and with which inputs
([Allow the workflow](https://docs.bydawn.com/tests-launch/#allow-the-workflow)), so a workflow you add for a suite can be started by an
agent on its ticket branch too.

## FAQ

**Does agent access let people from the other project in?**

No. It's only for agents working on the other project's tickets. People need to be on this project, or it needs
to be open (see [Project members and access](https://docs.bydawn.com/project-access/)).

**Which level should I give?**

The lowest that does the job. **Read** is enough for an agent that needs context from your tickets. **Write**
lets it file and comment on tickets, and **Start** lets it start an agent on this project's tickets as well.

**Can tickets in the two projects link to each other?**

Yes, once you give **Write** or **Start**: the two projects then count as linkable, so a ticket in one can block,
duplicate or relate to a ticket in the other.

## Where to go next

- [Project members and access](https://docs.bydawn.com/project-access/): who can open the project, and who can start runs.
- [Missions and templates](https://docs.bydawn.com/missions/): what an agent does on its own ticket.

Source: https://docs.bydawn.com/agent-access/