Agents

Agents are LLM agents driven by a codet server that carry out tasks through Gitea Actions runners. You create an agent once, pick the action it performs and the events that trigger it, and it then analyzes issues and pull requests, writes code, opens and maintains pull requests, reviews changes, or scans repositories for security problems.

Agents are available in Gitea Enterprise v27 and later.

How agents work

• Each agent is bound to its own bot account, and the agent name is the username of that bot. The bot can therefore be mentioned (@name), assigned to an issue or pull request, or requested as a reviewer like any other user.
• Each agent performs one action (analyze, manage pull requests, review code, or security scan) and reacts to the events you select for it. When you need an agent that writes code and another one that reviews it, you create two agents.
• An agent has one of three management scopes: global (site administrator), personal (user), and organization. The scope decides who can create and manage the agent and which repositories it applies to.
• The work is split between two components. The runner changes the code and pushes the branch to the target repository, while Gitea records the result and performs the follow-up actions, such as creating or updating pull requests, commenting, reviewing and merging.
• When an event fires, the agents of the repository owner’s scope and the global agents are both discovered. A global agent can act on every repository of the instance, a personal agent only on repositories owned by that user, and an organization agent only on repositories owned by that organization.
• Agents can hand work to each other, but the relay is bounded: a run counts how many agent runs already answered each other without a human in between, and stops once it reaches the configured Automatic agent rounds.

Prerequisites

Before you create an agent, make sure that:

1. Gitea Actions is enabled and at least one runner is online whose labels match the runner label setting (default ubuntu-latest).
2. At least one agent connection is available, that is, a reachable codet server URL together with its token.
3. The runner can download the codet CLI. For air-gapped deployments, point the download URL at an internal mirror.

Enable and configure agents

Agents are configured from their own section of the administration menu. Open Site Administration > Agents > General. This page stays reachable while agents are disabled, because it carries the switch that enables them.

Setting	Default	Description
Enable Agents	Off	When disabled, the user and organization agent pages are hidden and inaccessible.
Runner label	ubuntu-latest	The runner label used by the generated agent workflows.
Runs per issue and hour	200	How many agent runs one issue or pull request may start within an hour. It stops agents that keep answering each other. An integer between 1 and 1000.
Automatic agent rounds	20	How many agent runs may answer each other without a human in between, for example a coder that pushes and a reviewer that reviews that push. The chain stops at the limit and a new human request starts a fresh one. An integer between 1 and 50.
Automatic retries after a failure	0	How often the same request is started again automatically after its run failed. A run that fails for its own reason fails again on every retry, so 0 turns automatic retries off and leaves the decision to a person. An explicit retry or @agent redo always runs. An integer between 0 and 20.
Failure memory	1 hour	How long the failed runs of a request are counted for the retry limit. A request that shows up later starts with a clean history. An integer between 1 and 168 hours.
Queued request lifetime	24 hours	A request that waited for a running agent is dropped instead of started when it is older than this. An integer between 1 and 168 hours.
Checkout action	actions/checkout@v7	The action the generated workflows use to check out repositories. Use a full internal URL, for example https://gitea.example/actions/checkout@v7, when runners cannot reach external actions.
Automatic CI repairs per commit	3	How often an agent may answer the failing checks of one and the same commit. Reaching the limit means the repairs produced no new commit, so the agent stops and asks for a human. An integer between 1 and 20.
Reminder for blocked requests	168 hours	A coder request that waits for a blocking issue gets one reminder comment after this long. It keeps waiting and starts once the blockers are done. Between 24 and 720 hours.
Expiry of blocked requests	0 (off)	Drops a coder request that waited this long for a blocking issue, with one comment. 0 keeps it waiting forever, otherwise between 24 and 8760 hours.
Codet CLI version	v0.5.1	The codet CLI version the runner installs.
Codet CLI download URL	https://corp.gitea.com/copilot/codet-cli/releases/download/{version}/codet-{version}-{os}-{arch}.tar.gz	Supports the {version}, {os} and {arch} placeholders and can point at an internal mirror. .tar.gz archives are extracted automatically, and raw binaries are also supported.
Codet CLI checksums	Empty	Optional comma separated arch:sha256 list, for example amd64:<sha256>,arm64:<sha256>. When set, the runner verifies the downloaded archive or binary before using it.

These settings are written to the database by the administration UI (dynamic configuration). They are not app.ini options and cannot be set from the configuration file.

Connections, the agent list and the instance-wide agent secrets are the other entries of the same Agents section; they appear once agents are enabled.

Agent connections

