Tickets and gates · Factorial Docs

This page shows what a person does to and with a ticket. You file an issue, read its labels, decide a gate, and stop, resume or release a ticket that Factorial has parked.

Factorial writes the labels on a ticket to show its state. When you edit a ticket, Factorial reads your edit as input and acts on it at its next poll. Human edits explains why.

File an issue

A ticket starts as a GitHub issue. Factorial admits the issue when it meets the entry condition of its process, and the project must be active. In the sample process, the entry condition is the label factorial:new and an assignee. Your process can set another condition. Which issues enter explains how to write it.

When Factorial admits the issue, it labels the issue with the name of the first step. It does not assign the issue at that time. The outcomes of the steps assign the ticket later, to whoever must act next.

Choose a lane

A project can have more than one process. A process is a lane. To choose the lane, add the label factorial:process:<key>, where <key> is the name of the process.

An issue with no factorial:process: label uses the default lane of the project.
An issue with two of these labels does not enter.
An issue with a label for a lane that the project does not offer does not enter. It never falls back to the default lane.

The label must exist in the repository before you can add it. Connect a repository shows how to create the labels.

To see why an issue has not entered, open the project in the dashboard. On the Tickets tab, choose the Admission filter. The list shows each open issue that is not yet a ticket and what it still waits for.

Write the issue as a brief

The agent works from the issue. In the sample process, the plan agent receives the number, the body and the comments of the issue. Write the body as a brief for a colleague who does not know the code:

State the outcome that you want, and who needs it.
Name the constraints that matter, for example a file, an interface or a limit.
Link related issues and pull requests.

The agent also reads the comments. A comment is the place to add a constraint that you forgot.

Read a ticket's labels

The labels show where a ticket is. Factorial sets and removes them. Do not add a label to move a ticket. The exceptions are in the table.

Label	Meaning	Who sets it
`factorial:<step>`	The step that the ticket is on. A step name with an underscore keeps the underscore, for example `factorial:validate_ci`. A step can also set its own label in the process file, for example `factorial:spec-review` while a gate waits for a review.	Factorial
`factorial:blocked`	Factorial escalated the ticket, and a person must act. See Blocked tickets.	Factorial
Blocked-at label, for example `factorial:pr_merge_gate`	The step that the ticket is stuck on. It shows beside `factorial:blocked`. It uses the exact name of the step in the process file.	Factorial
`factorial:interrupted`	A person stopped the run. The ticket keeps the session and the workspace of the agent. Remove the label to resume. See Interrupt and resume. A session that reaches its time limit also shows this label.	Factorial, after a person interrupts
`factorial:waiting`	An interactive session waited for an answer and nobody replied, so it parked. Remove the label to resume. See When a run waits.	Factorial
`factorial:exit`	The ticket left the process. Remove the label to bring it back. See Exit and try again.	Factorial, or a person who adds it to exit the ticket
`factorial:done`	The ticket reached the end of its process.	Factorial
`factorial:process:<key>`	The lane that the issue asks for. Factorial reads it at admission and removes it afterwards.	A person

In the sample process, factorial:new is also a label that a person adds. Factorial removes it after admission. Labels that do not start with factorial: are yours. Factorial does not remove them.

Three labels resume or re-enter a ticket when you remove them. Removing factorial:interrupted or factorial:waiting resumes the session of the agent. Removing factorial:exit starts a fresh attempt at the step that the ticket left. One exception exists: a session at its time limit resumes only from the dashboard. Removing factorial:blocked retries the step that failed. See Blocked tickets.

Decide a gate

A gate waits for a person to review a pull request. While it waits, the dashboard shows the ticket as Waiting at gate. The ticket page shows Waiting for a review and a link to the pull request. Gates explains the gate in the process.

To decide a gate in GitHub:

Open the pull request that the gate names.
Read the changes. Check the pull request against the issue.
Submit a review. Choose Approve to accept the work. Choose Request changes to send it back, and write what must change.

What happens next depends on your decision:

After you approve, Factorial merges the pull request and moves the ticket to the next step. One approval from a reviewer who qualifies is enough. A commit that someone pushes after your approval needs a new approval.
After you request changes, Factorial runs the rework step of the gate again. The agent receives your review comments and pushes new work to the pull request.

