Clarifications and approvals

What this means

Some pipelines pause and wait for a person. There are four kinds of pause:

Awaiting clarification - the agents have a question. The pipeline can't move until you answer.
Awaiting approval - the merge request is open. The pipeline is waiting for someone to approve before it merges. May also surface a Merge blocked banner when the provider rejected the last merge attempt.
Paused — ticket on hold - the Jira ticket moved into a configured hold status. Bilbis resumes the pipeline automatically when the ticket leaves all hold statuses.
Configure Jira fields - Jira refused a workflow transition because required fields weren't supplied. An admin must update the Jira config before the pipeline can resume.

All four are normal. The first two are handled from the pipeline detail page. The last two clear themselves once Jira (or an admin) updates the right thing.

Awaiting clarification

The state badge is amber and reads Needs your input. The pipeline detail page grows a Clarifications tab. The tab indicator pulses while a question is pending.

When it happens

Common triggers:

The task description didn't say which branch to merge into, and the agent couldn't infer one.
The task could apply to more than one repo (in Let Bilbis pick mode), and the agent isn't confident enough to pick alone.
The agent needs a piece of information to continue - a value, a path, a yes/no decision.

Question kinds

Bilbis has three shapes of clarification, all on the same tab:

Kind	What it looks like	What you do
Branch needed	Blue Branch needed badge on the row. A small input field.	Type a branch name like `dev` or `main`. Long-form like "merge into staging" works too.
Multi-repo split needed	Violet Multi-repo split needed badge. Two buttons.	Click Yes, split to spawn one child pipeline per routed repo, or No, cancel to mark the parent failed.
Free-text question	Plain badge. A reply input field.	Type your answer and click Send reply.

Each clarification row also shows the round number, who asked, when it was asked, and the status (Pending, Answered, Timed out, or Cancelled).

Web channel vs Jira channel

The clarification can be delivered through the web app or through a Jira comment, depending on how the pipeline was created and configured.

Web channel - reply directly on the Clarifications tab. The pipeline resumes within a few seconds.
Jira channel - Bilbis posted the question on the linked Jira issue. Reply on the Jira comment instead. Bilbis polls Jira every few minutes and resumes the pipeline once it sees your reply.

The tab shows a banner at the top when a Jira-channel question is pending so you know to look at Jira instead of replying on the web.

Steps - answering a web-channel clarification

Open the pipeline detail page.
Click the Clarifications tab.
Read the question.
Reply using the input or buttons that appear:
- For branch questions, type the branch name.
- For split questions, click Yes, split or No, cancel.
- For free-text questions, type your answer.
Click the submit button (label varies - Resume pipeline, Send reply, or one of the split buttons).
The pipeline resumes within a few seconds. The state badge flips back to an active state.

Steps - answering a Jira-channel clarification

Open the pipeline detail page and confirm the channel is Jira.
Click the link to the Jira comment, if present.
Reply on the Jira issue.
Wait. Bilbis polls Jira every few minutes. The pipeline resumes after the next poll picks up your reply.

Cancelling a clarification

Admin-only. Useful when the task is no longer needed and you don't want to keep waiting.

On the Clarifications tab, the Jira-channel banner has a Cancel pipeline button. Pipelines on the web channel can be cancelled from the header Cancel button.
Confirm in the dialog.
The pipeline transitions to Cancelled. Any work the agent already did in its container is discarded.

A scheduled job auto-cancels stuck clarifications after 48 hours. The pipeline ends in Cancelled if no one replies in time. (Window flagged for backend confirmation.)

Awaiting approval

The state badge is amber and reads Awaiting approval. The pipeline header grows a yellow callout with a countdown.

When it happens

The agents finished coding, pushed a branch, opened the MR or PR, and CI passed. Bilbis now waits for a human to sign off before it merges.

The product's settings decide whether this state appears at all. Products with auto-merge configured may skip approval entirely. Products that require approval will pause every pipeline here.

Where you can approve

Approvals from any of these places work. Pick whichever is most convenient.

Approve & Merge button on the pipeline detail page (admin-only).
The merge request page on GitLab - leave an approval there.
The pull request page on GitHub - leave an approval there.
A reply on the linked Jira issue, when the product is configured for Jira approvals.

A scheduled job picks up approvals from any source within about 60 seconds and flips the state to Merging.

The countdown

The header callout shows how long until auto-merge fires. A few possible texts you might see:

"Waiting for human approval - auto-merge in 1h 12m" - the timer is running. If no one approves, the cron will auto-merge when it expires.
"Auto-merge window passed - waiting for cron sweep" - the timer expired. Cron will pick up the merge on its next sweep.
"Approval window expired - still parked (auto-merge disabled)" - the timer expired and your product has auto-merge off. The pipeline stays parked until someone approves.

The callout is yellow when normal, red when parked.

If the provider rejected Bilbis's last merge attempt, a second red banner shows under the approval banner reading Merge blocked: <friendly reason>. A scheduled job retries the merge every ten minutes. You don't need to retrigger anything - just clear the underlying block.

