Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Work sources (governor.work_source)

work_source chooses where Hive reads tasks. Most hives need no change: the default is GitHub Issues on their configured repositories. Reading tasks from a tracker does not grant agents permission to change code or merge it; ACMM, lane permissions, and merge gates still apply.

Choose and configure a source

Prerequisites: a running hive, access to change its settings, a GitHub repository agents can work on, and read credentials for the chosen tracker. Writing review follow-ups can require additional permissions documented below.

Hosted and dashboard-managed hives configure the block from Settings → Work source. Self-hosted operators can also set governor.work_source in their effective hive.yaml; on Kubernetes, a ConfigMap is only the first-boot seed (config layering).

Confirm that work is being read

1. Save your source and credentials using the chosen source’s instructions. Never commit literal credentials; use the documented environment references.
2. Pick a known open task that matches the configured repository, team/project, state/query, and hold-label filters.
3. Wait for a governor enumeration cycle and check the dashboard work list and logs for that task. A listed task is confirmation of reading, not a promise that an agent is eligible to act on it.
4. An empty list can mean no matching tasks or filtered/held work. Check the query and mappings. Authentication, TLS, or API errors in logs mean the source failed; they are not evidence of an empty backlog. Correct the credentials/connection and check the next cycle.

Optional run stages and Wavefront append work to the primary source. They are advanced integrations, not extra first-run steps.

Source reference

The four primary type values are github, github_projects, linear, and jira. Absent or type: "" behaves exactly like existing hives with no work_source block — GitHub Issues on the configured project.repos (pkg/config/config.go:1336-1348, pkg/worksource/factory.go:15-89).

This page documents all four. Linear has its own deeper guide — Linear agent integration — for the two-way agent-session integration (webhooks, session acknowledgement, writing back to Linear); this page covers only the read side (work_source.linear) for parity with the other three.

Jira Data Center supports an internal CA bundle (the certificates used to trust your server) and optional client-certificate authentication in current v5 code. See TLS for Data Center.

Trackers and forges

work_source picks the tracker: where work items are read from. The forge — where the repositories, branches and change requests live — is a separate setting, project.forge, which a project.repo_policies[].forge entry can override for one repository:

The GitLab and Gitea/Forgejo adapters read repos, issues and change requests, and can comment, label and set the hold gate; GitLab can also merge. A hive still cannot run on them, because enumeration, the merge gate and the agents’ gh path are GitHub-only. Every work source above therefore still targets a GitHub repository. See Forges: GitLab, Gitea and Forgejo for the operation list and what runs through the adapters today, and Forge setup for the reasons.

Run stages (run_stages: true)

governor:
  work_source:
    type: github
    run_stages: true

Wavefront migration graph (wavefront.enabled: true)

governor:
  work_source:
    type: github
    wavefront:
      enabled: true
      path: /data/wavefront/graph.json     # or url: https://wavefront.example/graph.json
      repo: acme/crust                     # owner/name every node key is scoped to
      receipts_dir: /data/wavefront/receipts

type: github (default)

No config needed. Enumerates open issues on project.repos via the existing GitHub client (pkg/worksource/factory.go:17-18). This is the only source type most hives ever need.

type: github_projects — GitHub Projects (Projects v2)

Reads items from a GitHub Projects v2 board via the GraphQL API (pkg/worksource/github_projects.go). Use this when work is tracked on a project board rather than as bare repo issues.

governor:
  work_source:
    type: github_projects
    github_projects:
      project_number: 7            # required — the number in the project URL
      org: your-org                # optional — falls back to project.org
      states: [Todo, In Progress]  # optional — Status field values to include; empty = all
      priority_field: Priority     # optional — name of a single-select priority field
      iteration_field: Sprint      # optional — name of an iteration field; only current-iteration items are returned when set
      default_repo: your-org/repo  # optional — used when an item's own repo can't be determined

Config fields (GitHubProjectsSourceConfig, pkg/config/config.go:1696-1703):

Credentials. The adapter authenticates with the same GitHub token the hive already uses for issues/PRs (ghToken passed into worksource.FromConfig, pkg/worksource/factory.go:15,23) — there is no separate token field in github_projects:. That token needs the read:project scope in addition to whatever repo scopes it already carries; a classic PAT with only repo cannot read a Projects v2 board and the GraphQL call fails with a GraphQL-level authorization error surfaced as worksource/github_projects: graphql error: ... (github_projects.go:330-332).

