ScopeReportLocation

Define a report, what it includes, what it looks like, and where to upload to.

Templates

By default, scope has 3 provided templates title, analyze, and doctor.

title is used to determine the title of the issue (if supported), analyze is used when scope analyze is run, and doctor is used when scope doctor is run.

Each of those templates are defined in a Jinja2 format, and they have different options available.

variable	description	example input	available in
entrypoint	The scope command run	scope doctor run	title, analyze, doctor
command	The scope command run	scope doctor run	analyze, doctor
groups	Output from each group run with doctor	{ name: string, actions: []{ check: [], fix: [], validate: [] }, additional_data: [string]:string	doctor
additionalData	Additional data from location	[]{ name: string, command: string, output: string }	doctor, analyze
result	Output from the command	{command: string, exit_code: i32, start_time: string, end_time: string, output: string}	analyze

GitHub Issues

When reporting to GitHub Issues, the env-var SCOPE_GH_TOKEN must be set to get the API token. When reporting to GitHub Issues, multiple authentication methods are supported:

1. GitHub App: SCOPE_GH_APP_ID and SCOPE_GH_APP_KEY
2. Personal Access Token: SCOPE_GH_TOKEN

---
apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: github
spec:
  destination:
    githubIssue:
      owner: ethankhall
      repo: dummy-repo

RustyPaste

RustyPaste is a pastebin style application. This may be a better choice when you can't require GitHub API token, or if there is a risk of sensitive data that shouldn't be in GitHub.

---
apiVersion: scope.github.com/v1alpha
kind: ScopeReportLocation
metadata:
  name: report
spec:
  destination:
    rustyPaste:
      url: http://localhost:8000

Schema

Viewer

Loading ....

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "V1AlphaReportLocation",
  "description": "A `ScopeReportLocation` tells where to upload a report to.",
  "type": "object",
  "required": [
    "apiVersion",
    "kind",
    "metadata",
    "spec"
  ],
  "properties": {
    "apiVersion": {
      "description": "API version of the resource",
      "$ref": "#/definitions/V1AlphaApiVersion"
    },
    "kind": {
      "description": "The type of resource.",
      "$ref": "#/definitions/ReportLocationKind"
    },
    "metadata": {
      "description": "Standard set of options including name, description for the resource. Together `kind` and `metadata.name` are required to be unique. If there are duplicate, the resources \"closest\" to the execution dir will take precedence.",
      "$ref": "#/definitions/ModelMetadata"
    },
    "spec": {
      "description": "Options for the resource.",
      "$ref": "#/definitions/ReportLocationSpec"
    }
  },
  "additionalProperties": false,
  "definitions": {
    "DoctorCheckSpec": {
      "description": "What needs to be checked before the action will run. `paths` will be checked first, then `commands`. If a `path` matches no files or the matching files have changed, the `command` will run.",
      "type": "object",
      "properties": {
        "commands": {
          "description": "A list of commands to execute to check the environment.",
          "default": null,
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "nullable": true
        },
        "paths": {
          "description": "A list of globs to check for changes. When the glob matches a new file, or the contents of the file change, the check will require a fix.\n\nRelative paths are relative to the scope config directory containing the config file.\n\nShared configs can use the template string `{{ working_dir }}` to access the working directory.",
          "default": null,
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string"
          },
          "nullable": true
        }
      },
      "additionalProperties": false
    },
    "DoctorFixSpec": {
      "description": "Definition for fixing the environment.",
      "type": "object",
      "properties": {
        "commands": {
          "description": "List of commands to run to fix the env.",
          "default": [],
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "helpText": {
          "description": "Text to display when no command is provided / fails to fix the env.",
          "default": null,
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "helpUrl": {
          "description": "Link to documentation to fix the issue.",
          "default": null,
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        }
      },
      "additionalProperties": false
    },
    "DoctorGroupActionSpec": {
      "description": "An action is a single step used to check in a group. This is most commonly used to build a series of tasks for a system, like `ruby`, `python`, and databases.",
      "type": "object",
      "required": [
        "check"
      ],
      "properties": {
        "check": {
          "description": "The `check` run before `fix` (if provided). A check is used to determine if the fix needs to be executed, or fail the action if no fix is provided. If a fix is specified, the check will re-execute to ensure that the fix applied correctly.",
          "$ref": "#/definitions/DoctorCheckSpec"
        },
        "description": {
          "description": "A description of this specific action, used for information to the users.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "fix": {
          "description": "A fix defines how to fix the issue that a `check` is validating. When provided, will only run when the `check` \"fails\".",
          "anyOf": [
            {
              "$ref": "#/definitions/DoctorFixSpec"
            },
            {
              "type": "null"
            }
          ],
          "nullable": true
        },
        "name": {
          "description": "Name of the \"action\". When not provided, it will be the index of the action within the group. This is used when reporting status to the users.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "required": {
          "description": "If false, the action is allowed to fail and let other actions in the group execute. Defaults to `true`.",
          "default": true,
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "DoctorGroupKind": {
      "type": "string",
      "enum": [
        "ScopeDoctorGroup"
      ]
    },
    "DoctorGroupSpec": {
      "description": "Often used to describe how to fix a \"system\", like `ruby`, `python`, or databases. Able to depend on other \"system\".",
      "type": "object",
      "required": [
        "actions"
      ],
      "properties": {
        "actions": {
          "description": "A series of steps to check and fix for the group.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/DoctorGroupActionSpec"
          }
        },
        "include": {
          "description": "Change how a group is handled when building the dependency task graph. When set to `when-required`, the group will be ignored unless it's required by another dependency.",
          "default": "by-default",
          "$ref": "#/definitions/DoctorInclude"
        },
        "needs": {
          "description": "A list of `ScopeDoctorGroup` that are required for this group to execute. If not all finish successfully, this group will not execute.",
          "default": [],
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "reportExtraDetails": {
          "description": "defines additional data that needs to be pulled from the system when reporting a bug. `reportExtraDetails` is a map of `string:string`, the value is a command that should be run. When a report is built, the commands will be run and automatically included in the report.",
          "default": {},
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "DoctorInclude": {
      "description": "Configure how a groups will be used when determining the task graph.",
      "oneOf": [
        {
          "description": "Default option, the group will be included by default when determining which groups should run.",
          "type": "string",
          "enum": [
            "by-default"
          ]
        },
        {
          "description": "Useful for shared configuration. The group will not run unless another group depends on it.",
          "type": "string",
          "enum": [
            "when-required"
          ]
        }
      ]
    },
    "KnownErrorKind": {
      "type": "string",
      "enum": [
        "ScopeKnownError"
      ]
    },
    "KnownErrorSpec": {
      "description": "Definition of the known error",
      "type": "object",
      "required": [
        "help",
        "pattern"
      ],
      "properties": {
        "help": {
          "description": "Text that the user can use to fix the issue",
          "type": "string"
        },
        "pattern": {
          "description": "A Regex used to determine if the line is an error.",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "ModelMetadata": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "annotations": {
          "description": "Annotations attach arbitrary non-identifying metadata to objects.",
          "default": {
            "scope.github.com/bin-path": null,
            "scope.github.com/file-dir": null,
            "scope.github.com/file-path": null,
            "working_dir": null
          },
          "$ref": "#/definitions/ModelMetadataAnnotations"
        },
        "description": {
          "description": "Description of this resource, used when listing resources and helpful to inform users why the resource exists.",
          "default": "Description not provided",
          "type": "string"
        },
        "labels": {
          "description": "Key/value pairs, allows resources to be easily filtered from the CLI.",
          "default": {},
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "name": {
          "description": "Name of the resource, needs to be unique across `kinds`. When two resources share a name, the one \"closest\" to the current working directory will take precedence.",
          "type": "string"
        }
      }
    },
    "ModelMetadataAnnotations": {
      "type": "object",
      "properties": {
        "scope.github.com/bin-path": {
          "description": "When running commands, additional paths that should be paced at the _beginning_ of the `PATH`.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "working_dir": {
          "description": "The current working directory of the scope command, generated automatically.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        }
      }
    },
    "ReportDestinationGithubIssueSpec": {
      "description": "How to load the report to GitHub Issue",
      "type": "object",
      "required": [
        "owner",
        "repo"
      ],
      "properties": {
        "owner": {
          "description": "`owner` of the repository for the issue",
          "type": "string"
        },
        "repo": {
          "description": "`repo` the name of the repo for the issue",
          "type": "string"
        },
        "tags": {
          "description": "A list of tags to be added to the issue",
          "default": [],
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "ReportDestinationLocalSpec": {
      "description": "Create a report that is only local",
      "type": "object",
      "required": [
        "directory"
      ],
      "properties": {
        "directory": {
          "description": "Directory to put the report into",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "ReportDestinationRustyPasteSpec": {
      "description": "How to upload a report to RustyPaste",
      "type": "object",
      "required": [
        "url"
      ],
      "properties": {
        "url": {
          "description": "URL of RustyPaste",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "ReportDestinationSpec": {
      "oneOf": [
        {
          "type": "object",
          "required": [
            "rustyPaste"
          ],
          "properties": {
            "rustyPaste": {
              "$ref": "#/definitions/ReportDestinationRustyPasteSpec"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "githubIssue"
          ],
          "properties": {
            "githubIssue": {
              "$ref": "#/definitions/ReportDestinationGithubIssueSpec"
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": [
            "local"
          ],
          "properties": {
            "local": {
              "$ref": "#/definitions/ReportDestinationLocalSpec"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "ReportDestinationTemplates": {
      "type": "object",
      "properties": {
        "analyze": {
          "description": "Template to use when generating a bug without with analyze or intercept A Jinja2 style template, to be included. The text should be in Markdown format. Scope injects `command` as the command that was run.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "doctor": {
          "description": "Template to use when generating a bug report with `scope doctor` A Jinja2 style template, to be included. The text should be in Markdown format. Scope injects `command` as the command that was run.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        },
        "title": {
          "description": "Title to use when creating the issue. This is a Jinja2 style template. `entrypoint` is provided as a variable, which is the scope command run.",
          "type": [
            "string",
            "null"
          ],
          "nullable": true
        }
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "ReportLocationKind": {
      "type": "string",
      "enum": [
        "ScopeReportLocation"
      ]
    },
    "ReportLocationSpec": {
      "description": "Define where to upload the report to",
      "type": "object",
      "required": [
        "destination"
      ],
      "properties": {
        "additionalData": {
          "description": "defines additional data that needs to be pulled from the system when reporting a bug. `additionalData` is a map of `string:string`, the value is a command that should be run. When a report is built, the commands will be run and automatically included in the report.",
          "default": {},
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "destination": {
          "description": "Destination the report should be uploaded to",
          "$ref": "#/definitions/ReportDestinationSpec"
        },
        "templates": {
          "description": "Templates to use when uploading a report",
          "default": {
            "analyze": null,
            "doctor": null,
            "title": null
          },
          "$ref": "#/definitions/ReportDestinationTemplates"
        }
      },
      "additionalProperties": false
    },
    "V1AlphaApiVersion": {
      "description": "Version of the Scope API",
      "oneOf": [
        {
          "description": "Current latest version of the resources.",
          "type": "string",
          "enum": [
            "scope.github.com/v1alpha"
          ]
        }
      ]
    },
    "V1AlphaDoctorGroup": {
      "description": "Resource used to define a `ScopeDoctorGroup`.",
      "type": "object",
      "required": [
        "apiVersion",
        "kind",
        "metadata",
        "spec"
      ],
      "properties": {
        "apiVersion": {
          "description": "API version of the resource",
          "$ref": "#/definitions/V1AlphaApiVersion"
        },
        "kind": {
          "description": "The type of resource.",
          "$ref": "#/definitions/DoctorGroupKind"
        },
        "metadata": {
          "description": "Standard set of options including name, description for the resource. Together `kind` and `metadata.name` are required to be unique. If there are duplicate, the resources \"closest\" to the execution dir will take precedence.",
          "$ref": "#/definitions/ModelMetadata"
        },
        "spec": {
          "description": "Options for the resource.",
          "$ref": "#/definitions/DoctorGroupSpec"
        }
      },
      "additionalProperties": false
    },
    "V1AlphaKnownError": {
      "description": "Resource used to define a `ScopeKnownError`. A known error is a specific error that a user may run into.",
      "type": "object",
      "required": [
        "apiVersion",
        "kind",
        "metadata",
        "spec"
      ],
      "properties": {
        "apiVersion": {
          "description": "API version of the resource",
          "$ref": "#/definitions/V1AlphaApiVersion"
        },
        "kind": {
          "description": "The type of resource.",
          "$ref": "#/definitions/KnownErrorKind"
        },
        "metadata": {
          "description": "Standard set of options including name, description for the resource. Together `kind` and `metadata.name` are required to be unique. If there are duplicate, the resources \"closest\" to the execution dir will take precedence.",
          "$ref": "#/definitions/ModelMetadata"
        },
        "spec": {
          "description": "Options for the resource.",
          "$ref": "#/definitions/KnownErrorSpec"
        }
      },
      "additionalProperties": false
    },
    "V1AlphaReportLocation": {
      "description": "A `ScopeReportLocation` tells where to upload a report to.",
      "type": "object",
      "required": [
        "apiVersion",
        "kind",
        "metadata",
        "spec"
      ],
      "properties": {
        "apiVersion": {
          "description": "API version of the resource",
          "$ref": "#/definitions/V1AlphaApiVersion"
        },
        "kind": {
          "description": "The type of resource.",
          "$ref": "#/definitions/ReportLocationKind"
        },
        "metadata": {
          "description": "Standard set of options including name, description for the resource. Together `kind` and `metadata.name` are required to be unique. If there are duplicate, the resources \"closest\" to the execution dir will take precedence.",
          "$ref": "#/definitions/ModelMetadata"
        },
        "spec": {
          "description": "Options for the resource.",
          "$ref": "#/definitions/ReportLocationSpec"
        }
      },
      "additionalProperties": false
    }
  }
}