Common reasons (the banner lines them up to the source's exact status):

Friendly label	Source	Where to fix
Merge conflicts on the target branch	`gitlab:broken_status`, `github:dirty`	Resolve conflicts in your IDE or on the provider, then push.
CI must pass before merge	`gitlab:ci_must_pass`, `github:unstable`	Wait for CI. If a job is stuck, fix it on the provider.
Open discussions block the merge	`gitlab:discussions_not_resolved`	Resolve every open discussion thread on the MR.
Required approvals missing	`gitlab:not_approved`	Get the remaining reviewers to approve on the provider.
Reviewer requested changes	`gitlab:requested_changes`	Address the review and push - the reviewer needs to approve again.
Blocked by branch protection rules	`gitlab:blocked_status`, `github:blocked`	An admin needs to relax the branch rule, or the MR/PR needs the missing approvals.
Branch is behind the base	`github:behind`	Update the branch from the base, then push.
MR/PR is still in draft	`gitlab:draft_status`, `github:draft`	Mark the MR or PR as ready on the provider.
External status checks failing	`gitlab:external_status_checks`	Fix or override the failing external check.
Provider returned HTTP <code>	`http_<code>`	Provider was unreachable; cron will retry. If it persists, check provider status.

The banner also has an Open MR/PR link to jump straight to the source. Once the block clears, the next ten-minute retry merges and the pipeline transitions to Merging → Done.

Paused — ticket on hold

The state badge is amber and reads Paused — ticket on hold. The pipeline detail page shows the badge plus a small hint pointing at the Timeline tab for the latest reason.

When it happens

A Jira webhook moved the ticket into one of the Hold statuses configured in Settings → Integrations → Jira (or on a per-product Jira override). Examples teams typically configure: On Hold, Blocked, Waiting on customer.

How to resume

Move the Jira ticket back out of the hold status. The next Jira webhook poll resumes the pipeline automatically - no FE button. Cancel still works from the pipeline header if the work is no longer needed.

Where the reason lives

The latest Timeline transition row has an On hold callout naming the hold status the ticket entered. Each subsequent move into a different hold status appends another transition row.

Configure Jira fields

The state badge is orange and reads Configure Jira fields. This pause is admin-only.

When it happens

Bilbis tried to move the linked Jira ticket through one of the configured workflow statuses (typically Code Review when the MR opens) but Jira refused because the transition requires fields that weren't supplied. The pipeline parks until those fields are mapped.

How to resume

Open Settings → Integrations → Jira (or Products → <your product> → Jira override if the product overrides the org config).
Expand Transition field mappings.
Find the target status that failed - the Timeline tab callout names the missing field IDs.
Add a row for each required field: paste the field ID (for example customfield_10015) and a value. Strings, dates, and JSON values are supported. See Jira setup for the full editor.
Save.
Retrigger the pipeline (cancel and re-dispatch, or use a saved template). The next attempt submits the new fields and Jira accepts the transition.

Placeholder values

The editor expands these at transition time:

Placeholder	Result
`{{today}}`	The current date in `YYYY-MM-DD`.
`{{today+Nd}}`	Today plus N days (N from -365 to 365).
`{{now}}`	Current ISO timestamp.

Steps - approving from the pipeline detail page

Open the pipeline.
Look for the Approve & Merge button on the right of the header.
Click it.
Approval is recorded. The cron picks it up within 60 seconds. State flips to Merging, then Done.

Steps - approving from Jira

Open the linked Jira issue.
Reply with whatever phrase your product is configured to accept (typically a positive word like approve or lgtm).
Wait. The cron picks up Jira approvals within 60 seconds.

Permissions

Action	Who can do it
Read clarifications	Any role.
Reply on the web channel	Any role.
Cancel a clarification	Admin or owner.
Click Approve & Merge on the pipeline page	Admin or owner.
Approve via the MR or PR page	Whoever can approve on your Git provider.
Approve via Jira	Whoever can comment on the Jira issue.

Problems and fixes

Problem	What to check
The Clarifications tab dot won't stop pulsing.	A question is still pending. Read it and reply.
I replied but the pipeline didn't resume.	If the channel is Jira, wait - polling can take a few minutes. If the channel is web, refresh the page; a 409 error from the agent means it couldn't read your reply. Try a shorter, clearer answer.
The branch input rejected my reply.	The agent asked for a branch and couldn't read one out of your text. Try just the branch name, like `dev`.
The split buttons keep disabling.	A reply is in flight. Wait a moment, then try again.
Approve & Merge is missing.	The pipeline is not in Awaiting approval, or your role doesn't allow approving. Check the state badge first.
The yellow callout went red.	Auto-merge is disabled and the window expired. Approve via any channel to unblock.
The pipeline stayed in Awaiting approval for an hour after I approved on Jira.	The cron sweeps every 60 seconds. If it's been longer, check whether the Jira reply was on the right comment thread.
The pipeline ended in Cancelled and I never cancelled it.	Either an admin cancelled it, the 48-hour clarification auto-cancel fired, or the linked Jira ticket moved into a configured Cancel status (see Jira setup). (48-hour window flagged for backend confirmation.)
The pipeline shows Merge blocked and I can't tell what to fix.	Read the banner's friendly reason and the raw status next to it. The reason maps to a specific provider check (CI, conflicts, draft, branch protection). Open the MR/PR via the banner's link. Cron retries every ten minutes.
The pipeline shows Paused — ticket on hold but the ticket is no longer on hold.	Bilbis polls Jira on a schedule. Wait a few minutes for the next poll, or move the ticket through a non-hold status to push a fresh webhook event.
The pipeline shows Configure Jira fields and I'm not an admin.	Only admins/owners can edit Transition field mappings. Ask an admin. The Timeline tab callout shows which field IDs Jira asked for so you can paste them when relaying.

Pipeline states - every state and badge color.
Review pipeline results - read the detail page tab by tab.
Create a pipeline - Merge target branch, Let Bilbis pick, and other fields that affect whether a clarification fires.
Troubleshooting - recovery for stuck or failed runs.
Jira setup - configure trigger, cancel, hold statuses, and transition field mappings.

Clarifications and approvals

On this page