States and transitions
Implementation and handling of state transitions in an IssueOps workflow
- Alpha
As the introduction mentioned, IssueOps can be thought of as a state diagram where an issue transitions through different states in response to events and conditions. This section of the documentation describes some common states, transitions. and how to implement them in your workflows.
If an issue was a paper form, a state would be a big rubber stamp that tells anyone who looks at the form exactly what is going on.
Tracking state can be as simple as checking what labels are applied to your issues. Whatever approach you want to take, remember that tracking state is critical to ensure that the right processing occurs at the right time!
| State | Description |
|---|---|
Opened | The initial state for a new issue that has been opened. |
| Typically the first state in the lifecycle of an issue. | |
Parsed | The issue body has been read and converted to machine-readable JSON |
Usually the next immediate state after Opened. | |
Validated | The issue body has been deemed valid based on any custom rules. |
Usually the next immediate state after Parsed. | |
| The next transitions depend on the type of request and any rules that must be followed. | |
Submitted | The issue has been submitted for processing |
Approved | The issue has been approved for processing. |
Denied | The issue has been denied for processing |
Closed | The issue has been closed 🎉 |
If an issue was a paper form, a transition would be someone taking it out of their inbox, stamping it APPROVED, and putting it in their outbox.
Transitions are where actual processing on your issues occurs. A transition is equivalent to an event that triggers a GitHub Actions workflow run. That is why, as your IssueOps workflows become larger and more complex, tracking state is so important. Otherwise, its easy to end up the wrong workflows running at the wrong time!
Since each transition is triggered by the same type of event:
on:issue_comment:- created
Your workflows must track the following to determine what jobs to run:
Each of the following sections describes how to implement the core transitions in an IssueOps workflow. Throughout each page, you will see an example implementation of a new repository request workflow. This workflow is designed to demonstrate how to apply each concept.
Nope! You can use as many or as few states as you need. For example, if you
don't need an authorized user to approve requests, you can omit the Approved
state.
Of course! In state diagrams, its common for each state to have multiple transitions. States can even transition back into themselves!
When an issue is first opened it will be in the Opened state. Typically, the
first step after an issue is opened is to parse the body and prepare for further
processing. If this is successful, the issue would transition into the Parsed
state. If there is a problem during parsing, the workflow can add a comment with
a descriptive error and return the issue to the Opened state. When the user
edits the issue to fix the error, parsing would run again.