A connection describes a codet server: its URL and its token. Once an agent selects a connection, it discovers the available models and working languages from that server through codet-sdk.

Field	Required	Description
Agent connection name	yes	The name shown in the agent form.
Agent connection URL	yes	For example https://codet.example.com.
Agent connection token	yes	Stored encrypted. After saving it can only be replaced, never read again.

Scopes

• Global connections are created by a site administrator under Site Administration > Agents > Connections and can be shared with users and organizations through an access mode.
• Local connections are created by a user or organization on their own settings page. They are visible and usable only within that scope, and a connection inherited from the global scope is read-only there.

Access modes

Only global connections have an access mode, configured separately for users and for organizations.

Access mode	Meaning
Nobody	Keep the connection private and usable only in the global (site administration) scope.
All	Share the connection with every user or organization of that scope.
Listed	Allow only the users, user groups or organizations in the access list to use it.

An access list can contain three kinds of principal: users, user groups and organizations. A user group is matched by its effective members, including the members inherited through nested user groups.

Model and language discovery

• The model selector of the agent form is loaded from the selected connection through codet-sdk; the list is no longer maintained by hand.
• The models and languages of a connection are cached (for five minutes on success and thirty seconds on failure). The cache is invalidated immediately when a connection is created, updated or deleted.
• When discovery fails the form shows a notice and lets you enter a model name manually. The language list then falls back to a built-in list (Auto, English, Simplified Chinese, Traditional Chinese).

Create and edit an agent

Field	Description
Name	Required, at most 40 characters. It is also used as the bot username, so it has to be a valid and globally unique Gitea username.
Agent connection	Required. The save button stays disabled while no connection is available, with a notice to create one first.
Model	Required. The list is loaded from the selected connection through codet-sdk; when loading fails you can enter a name manually.
Description	Optional. It is also stored as the description of the bot account.
Working language	The language the agent uses for reviews, comments, and pull request titles and descriptions. Auto (follow the conversation) follows the language of the triggering issue, pull request or comment, and falls back to English when it cannot be detected. Code, identifiers, commit SHAs and command output are left unchanged.
System prompt	Not edited in the form, see Prompt, skills and MCP. The form only shows a link to the .agent repository of the agent.
Avatar	Optional. Pick one of the built-in logos that matches what the agent does, let the logo follow the selected action automatically, or upload your own image (SVG is not supported).
Action and trigger events	The single action the agent performs and the events that trigger it, see Actions and trigger events.

The agent list labels every agent with a role derived from its action (Plan, Code, Review or Security) and shows its model and working language.

Creating an agent automatically:

1. creates a bot account (activated, with a private email address and the right to create organizations disabled), and
2. stores the action and trigger-event configuration.

In addition, every triggered run (except the scheduled scan) makes sure the bot is added to the target repository as a write collaborator, so what the agent does inside the repository stays constrained by its real permissions.

Every scope can create several agents, and each of them can be edited and deleted on its own. Deleting an agent also removes its bot account, its command list, and long-lived credentials that older versions may have left behind.

Actions and trigger events

Each agent performs exactly one action, and the action cannot be changed after the agent is created; its settings and trigger events stay editable. The form lists the actions with the events each one understands: pick the action, then the events that should trigger it. Only the events of the selected action can be chosen, and at least one event is required.

Actions

Action	Description	Trigger events
Analyze	Analyze the request and decide by itself whether to reply with the analysis or to split it into subtask issues, each starting its own agent session.	Issue created, Assigned, Mentioned, Replied, Default branch CI failed
Manage Pull Request	Create the initial pull request when needed, then keep updating and maintaining that pull request, including resolving related review-comment conversations. It can also fix security findings and repair a failing default branch.	Issue created, Assigned, Mentioned, Replied, Review submitted, Review comment posted, New code scanning finding, Requested on a finding, Confirmed code scanning finding, Default branch CI failed
Review Code	Review the latest code changes, verify whether the requested fixes are complete, and submit an updated review through Gitea.	Pull request created, Review requested, Assigned, Mentioned
Security Scan	Scan repository code and history for high-confidence security findings and report the actionable ones as issues or on the repository security page. It can also judge the findings of every scanner for false positives.	Scheduled security scan, Push to the default branch, Pull request created, Review requested, Assigned, Mentioned, New code scanning finding, Requested on a finding

Notes:

• Resolving review conversations is not a separate action; it is part of Manage Pull Request.
• Merging is not a separate action either. It is enabled by the Allow merge after checks and approvals pass option of Review Code; that option only permits the merge, which still has to satisfy the required checks and branch protection approvals.

Trigger events

