Issue フォームの構文

Issue フォームには、さまざまな入力タイプ、検証、デフォルトのアサインされた人、デフォルトのラベルを定義できます。

この記事の内容

Note

Issue フォームは現在 パブリック プレビュー 段階であり、変更される可能性があります。

Issue フォームの YAML 構文について

YAML フォーム定義ファイルをリポジトリの /.github/ISSUE_TEMPLATE フォルダに追加することで、カスタム Issue フォームを作成できます。 YAML の初心者で詳しく学びたい場合は、「Learn YAML in Y minutes」(YAML を Y 分で学ぶ) を参照してください。 Issue フォームにさまざまな入力タイプ、検証、デフォルトのアサインされた人、デフォルトのラベルを定義できます。

コントリビューターが Issue フォームに入力すると、それぞれの入力に対する回答が Markdown に変換され、Issue の本文に追加されます。 コントリビューターは、Issue フォームで作成された問題を編集でき、他のユーザは、他の方法で作成された Issue のように Issue を取り扱うことができます。

Issue フォームは、pull request ではサポートされていません。 コラボレーターが使用できるように、リポジトリの pull request テンプレートを作成できます。 詳しくは、「リポジトリ用のプルリクエストテンプレートの作成」をご覧ください。

このサンプル YAML 設定ファイルでは、バグを報告するためにいくつかの入力を使用して Issue フォームを定義します。

YAML
name: Bug Report
description: File a bug report.
title: "[Bug]: "
labels: ["bug", "triage"]
projects: ["octo-org/1", "octo-org/44"]
assignees:
  - octocat
body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to fill out this bug report!
  - type: input
    id: contact
    attributes:
      label: Contact Details
      description: How can we get in touch with you if we need more info?
      placeholder: ex. email@example.com
    validations:
      required: false
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Also tell us, what did you expect to happen?
      placeholder: Tell us what you see!
      value: "A bug happened!"
    validations:
      required: true
  - type: dropdown
    id: version
    attributes:
      label: Version
      description: What version of our software are you running?
      options:
        - 1.0.2 (Default)
        - 1.0.3 (Edge)
      default: 0
    validations:
      required: true
  - type: dropdown
    id: browsers
    attributes:
      label: What browsers are you seeing the problem on?
      multiple: true
      options:
        - Firefox
        - Chrome
        - Safari
        - Microsoft Edge
  - type: textarea
    id: logs
    attributes:
      label: Relevant log output
      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
      render: shell
  - type: checkboxes
    id: terms
    attributes:
      label: Code of Conduct
      description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com). 
      options:
        - label: I agree to follow this project's Code of Conduct
          required: true

最上位の構文

すべての Issue フォーム構成ファイルは、name、description、および body のキー/値ペアで始まる必要があります。

YAML
name:
description:
body:

各 Issue フォームに次の最上位のキーを設定できます。

Note

現在、organization での issue の種類、sub-issue、高度な issue の検索は、パブリック プレビュー 段階です。 GitHub のブログをご覧ください。

キー説明必須型
nameIssue フォームテンプレートの名前。 Markdown テンプレートを含む他のすべてのテンプレートと異なる、一意の名前である必要があります。必須String
descriptionテンプレート選択インターフェイスに表示される、Issue フォーム テンプレートの説明。必須String
bodyフォームでの入力の種類の定義。必須Array
assigneesこのテンプレートで作成された Issue に自動的に割り当てられるユーザー。オプション配列またはコンマ区切りの文字列
labelsこのテンプレートで作成された Issue に自動的に追加されるラベル。 リポジトリにラベルがまだ存在しない場合、それが自動的に Issue に追加されることはありません。オプション配列またはコンマ区切りの文字列
titleIssue 送信フォームに事前に設定されるデフォルトのタイトル。オプションString
typeこのテンプレートで作成された issue に自動的に追加される issue の種類。 Issue の種類は organization レベルで定義され、リポジトリ全体で共有される構文を作成するために使用できます。省略可能String
projectsこのテンプレートで作成された問題のあるすべてのプロジェクトは自動的に追加されます。 このキーの形式は PROJECT-OWNER/PROJECT-NUMBER です。 > [!NOTE] issue を開くユーザーは、指定されたプロジェクトに対する書き込みアクセス許可を持っている必要があります。 このテンプレートを使うユーザーが書き込みアクセス権限を持っていることを期待できない場合は、プロジェクトの自動追加ワークフローを有効にすることを検討してください。 詳細については、「アイテムを自動的に追加する」を参照してください。オプション配列またはコンマ区切りの文字列

body で使用できる入力の種類とその構文については、「GitHub のフォームスキーマの構文」をご覧ください。

Markdown Issue テンプレートを YAML Issue フォーム テンプレートに変換する

リポジトリ内では、Markdown と YAML の両方の Issue テンプレートを使用できます。 Markdown Issue テンプレートを YAML Issue フォーム テンプレートに変換する場合は、新しい YAML ファイルを作成して、Issue フォームを定義する必要があります。 既存の Markdown Issue テンプレートを YAML Issue フォーム テンプレートに変換する場合は、手動で行うことができます。 詳しくは、「リポジトリ用に Issue テンプレートを設定する」をご覧ください。

YAML Issue フォームに同じファイル名を使用する場合は、新しいファイルをリポジトリにコミットするときに、Markdown Issue テンプレートを削除する必要があります。

Markdown Issue テンプレートと、対応する YAML Issue フォーム テンプレートの例を次に示します。

Markdown Issue テンプレート

Markdown
---
name: 🐞 Bug
about: File a bug/issue
title: '[BUG] <title>'
labels: Bug, Needs Triage
assignees: ''

---

<!--
Note: Please search to see if an issue already exists for the bug you encountered.
-->

### Current Behavior:
<!-- A concise description of what you're experiencing. -->

### Expected Behavior:
<!-- A concise description of what you expected to happen. -->

### Steps To Reproduce:
<!--
Example: steps to reproduce the behavior:
1. In this environment...
1. With this config...
1. Run '...'
1. See error...
-->

### Environment:
<!--
Example:
- OS: Ubuntu 20.04
- Node: 13.14.0
- npm: 7.6.3
-->

### Anything else:
<!--
Links? References? Anything that will give us more context about the issue that you are encountering!
-->

YAML Issue フォーム テンプレート

YAML
name: 🐞 Bug
description: File a bug/issue
title: "[BUG] <title>"
labels: ["Bug", "Needs Triage"]
body:
- type: checkboxes
  attributes:
    label: Is there an existing issue for this?
    description: Please search to see if an issue already exists for the bug you encountered.
    options:
    - label: I have searched the existing issues
      required: true
- type: textarea
  attributes:
    label: Current Behavior
    description: A concise description of what you're experiencing.
  validations:
    required: false
- type: textarea
  attributes:
    label: Expected Behavior
    description: A concise description of what you expected to happen.
  validations:
    required: false
- type: textarea
  attributes:
    label: Steps To Reproduce
    description: Steps to reproduce the behavior.
    placeholder: |
      1. In this environment...
      1. With this config...
      1. Run '...'
      1. See error...
  validations:
    required: false
- type: textarea
  attributes:
    label: Environment
    description: |
      examples:
        - **OS**: Ubuntu 20.04
        - **Node**: 13.14.0
        - **npm**: 7.6.3
    value: |
        - OS:
        - Node:
        - npm:
    render: markdown
  validations:
    required: false
- type: textarea
  attributes:
    label: Anything else?
    description: |
      Links? References? Anything that will give us more context about the issue you are encountering!

      Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
  validations:
    required: false

参考資料