Parse

When a new issue is opened, before any action can be taken on it, you should parse its contents and turn it into a machine-readable format. The issue-ops/parser action does this by comparing the body of the issue with the original issue form template. This way, you can directly reference issue form fields without having to parse the body yourself with regular expressions.

NPM Package

This is also available as a standalone npm package, @github/issue-parser

This action provides specific output formats based on the typeproperty of the input.

Input type	Example parsed output
`input`	`"octorepo"`
`textarea`	`"This is a description!\n\nIt is multiline, too!"`
`dropdown`	`["octocat", "issueops"]`
`checkboxes`	`{ "selected": ["Yes"], "unselected": ["No"] }`

Depending on how you're processing the input data, different types may be more helpful than others! Based on the issue form template and the contents of the issue itself, the json output will look similar to the following:

1{
2  "the_name_of_the_thing": "this-thing",
3  "the_nickname_of_the_thing": "thing",
4  "the_color_of_the_thing": ["blue"],
5  "the_shape_of_the_thing": ["square"],
6  "the_sounds_of_the_thing": ["re", "mi"],
7  "the_topics_about_the_thing": [],
8  "the_description_of_the_thing": "This is a description.\n\nIt has lines.",
9  "the_notes_about_the_thing": "- Note\n- Another note\n- Lots of notes",
10  "the_code_of_the_thing": "const thing = new Thing()\n\nthing.doThing()",
11  "the_string_method_of_the_code_of_the_thing": "thing.toString()",
12  "is_the_thing_a_thing": {
13    "selected": ["Yes"],
14    "unselected": ["No"]
15  },
16  "is_the_thing_useful": {
17    "selected": ["Sometimes"],
18    "unselected": ["Yes", "No"]
19  },
20  "read_team": "IssueOps-Demo-Readers",
21  "write_team": "IssueOps-Demo-Writers"
22}

Once an issue has been parsed, the next step is to validate the contents to make sure the request isn't missing data, doesn't contain invalid data, and can be processed by your workflow.

New repository request

Issue form template

The new repository worklow starts off with the following issue form template.

1name: New Repository Request
2description: Submit a request to create a new GitHub repository
3title: '[Request] New Repository'
4labels:
5  - issueops:new-repository
6
7body:
8  - type: markdown
9    attributes:
10      value:
11        Welcome to GitHub! Please fill out the information below to request a
12        new repository. Once submitted, your request will be reviewed by the
13        IssueOps team. If approved, the repository will be created and you will
14        be notified via a comment on this issue.
15  - type: input
16    id: name
17    attributes:
18      label: Repository Name
19      description: The name of the repository you would like to create.
20      placeholder: octorepo
21    validations:
22      required: true
23  - type: dropdown
24    id: visibility
25    attributes:
26      label: Repository Visibility
27      description: The visibility of the repository.
28      multiple: false
29      options:
30        - private
31        - public
32    validations:
33      required: true
34  - type: input
35    id: read-team
36    attributes:
37      label: Read Team
38      description: The GitHub Team that will get read access to the repository.
39      placeholder: octocat-readers
40    validations:
41      required: true
42  - type: input
43    id: write-team
44    attributes:
45      label: Write Team
46      description: The GitHub Team that will get write access to the repository.
47      placeholder: octocat-writers
48    validations:
49      required: true
50  - type: dropdown
51    id: auto-init
52    attributes:
53      label: Auto Init
54      description: Select `true` to initialize the repository with a `README`.
55      multiple: false
56      options:
57        - 'true'
58        - 'false'
59    validations:
60      required: true
61  - type: textarea
62    id: topics
63    attributes:
64      label: Topics
65      description:
66        (Optional) A list of topics to add to the repository. Separate each
67        topic with a new line.
68      placeholder: |
69        octocat
70        octodog
71    validations:
72      required: false

When a user submits a request for a new repository, the issue form will look something like this:

GitHub Actions workflow

Creating an issue will kick off the start of the IssueOps process. However, in order to do anything with the request, we need to parse the issue body and extract the information we need to get approval and create a repository.

Tips and Tricks

Check the workflow comments for useful tips!

1name: Issue Opened/Edited/Reopened
2
3# At minimum, the issue body should be parsed any time an issue is opened,
4# edited, or reopened. This ensures that the most up to date information is
5# validated.
6on:
7  issues:
8    types:
9      - opened
10      - edited
11      - reopened
12
13jobs:
14  # Different request types may have different inputs. For example, a new
15  # repository request may have different inputs than a repository transfer
16  # request. You can create multiple jobs to parse different types of requests
17  # in the same workflow. Labels can be used to control which jobs run for
18  # which types of requests.
19  new-repository-request:
20    name: New Repository Request
21    runs-on: ubuntu-latest
22
23    # Assign labels for different types of requests, and use those labels to
24    # trigger different workflows, jobs, and steps.
25    if: contains(github.event.issue.labels.*.name, 'issueops:new-repository')
26
27    # Initially, this workflow only needs permissions to read issues and
28    # contents. This will be expanded later as we build additional
29    # functionality.
30    permissions:
31      contents: read
32      issues: read
33
34    steps:
35      # Get the repository contents. This lets the workflow reference files in
36      # the repository such as the issue form template.
37      - name: Checkout
38        id: checkout
39        uses: actions/checkout@vX.X.X
40
41      - name: Parse Issue
42        id: parse
43        uses: issue-ops/parser@vX.X.X
44        with:
45          body: ${{ github.event.issue.body }}
46          issue-form-template: new-repository-request.yml
47
48      - name: Output the Parsed Issue
49        id: output
50        run: echo ${{ steps.parse.outputs.json }}

Next steps

At this point, our issue has successfully transitioned into the Parsedstate. This means that we have a machine-readable representation of the request that can be further processed by our workflows. However, we don't know if the request actually contains valid information! The next transition involves validating the parsed request against a set of rules to make sure it's ready to be processed.Continue to the next section to learn about validation.