Event	When it fires
All events	A virtual event: the action handles every event it supports in the background.
Assigned	The agent bot user is assigned to an issue or pull request.
Mentioned	The agent bot user is mentioned in an issue or pull request comment.
Replied	A new reply is posted on an issue or pull request currently assigned to the agent.
Review requested	The agent bot user is requested as a reviewer on a pull request.
Review submitted	A pull request receives a submitted review and the agent is assigned to follow up on the pull request.
Review comment posted	A pull request receives a new inline review comment and the agent is assigned to follow up on the pull request.
Issue created	A new issue is created in a repository owned by the current user or organization.
Pull request created	A new pull request is created in a repository owned by the current user or organization.
Scheduled security scan	Scans every repository where the agent bot user has issue read access, on a recurring schedule.
Push to the default branch	Commits land on the default branch; only the changed code is scanned.
New code scanning finding	A scan stores a new finding (of any scanner) for the default branch.
Requested on a finding	A user with security write access asks this agent on the page of a finding.
Confirmed code scanning finding	A triage agent confirmed a high or critical finding as real.
Default branch CI failed	A workflow run on the default branch fails after the previous run of that workflow passed. The agent diagnoses it (Analyze) or opens a fix pull request (Manage Pull Request).

Notes:

• Every action supports only a subset of the events above. The form does not offer unsupported combinations, saving rejects them, and the run filters them out. All events therefore only means “every event the action supports”.
• The selected action needs at least one trigger event, otherwise saving fails.

Action settings

Action	Setting	Description
Manage Pull Request	Request Agent reviews for this PR	Optional. When the managed pull request is created or updated, one or more selected agents are requested as reviewers automatically.
Manage Pull Request	Request user reviews for this PR	Optional. One or more users are requested as reviewers when the managed pull request is created or updated. Users and agents can be combined.
Manage Pull Request	Auto-maintain failing CI for this PR	Optional. When enabled, later failing workflow runs on this managed pull request trigger the agent again to try to fix the CI.
Manage Pull Request	PR auto-maintenance max retries	Default 5. The maximum number of automatic CI-fix attempts; an integer not smaller than 1.
Manage Pull Request	Keep this PR up to date with its base branch	Optional. Merges the base branch into the head branch as soon as it falls behind. It merges, never rebases or force pushes, so nobody else’s commits are rewritten.
Manage Pull Request	Resolve merge conflicts of this PR automatically	Optional. A conflicting pull request starts a run that merges the base branch and resolves the conflicts; a conflict it cannot resolve is handed back with a comment.
Manage Pull Request	Conflict resolution max retries	Default 3. Attempts against the same state of the base branch; a new commit on the base branch resets the count.
Manage Pull Request	Delete the head branch after the PR is merged	Optional. A branch that another open pull request still uses is kept.
Manage Pull Request	Code push mode	How the agent proposes its work. Auto (default) pushes a branch into the repository when the bot may write there and falls back to AGit otherwise. Branch always pushes a branch. AGit leaves no branch in the repository and works with read access alone. Fork works in a fork of the agent account. Commit into the target branch opens no pull request; use it only for repositories worked on without review.
Manage Pull Request	Split large requests into a delivery plan	Optional. The agent may decide that a request does not fit one reviewable pull request and submit a delivery plan.
Manage Pull Request	Delivery plan approval	When a plan needs a person’s approval before its first step starts: always, only for a plan reaching into another repository or with more than 3 steps, only for a plan that moves a private repository into a wider one, or never.
Manage Pull Request	Fix security findings	Opens a fix pull request for a finding of any scanner when a user with security write access asks on the finding page.
Manage Pull Request	Fix new findings automatically	Opens a fix pull request for every new finding of the default branch from a least severity on, with Open fix pull requests at most pausing automatic fixes while that many are open.
Manage Pull Request	Wait for false positive detection	Findings of other scanners are fixed automatically only after a triage agent confirmed them. Findings reported by the security scan agent are fixed right away.
Review Code	Allow merge after checks and approvals pass	See the note above.
Analyze / Security Scan	Assign the created issues to agents	Assign every new issue to the selected agents, so each one starts its own agent session. When no other agent exists in the scope yet, the selector says so but is still shown so the capability is discoverable.
Analyze / Security Scan	Assign the created issues to users	Optional. Also assign every generated issue to these users. A user assignment does not start an agent session, it gives the work an owner.
Security Scan	Scan interval	One of 6h, 12h, 24h, 72h, 168h; default 24h. It only applies when the Scheduled security scan event is selected. Clearing that event turns the recurring scan off and the interval is ignored.
Security Scan	Report findings as	Where a scan of the whole repository reports: a new issue for every finding or findings on the repository security page. A scan of a pull request always reports on that pull request.
Security Scan	Detect false positives	Judges the findings of every scanner (code scanning, dependencies, secrets) as real or false positive and records the verdict on the finding. Users with security write access can always ask for it on the finding page.
Security Scan	Judge new findings automatically	Judges every new default branch finding from a least severity on (critical, high and above, moderate and above, low and above).
Security Scan	Dismiss high confidence false positives	A high confidence false positive verdict dismisses the finding. Needs security write access for the agent account; the finding can be reopened like any dismissal.
Security Scan	Confidence level	One of medium (medium and above), high (high only), low (low and above); default medium.