Cadence and webhooks (#13379). The GraphQL listing is not made on every eval cycle. It runs on a reconcile cadence (githubProjectsReconcileInterval, 15 minutes, pkg/worksource/github_projects_cache.go) and the result is held in a process-wide per-board cache; cycles in between read the cache, with the status, iteration and priority filters applied at read time so the current-iteration window moves without a re-list. Subscribing the App or organization webhook to projects_v2_item keeps the cache current between listings: each created/edited/deleted/reordered/archived/ restored/converted delivery is a hint that re-reads that one item by node id (one GraphQL call; deleted removes it with no call) and patches the cache (worksource.ApplyProjectsV2ItemEvent). The delivery’s project_node_id must match a board that has listed at least once; anything else waits for the next listing. Writes (AddIssueToColumn, the review backlog destination) are unchanged and still go straight to GitHub.

Failure mode. A wrong project_number or an org the token can’t see returns a GraphQL error on the first listing, logged but not fatal — the hive keeps running with an empty work-item list from this source. When a later re-list fails, the previous listing is served (and the entry marked stale) for up to two hours before the error surfaces again.

type: linear

governor:
  work_source:
    type: linear
    linear:
      api_key: ${LINEAR_API_KEY}
      hold_labels: [hold]              # additive; GitHub's hold defaults still apply
      teams:
        - key: ENG
          repo: your-org/default-repo
          states: [Todo, In Progress]
          cycles: current              # optional; only issues in the active cycle
          projects:                    # optional; when present, only these projects enumerate
            - name: Platform
              repo: your-org/platform
      assigned_only: true              # optional; requires a connected Linear agent app
      session_agent: scanner           # which hive agent takes Linear agent sessions

A team’s (or project’s) repo also gates review scope-contract recognition: a Linear key found in a PR’s body, title, or branch is treated as its scope contract only when that key maps to the PR’s repository.

The hive then reads that issue read-only through this work source when it plans the review kick — identifier, title, state, description and the last few comments, capped at 10 KiB with a truncation note — and inlines it into the kick as untrusted data from the issue tracker, so reviewers judge against the acceptance criteria without ever holding the Linear key. The text is cached per issue and refetched only when its updatedAt changes (checked at most every five minutes). If a refresh fails, the last known-good text for that issue is reused (and not retried until the next recheck); only an issue never fetched before makes the kick name the identifier it could not fetch.

api_key and at least one teams[].key/teams[].repo are required — construction fails closed with an explicit error naming the missing field otherwise (factory.go:32-53). assigned_only: true additionally requires the Linear agent app to already be connected (linearagent.StoredViewerID); without a connected app it is a startup error, not “enumerate everything” (factory.go:58-67).

See Linear agent integration for the OAuth app setup, webhook wiring, LINEAR_CLIENT_ID/LINEAR_CLIENT_SECRET/ LINEAR_WEBHOOK_SECRET, and how agents write back to Linear.

ACMM gap issues. The dashboard’s ACMM “Open Issue” / “Open All” buttons file on GitHub by default even on a Linear-sourced hive. Set governor.acmm.issue_tracker: work_source to file them on the Linear team mapped to the criterion’s repo instead (teams[].repo match, else the first team) — see ACMM policy matrix → Where gap issues are filed.

type: jira — Jira Cloud or Jira Data Center

Reads issues from Jira Cloud via REST API v3, or from Jira Data Center / Server via REST API v2 when deployment: datacenter is set (pkg/worksource/jira.go). The Jira Data Center REST reference documents API version 2 and URI layouts that include the instance context path, such as http://host:port/context/rest/api-name/api-version/resource-name (Atlassian Jira Data Center REST API reference). Atlassian’s server examples use /rest/api/2/... endpoints for issues and searches (Jira REST API examples). Data Center PATs are available in Jira Core/Software 8.14+ and are sent with Jira Data Center’s bearer-token HTTP authentication (Using Personal Access Tokens). Jira Cloud rich text comments/descriptions use ADF JSON (Atlassian Document Format); Data Center accepts plain text / wiki-markup string bodies.

Terms in the examples: PAT is a personal access token; JQL is Jira Query Language, used to select issues; ADF is Atlassian Document Format for rich text. TLS protects the connection, a CA is a certificate authority, and PEM is the text format used for certificates and keys. mTLS means mutual TLS: the client presents a certificate as well as verifying the server.

governor:
  work_source:
    type: jira
    jira:
      base_url: https://your-org.atlassian.net   # required
      email: bot@your-org.com                    # required — Atlassian account email
      api_token: ${JIRA_API_TOKEN}                # required
      project_keys: [ENG, OPS]                    # used to build the default JQL
      # jql: "project in (ENG) AND statusCategory != Done"  # optional full override
      repo: your-org/default-repo                 # required for agents to know what to clone
      hold_labels: [hold, blocked]                # optional — Jira labels that gate an issue

Jira Data Center / Server example:

governor:
  work_source:
    type: jira
    jira:
      deployment: datacenter
      base_url: https://jira.example.com/jira      # context paths are preserved
      api_token: ${JIRA_DATACENTER_PAT}            # preferred PAT bearer auth
      # Or, for older instances without PATs:
      # username: hive-bot
      # password: ${JIRA_DATACENTER_PASSWORD}
      # ca_bundle: ${JIRA_DATACENTER_CA_BUNDLE}    # optional PEM, appended to system roots
      # insecure_skip_verify: false                # optional, unsafe; testing only
      # client_cert: ${JIRA_DATACENTER_CLIENT_CERT} # optional mTLS PEM
      # client_key: ${JIRA_DATACENTER_CLIENT_KEY}   # optional mTLS PEM key
      project_keys: [ENG, OPS]
      repo: your-org/default-repo
      hold_labels: [hold, blocked]

Config fields (JiraSourceConfig, pkg/config/config.go):

¹ project_keys is not enforced as required by the constructor, but if both it and jql are empty the built JQL becomes project in () AND ..., which Jira will reject — set one or the other.

Credentials. Jira Cloud REST v3 uses HTTP Basic auth with the account email as username and the API token (not the account password) as password. Jira Data Center sends the PAT as bearer-token HTTP auth when api_token is set; otherwise it falls back to HTTP Basic with username/password (or email as the username when username is empty). Supply secrets via ${JIRA_API_TOKEN} / ${JIRA_DATACENTER_PAT} / ${JIRA_DATACENTER_PASSWORD} environment-variable substitution in hive.yaml — never inline literal credentials in committed config.

TLS for Data Center

If Jira is signed by an internal CA, set ca_bundle to a PEM bundle (or ${JIRA_DATACENTER_CA_BUNDLE}) and Hive appends those roots to the system trust store. mTLS is optional: provide both client_cert and client_key as PEM values or environment references. The dashboard’s Work Source tab shows these Data Center-only fields as write-only set/unset indicators. insecure_skip_verify remains off by default; when enabled it bypasses TLS verification, should be limited to testing, and emits a warning every time the Jira client is built.

Jira data and failure reference

Data model differences. Cloud users expose accountId and rich-text description/comment bodies as ADF JSON. Data Center commonly exposes users by name / key; the adapter prefers those identities when deployment: datacenter is set. Data Center comments sent by Hive are plain strings so Jira can render them as wiki markup/plain text; Cloud comments use a minimal ADF document.

Priority mapping. Jira priority names are normalized case-insensitively (normalizeJiraPriority, jira.go:126-141):

Hold-label gating. ListIssues drops any issue whose Jira labels field contains one of the configured hold_labels before it is returned to the governor — the same shape as GitHub’s hold label, but Jira has no built-in “hold” concept so this is opt-in and additive (jira.go:143-175).

Pagination and endpoints. Cloud posts to /rest/api/3/search/jql with an explicit field list and follows nextPageToken until isLast or no next token. Data Center uses /rest/api/2/search with startAt/maxResults and a total. Both request 100 issues per page until the result set is exhausted. Issue fetch, comment, and transition helper paths use the same API-version switch (/issue/{key}, /issue/{key}/comment, and /issue/{key}/transitions).

Failure mode. A bad base_url, invalid credentials, or non-2xx Jira response causes a worksource/jira: search: ... error on every governor cycle. For an HTTP rejection, the message is worksource/jira: search: returned <status>: <body>. It is logged but not fatal — the hive keeps running with an empty work-item list from this source until the misconfiguration is fixed.

Review backlog routing (review.backlog)

Review findings below the blocking line (review.severity.block_at), and cited out-of-scope findings, are filed as follow-up items in the tracker named by review.backlog.destination. The destination must match the active work source. The item is written with this page’s work-source client and credentials (src/pkg/worksource/review_backlog_sink.go):

If the destination’s work source is not active, or cannot be built (for example a missing api_key), the hive files a GitHub issue with the agent/reviewer label and logs why. Items are de-duplicated per repo by finding fingerprint. When another PR raises the same finding, the hive comments on the existing item instead of filing a new one. At most max_per_pr_per_day items are filed or updated per PR per day. See review-swarm.md for the fingerprint, item body and audit entries.

Open questions

• The issue that requested this page (#4926) says GitHub Projects requires a “project node ID”. The code instead takes a plain integer project_number (the number visible in the project’s URL) and resolves it server-side via GraphQL (organization(login).projectV2(number), github_projects.go:102-103) — there is no node-ID field in GitHubProjectsSourceConfig. This page documents the code as written.