Parse

Overview

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. This action provides specific output formats based on the type property of the input.

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:

{
  "the_name_of_the_thing": "this-thing",
  "the_nickname_of_the_thing": "thing",
  "the_color_of_the_thing": ["blue"],
  "the_shape_of_the_thing": ["square"],
  "the_sounds_of_the_thing": ["re", "mi"],
  "the_topics_about_the_thing": [],
  "the_description_of_the_thing": "This is a description.\n\nIt has lines.",
  "the_notes_about_the_thing": "- Note\n- Another note\n- Lots of notes",
  "the_code_of_the_thing": "const thing = new Thing()\n\nthing.doThing()",
  "the_string_method_of_the_code_of_the_thing": "thing.toString()",
  "is_the_thing_a_thing": {
    "selected": ["Yes"],
    "unselected": ["No"]
  },
  "is_the_thing_useful": {
    "selected": ["Sometimes"],
    "unselected": ["Yes", "No"]
  },
  "read_team": "IssueOps-Demo-Readers",
  "write_team": "IssueOps-Demo-Writers"
}

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.

name: New Repository Request
description: Submit a request to create a new GitHub repository
title: '[Request] New Repository'
labels:
  - issueops:new-repository

body:
  - type: markdown
    attributes:
      value:
        Welcome to GitHub! Please fill out the information below to request a
        new repository. Once submitted, your request will be reviewed by the
        IssueOps team. If approved, the repository will be created and you will
        be notified via a comment on this issue.
  - type: input
    id: name
    attributes:
      label: Repository Name
      description: The name of the repository you would like to create.
      placeholder: octorepo
    validations:
      required: true
  - type: dropdown
    id: visibility
    attributes:
      label: Repository Visibility
      description: The visibility of the repository.
      multiple: false
      options:
        - private
        - public
    validations:
      required: true
  - type: input
    id: read-team
    attributes:
      label: Read Team
      description: The GitHub Team that will get read access to the repository.
      placeholder: octocat-readers
    validations:
      required: true
  - type: input
    id: write-team
    attributes:
      label: Write Team
      description: The GitHub Team that will get write access to the repository.
      placeholder: octocat-writers
    validations:
      required: true
  - type: dropdown
    id: auto-init
    attributes:
      label: Auto Init
      description: Select `true` to initialize the repository with a `README`.
      multiple: false
      options:
        - 'true'
        - 'false'
    validations:
      required: true
  - type: textarea
    id: topics
    attributes:
      label: Topics
      description:
        (Optional) A list of topics to add to the repository. Separate each
        topic with a new line.
      placeholder: |
        octocat
        octodog
    validations:
      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.

name: Issue Opened/Edited/Reopened

# At minimum, the issue body should be parsed any time an issue is opened,
# edited, or reopened. This ensures that the most up to date information is
# validated.
on:
  issues:
    types:
      - opened
      - edited
      - reopened

jobs:
  # Different request types may have different inputs. For example, a new
  # repository request may have different inputs than a repository transfer
  # request. You can create multiple jobs to parse different types of requests
  # in the same workflow. Labels can be used to control which jobs run for
  # which types of requests.
  new-repository-request:
    name: New Repository Request
    runs-on: ubuntu-latest

    # Assign labels for different types of requests, and use those labels to
    # trigger different workflows, jobs, and steps.
    if: contains(github.event.issue.labels.*.name, 'issueops:new-repository')

    # Initially, this workflow only needs permissions to read issues and
    # contents. This will be expanded later as we build additional
    # functionality.
    permissions:
      contents: read
      issues: read

    steps:
      # Get the repository contents. This lets the workflow reference files in
      # the repository such as the issue form template.
      - name: Checkout
        id: checkout
        uses: actions/checkout@vX.X.X

      - name: Parse Issue
        id: parse
        uses: issue-ops/parser@vX.X.X
        with:
          body: ${{ github.event.issue.body }}
          issue-form-template: new-repository-request.yml

      - name: Output the Parsed Issue
        id: output
        run: echo ${{ steps.parse.outputs.json }}

Next steps

At this point, our issue has successfully transitioned into the Parsed state. 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.