Access control

Each agent can be configured individually with “who can command it”. Open the agent list and choose Access, or use the Access button on the edit page.

Who can command	Meaning
Anyone with write access to the repository (default)	Write access to the target repository is enough to command the agent.
Only the owner and the listed principals	In addition to write access to the repository, the principal has to match the command list.
Only the owner	Only the owner of the agent can command it.

The command list accepts users, organization teams and user groups, resolved by name and stored. The list only narrows access:

• commanding an agent always requires write access to the target repository;
• what the agent itself may do still depends on what its bot account may do in that repository.

Agent secrets

An agent run can read secrets, for example to authenticate to an MCP server. Reference them as ${{ secrets.NAME }} in the MCP declaration.

Scopes and inheritance

Scope	Where to manage it	Available to
All agents (instance)	Site Administration > Agents > Secrets	Every agent of this Gitea instance.
Owner	User Settings > Agents > Secrets and Organization Settings > Agents > Secrets	Every agent owned by that user or organization.
Repository	Repository > Settings > Agent secrets	Every agent running for that repository.
Agent	The Secrets button on the agent edit page	That agent only.

The inheritance order, from broad to narrow, is instance, owner, repository, agent. A secret with the same name is overridden by the more specific scope, and the agent scope wins. Every page also lists the secrets inherited from the wider scopes, so it is visible what an agent really sees.

Limits

• Values are stored encrypted and are write-only: after saving they can only be replaced, and they are masked in the run log.
• The .gitea/agents/mcp.json of the target repository can override the MCP configuration of the agent configuration repository. The secret names it references are resolved through the scopes above.

Prompt, skills and MCP

The system prompt, the skills and the MCP servers of an agent are not edited in the agent form. They are configured in a Git repository owned by the agent bot account, so every change is versioned, reviewable and reproducible: each run records the configuration commit it used, and the form only links to the repository.

Agent configuration repository <agent-bot>/.agent

The configuration of an agent lives in the private .agent repository of its own bot account. The run token never gets write access to it, so an agent cannot rewrite its own instructions.

Path	Purpose
system-prompt.md	The system prompt of the agent.
skills/<name>/SKILL.md	A skill the agent can load, following the Agent Skills layout: one directory per skill, and SKILL.md starts with YAML frontmatter.
mcp.json	The MCP servers the agent may use, using the mcpServers structure shared by Claude Desktop, Cursor and VS Code. Secrets are never stored here, only referenced as ${{ secrets.NAME }}.
settings.yml	Selects which of the declared skills and MCP servers are enabled.

Example settings.yml:

version: v1
skills:
  - code-review
  - security-audit
# empty means every server declared in mcp.json is enabled
mcp:
  - internal-docs

Target repository .gitea/agents/<agent>.yml

A target repository can add its own skills, disable inherited ones, use its own MCP declaration and append a prompt section for itself. The file name is the agent name:

# .gitea/agents/<agent name>.yml
# add skills of the repository
skills:
  - repo-conventions
# turn off skills inherited from the agent
disable_skills:
  - security-audit
# choose which MCP declaration to use
mcp:
  - repo-tools
# append to the prompt; the agent prompt cannot be replaced
prompt_append: |
  This repository uses Conventional Commits.

Path	Purpose
.gitea/agents/<agent>.yml	Repository-level agent configuration, supporting skills, disable_skills, mcp and prompt_append.
.gitea/agents/skills/<name>/SKILL.md	A skill of the repository.
.gitea/agents/mcp.json	The MCP declaration of the repository.

Limits and fault tolerance:

• A repository can only append to the prompt; it cannot replace the prompt of the agent.
• A missing or broken configuration does not fail the run; the inline configuration of the agent form is still used as a fallback.

How runs and sessions work