If GitHub refuses the merge, the gate keeps waiting and Factorial comments on the ticket with the reason. If the review does not count, Factorial comments with that reason too.

Only some reviewers can decide a gate. Your process names them, either as a list of people or as a repository role. Who may decide a gate has the rules.

Decide from the dashboard

The dashboard cannot approve. Approve in GitHub. The ticket page does offer Request changes, for a gate that has a rework step. Use it like this:

Open the ticket page. In the Waiting for a review message, push Request changes.
Write what must change in the attempt.
Push Send change request.

The request rejects the gate and starts a new attempt of the rework step. The agent receives your text as its change request. Factorial also posts the text, with your email, on the pull request. Anyone who can read the repository can read it, so never write a credential in it. Factorial refuses a request that comes after the pull request merged, and it gives the reason.

Any signed-in dashboard user can send a change request. The request can only send work back. It cannot approve or merge.

Interrupt and resume

You can stop a running agent and let it continue later. An interrupt stops the run, and it keeps the session of the agent and its workspace.

Open the ticket page.
In the activity, find the attempt that runs. Push Interrupt and confirm.

You can interrupt only an agent step that runs. Factorial parks the ticket and adds factorial:interrupted beside the label of the step.

To resume, remove factorial:interrupted from the issue. The agent continues its own session in the workspace that Factorial kept, on the same attempt. A comment that you add to the ticket during the park becomes the next instruction of the agent. Use this to steer the agent before you resume.

A ticket that has an interactive session can also resume from the dashboard, with Resume session in the Terminal section of the run. When a run waits has the details.

When a run waits

An interactive session can wait for you at its prompt. If the agent asks a question and nobody answers, the session parks. Factorial adds factorial:waiting. It comments on the ticket with the question of the agent and the postconditions that are not yet met. The comment also links to the terminal of the run.

To continue, do one of these:

Remove factorial:waiting from the issue.
Open the terminal of the run on the ticket page, write your answer, and push Resume session. Your answer is the next turn of the agent.

If you remove the label while the session is still idle and not yet parked, nothing happens. Factorial writes the label again.

A session also has a time limit. When a session reaches it, Factorial parks the session and adds factorial:interrupted. The operator sets the limit for the deployment. Interactive sessions explains the setting. Only the dashboard can resume this park. Push Resume session in the terminal of the run. If you remove the label, Factorial adds one comment and writes the label again.

Exit and try again

A ticket can leave the process before it ends. This is an exit. Factorial stops the live work and parks the ticket with factorial:exit. To exit a ticket:

Add the label factorial:exit to the issue.
Close the issue. Closing counts as an exit unless the ticket is at its last step or waits at a gate.
On the ticket page, push Exit and confirm.

To bring the ticket back, first open the issue again if you closed it. Then remove factorial:exit, or push Re-enter on the ticket page. The ticket gets a fresh attempt at the step that it left, after the retry delay. Factorial does not re-enter a ticket while its issue stays closed. It comments with the reason.

A ticket that has no retry policy cannot get a fresh attempt. Factorial refuses and comments. Defaults, retries and escalation shows how to set a retry policy.

How a ticket ends explains the exit from the point of view of the process.

Blocked tickets

A step can fail. Factorial then retries it, up to the number of attempts that the process allows, with a delay between the attempts. When all attempts fail, Factorial escalates. It adds factorial:blocked and a blocked-at label, assigns the ticket as the process says, and comments with the reason. Defaults, retries and escalation explains how to set these.

A gate that rejects work, when the process has no rework step for it, blocks the ticket too. The ticket page then shows Rejected.

To release a blocked ticket:

Read the comment on the ticket and the activity on the ticket page. Find the cause of the failure.
Fix the cause.
Remove factorial:blocked from the issue, or push Unblock on the ticket page and confirm.

Factorial starts a fresh set of attempts at the failed step, after the retry delay. For a rejected gate, it opens the gate again for a new review. To skip the delay of a retry that is already booked, push Retry now in the attempt on the ticket page.

Two other states look similar. A Quarantined ticket is one whose passes keep failing. Factorial stops retrying it. Fix the cause and push Requeue. For a ticket that shows Passes are failing, Factorial retries on its own interval.