States and transitions

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.

States

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!

Transitions

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:

• Issue state
• Issue body
• Comment body (command and arguments)
• Any other relevant information in the issue

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.

• Parse
• Validate
• Submit
• Approve
• Deny

FAQ

Do my IssueOps need all these states?

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.

Can my IssueOps use each state more than once?

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.