1. An event fires. Gitea finds the agents that handle it (the repository owner scope plus the global scope) and creates a session for each of them.
2. Gitea generates a workflow for the run and starts an Actions run on a runner that matches the configured runner label.
3. The runner checks out the code, installs the codet CLI, prepares the prompt, skills and MCP configuration, and runs the agent.
4. The agent edits the code and pushes its branches. Gitea applies the results as the follow-up actions of the session, such as creating or updating pull requests, commenting, reviewing and merging, and streams the progress into the issue or pull request timeline.

Credentials

• A run started by a person receives a session token of the agent bot. It lives exactly as long as the Actions task of that run, nothing is stored or has to be revoked, and disabling Agents ends every token at once. An agent bot has no standing credential: personal access tokens and OAuth2 tokens of an agent bot are refused.
• The effective permission of every request is the intersection of the bot’s permission, the permission of the person who triggered the run, and the token scope (repository, issue and package write; no administration or settings). The agent can therefore read related repositories, but never does what the person behind the run could not do.
• Searches and listings during a run only surface repositories that both the bot and the triggering person can see.
• The .agent configuration repository is read-only for the run, so an agent cannot rewrite its own instructions.
• A run nobody started (for example the scheduled scan) has no session token; it is bounded by the agent account alone.
• A write-heavy looping run is stopped after 500 write requests.

Sessions

• A session bundles the codet conversation with the Gitea context (repository, issue or pull request, and the user who triggered it).
• Follow-up runs on the same issue continue the same codet conversation. Repository-level runs (such as the scheduled scan) and runs while a session is still working open a new session.
• Every follow-up action is authorized with the intersection of the triggering user’s permissions and the agent’s permissions.
• If an agent is already working, a new request waits as a queued request and starts when the current run finishes. A queued request older than the Queued request lifetime setting is dropped instead of started.
• A session is canceled automatically when its pull request is merged or closed, when its issue is closed, or when a newer request supersedes it. It can also be canceled or retried by a user.
• The issue or pull request timeline shows a session card with its progress and streams the output of a running session.
• Comment @agent stop (also cancel, abort) to stop a running agent, and @agent redo (also restart, rerun, retry) to discard its current run and start over.
• The verbosity of the run log is controlled by the repository or organization Actions variable AGENT_LOG_EVENTS: summary (default), verbose or off.

Built-in gitea MCP server

Every run gets a built-in MCP server named gitea, served by Gitea itself for that session. It gives the agent read tools such as failed jobs and job logs, pull request diffs and checks, review threads, issue comments and references, code search and repository context, plus checks like push rule validation. The name gitea* is reserved, so servers declared in mcp.json cannot use it. Tool calls are limited to the session and authorized like the rest of the run.

Delivery plans

When Split large requests into a delivery plan is enabled for a Manage Pull Request agent, the agent can answer a large request with a plan of up to 12 steps instead of one oversized pull request. Gitea schedules one step at a time, each step with its own pull request.

• A step that depends on an earlier one is based on that step’s branch, and the pull requests are shown as a stack (“PR 2 of 3 in stack”) on the pull request pages.
• Depending on Delivery plan approval, the plan waits for a person to Approve it. Steps may target other repositories.
• A mention or reply on the source issue while a plan is in progress asks the agent to revise the plan instead of starting a separate pull request.
• When all steps are merged, a read-only run verifies that the request is complete (verifying), then the plan is done.
• The plan card offers Pause plan, Resume plan, Cancel plan, Mark done and, for a blocked step, Retry. A step is blocked, for example, when permission is missing, its run budget is exhausted or its parent pull request was closed unmerged.

Troubleshooting

Symptom	What to check
The save button is disabled or asks for a connection	The scope has no usable and fully configured (URL and token both set) agent connection. Create one first, or ask an administrator to share a global connection.
The model list fails to load	Check that the URL and token of the connection are valid and that the server is reachable. You can also enter a model name manually.
Creating an agent reports that the name is unavailable	The agent name is the bot username, so it has to be a valid and globally unique username, including not colliding with an existing user.
Nothing runs when an event fires	Check in order: Agents is enabled, the agent belongs to the scope of the repository owner or to the global scope, the agent selects the action with the right events, the commanding user has write access to the repository, and a runner is online for the runner label.
An agent review is expected but does not trigger	Check that the Review requested or Assigned event is bound to the Review Code action. Requesting an agent as a reviewer also assigns it.
The merge does not happen	A merge requires all required checks and branch protection approvals. When the branch is behind, update it first, then wait for the checks and merge.
The pages return 404 after agents are disabled	This is expected: after disabling Agents the user and organization agent pages are hidden and inaccessible.

Availability

Agents were introduced in Gitea Enterprise v27.