Fullsend

Appearance

157. Require a jira authorization entry when the jira-poll driver runs ​

Date: 2026-11-02

Status ​

Accepted

Supersedes the opt-in rule of ADR 0153; the rest of that ADR stands. See Context.

Context ​

Until recently, Fullsend had exactly one way to decide who may use the Jira poller to run agents: the actor's Jira project role, matched by name in the project's role roster. That way is bad on two counts. Reading the roster needs the Administer Projects permission, so a bot that only watches a project had to be one of its administrators (#8401). And the match is on role names, so a project whose roles are not literally called Administrators or Developers downgrades everyone to read and ignores their slash commands.

#8892 (ADR 0153) added better alternatives. A repository can list, in its .fullsend/config.yaml, the Jira groups and accounts allowed to run agents, and it can let Jira's own Edit Issues permission vouch for anyone who adds a label. To keep that change non-breaking, the old way stayed the default: a repository that configures nothing still gets project roles, and still needs an administrator bot. So Fullsend now has a bad default, and a silent one. A repository cannot tell "I chose project roles" from "I configured nothing", because they are the same config file, and a team that skips the authorization step learns which mode it is in from a 401 in the poll log, by granting the bot a role it should not hold, or by never seeing a dispatch. The review of #8892 raised this (comment), and #9004 proposed the decision recorded here.

This ADR deprecates and removes that default. It does not put a different default in its place: a repository that runs the poller must say which way it uses, and the old way stays available as an explicit choice.

In Fullsend terms, the poller is the jira-poll input driver (ADR 0063), and its trust decision is the authorization contract every dispatch path uses (ADR 0054), under the least-privilege principle of the security threat model. At d7394b881b4e68aa78976ee82ffb226cfbcb42c6, jiraPollAuthorization (internal/cli/poll.go) leaves Authorization.Configured false when .fullsend/config.yaml has no jira provider, and roleSourceFor (internal/jirapoll/auth.go) then selects the project role roster (GET /rest/api/3/project/<KEY>/role) as the role source for every event.

This ADR aims to make a repository's Jira authorization source an explicit choice whenever the jira-poll driver runs, without changing who may trigger agents under any existing configuration.

Options ​

  • Keep the provider opt-in. No change. The admin-only default stays invisible, and the least-privilege gain of ADR 0153 reaches only repositories that happen to read the guide's authorization step.
  • Flip the default. With no entry, label-added events would be authorized by Jira's Edit Issues permission (labels: jira_editors), as they are once an entry exists. No repository needs a config change, but in a project where Edit Issues is granted more widely than the Developers role this silently widens who can trigger agents, under a repository that did nothing.
  • Require the entry (chosen). A missing entry fails loudly at poller start, and the fix is a two-line entry that reproduces today's behaviour exactly. Behaviour changes only for a repository that edits its config.

Within the chosen option, the deprecation warning is logged by the poller, not reported by fullsend lint. At the SHA above, runLint (internal/cli/lint.go) reads config.yaml and composes the harnesses; it never sees the scheduled workflow or pipeline that starts the driver, so it cannot tell whether a repository polls Jira. A lint finding would fire for every repository with no jira entry, most of which never poll Jira, or would have to guess from workflow file names. The poller knows for certain, so its warning is right every time it appears.

Decision ​

We require a jira entry under authorization: whenever the jira-poll input driver runs, so that project-role authorization, and the Administer Projects permission it needs, is a choice a repository writes down rather than a default it falls into.

The requirement arrives in two steps, each in its own release:

  1. Warning (#9005). When the driver starts with no jira entry, the poller logs one warning before the first poll cycle. It says that running without an entry is deprecated and will become an error, that the current mode authorizes every event through project roles, and it prints the two-line entry below. The release notes announce the deprecation. Nothing else changes.
  2. Removal (#9006). The poller refuses to start without a jira entry, before any Jira call, with a message that names the requirement and prints the same two-line entry. This is a breaking change and is marked as one.

The migration for a repository that wants today's behaviour is the entry that ADR 0153 already defines for it:

yaml
authorization:
  - provider: jira
    labels: project_roles

The meaning of an entry does not change. Lists, labels: values and roster loading stay as ADR 0153 decided them, and the two-line entry resolves every event through the project role roster exactly as no entry does today.

Forge scope ​

This decision applies to the jira-poll input driver under both of its targets, GitHub Actions (--target-forge github) and GitLab CI (--target-forge gitlab), which build the poller's options through the same function. GitHub, GitLab and Forgejo event authorization is unchanged: authorization: stays optional for a repository that does not run the driver, and the owners_file provider is untouched.

Consequences ​

  • Every Jira poller configuration states where its actor roles come from, so the admin-only path is visible in config review and in the guide's setup steps, instead of being the mode a repository is in by omission.
  • A repository that keeps project roles adds two lines; one that never added an entry sees a warning for at least one release, then a start failure whose message contains the fix.
  • The removal should follow a deprecation period. The proposal is at least three months after the first release whose notes announce the deprecation; the interval is settled on #9006 before the removal is scheduled.
  • Jira poller setups that Fullsend generates, such as the repos install option proposed in #8906, must write a jira entry.
  • The user guide, the config references, the authorization normative specs and docs/architecture.md describe the entry as deprecated-when-missing from the warning release and as required from the removal release. The deprecation is listed on the deprecations tracker #7155 until it is removed.