Jira Agent Onboarding Guide

This guide walks you through setting up the jira-agent periodic Prow job for your OpenShift team. The jira-agent automatically picks up Jira issues, solves them using Claude Code, runs code review, addresses findings, creates PRs, and sends Slack notifications.

Generic Step Registry

The Jira Agent is implemented as a generic, parameterized step registry in openshift/release at ci-operator/step-registry/jira-agent/. Any team can reuse it by creating a thin wrapper workflow with their own env vars and credentials. No bash scripting required.

For the full setup guide — workflow templates, periodic job config, credentials, environment variables, and credential overrides — see the step registry ONBOARDING.md.

How It Works

flowchart LR A["🔍 Jira Query"] --> B["🛠️ Solve"] B --> C["👀 Review"] C --> D["✅ Fix"] D --> E["🚀 Create PR"] E --> F["💬 Slack Notify"] E --> G["📊 HTML Report"]

The jira-agent runs as a periodic Prow job with three phases:

Phase	What happens
Setup	Verifies Claude Code CLI and Vertex AI credentials
Process	For each Jira issue: solve review fix PR creation
Report	Generates an HTML report with token usage, cost breakdown, and phase output

Your team creates a thin workflow YAML that sets team-specific env vars and references the generic step registry components.

Prerequisites

Checklist

[x] GitHub App installed on both your fork org and upstream repo
[x] Fork organization on GitHub where the agent pushes branches
[x] Vault secret synced to OpenShift CI
[x] Vertex AI access via a Google Cloud service account
[x] Jira labels on issues you want the agent to process (e.g., issue-for-agent)
[ ] (Optional) Slack incoming webhook for PR notifications

Fork / Upstream Model

The jira-agent pushes branches to a fork and creates PRs against the upstream repo. This is the same fork-based workflow developers use — it avoids needing write access to the upstream repo.

HyperShift Team Example

	Repo	Purpose
Upstream	`openshift/hypershift`	PRs are created against this repo
Fork	`hypershift-community/hypershift`	Agent pushes branches here

Tip

For teams working on repos within the openshift/ GitHub org, create a fork organization (e.g., my-team-bots/my-repo) and install the GitHub App on both. The agent only needs push access to the fork; PR creation to upstream is handled by the GitHub App's permissions.

Setup Steps

Follow the step registry ONBOARDING.md for the complete setup instructions:

Create your wrapper workflow — a thin YAML file referencing the generic step refs with your team's env vars
Create the periodic job config — add the job to your CI config in openshift/release
Set up credentials — store GitHub App, Jira, and Vertex AI credentials in a Vault secret
Submit a PR to openshift/release

Rehearsal Testing

To test your job in a PR, trigger a rehearsal with the full job name:

/pj-rehearse periodic-ci-openshift-<your-repo>-main-periodic-jira-agent

Never run bare /pj-rehearse — always specify the full job name.

Jira Setup

Labels

The agent uses labels to track which issues have been processed:

Label	Who adds it	Purpose
`issue-for-agent`	You	Marks issues for the agent to pick up
`agent-processed`	Agent	Prevents re-processing on subsequent runs

Your JQL query should include labels = issue-for-agent AND labels != agent-processed to implement this pattern.

Security Level

Warning

Make sure your Jira issues are accessible to the service account. If issues have restricted security levels, the agent's API token must have access to that level. Issues with security levels the agent can't see will silently be excluded from JQL results.

Issue Format

For best results, structure Jira issue descriptions with these sections:

Required🔵 Optional

Context — Background information about the problem
Acceptance criteria — Clear criteria for what the fix should accomplish

Steps to reproduce — For bugs, numbered reproduction steps
Expected vs actual behavior — What should happen vs what happens

Validate issues with /jira:ready-to-solve

The /jira:ready-to-solve skill validates that an issue's description is well-groomed enough for the agent to produce a quality solution. It checks for required sections (Context, Acceptance Criteria, Technical Details), runs AI qualitative assessments, and can auto-fix failing checks with --fix. Run it before labeling issues for the agent:

/jira:ready-to-solve OCPBUGS-12345        # validate
/jira:ready-to-solve OCPBUGS-12345 --fix  # validate and fix

Issues that pass are labeled ready-to-solve; those that fail get not-ready-to-solve.

Example Issue Description

## Context
The FooController does not handle the case where the bar field is nil,
causing a nil pointer dereference when reconciling resources created
before v4.15.

## Acceptance Criteria
- The controller handles nil bar field gracefully
- Existing resources without the bar field continue to work
- Unit tests cover the nil case

## Steps to Reproduce
1. Create a Foo resource without the bar field
2. Wait for reconciliation
3. Observe panic in controller logs

JQL Examples

SimpleWith status filterMultiple projectsPriority filter

project = OCPBUGS
  AND labels = issue-for-agent
  AND labels != agent-processed

project = OCPBUGS AND resolution = Unresolved
  AND status in (New, "To Do")
  AND labels = issue-for-agent
  AND labels != agent-processed

project in (OCPBUGS, CNTRLPLANE) AND resolution = Unresolved
  AND status in (New, "To Do")
  AND labels = issue-for-agent
  AND labels != agent-processed

project = OCPBUGS AND priority in (High, Highest)
  AND labels = issue-for-agent
  AND labels != agent-processed

HyperShift Team

The HyperShift team uses this JQL to find agent-eligible bugs:

project in (OCPBUGS, CNTRLPLANE)
  AND resolution = Unresolved
  AND status in (New, "To Do")
  AND labels = issue-for-agent
  AND labels = ready-to-solve
  AND labels != agent-processed

Note the labels = ready-to-solve filter — only issues validated by /jira:ready-to-solve are picked up.

Troubleshooting

\"No issues found\"

Check that your JQL query returns results in the Jira UI
Verify the Jira API token has access to the project and security level
Ensure issues have the issue-for-agent label (or whatever your JQL filters for)

\"Required credentials are missing\"

Verify your Vault secret is synced to the CI namespace
Check that the key names in your secret match JIRA_AGENT_FORK_INSTALLATION_ID_KEY and JIRA_AGENT_UPSTREAM_INSTALLATION_ID_KEY
Required keys: app-id, private-key, fork installation ID, upstream installation ID

\"Failed to generate GitHub App token\"

Verify the GitHub App is installed on the target org/repo
Check that the installation ID is correct (not the app ID)
Ensure the private key matches the app

Plugin installation fails

The process script forces HTTPS for git operations:

git config --global url."https://github.com/".insteadOf "git@github.com:"

If you see SSH-related errors, check that this config is applied before plugin installs

PR creation fails

Verify the GitHub App has Pull requests: Read & write permission on the upstream repo
Check that the fork is synced with upstream (the agent does this automatically)
Ensure the branch name doesn't conflict with an existing branch

Slack notification not sent

Verify slack-webhook-url in the Vault secret is a valid incoming webhook URL
Check job logs for webhook response errors

Reference Implementation

See the HyperShift team's implementation for a complete working example:

Resource	Link
Step registry onboarding guide	`ONBOARDING.md`
Wrapper workflow	`hypershift-jira-agent-workflow.yaml`
Periodic job config	`openshift-hypershift-main.yaml`
Generic steps	`ci-operator/step-registry/jira-agent/`
HyperShift CI docs	AI-Assisted CI Jobs