Skip to content

Specifications

Jump to bottom
Kirill edited this page Mar 28, 2021 · 6 revisions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Gitsrap works mostly with resource specification yaml documents. Each file should contain at least one document and may contain multiple documents separated by --- yaml document separator.

Each specification document is a yaml mapping, it consists of these keys:

  • version - specification document version
  • kind - specification kind
  • metadata - specification metadata
  • spec - resource specification

Version should be v2. Kind is a string which describes the specification kind, it must be one of:

A spec may have selector key to attach to the correct resource.

Metadata is differ for specification, but most of them has these keys:

  • name - resource name (e.g. repository name or organization name)
  • id - resource ID (e.g. repository, webhook, organization ID)
  • owner - resource owner, e.g. repository owner

Repository

Describes GitHub repository resource, it has:

  • description (string) - repository description
  • homepage (string) - repository home page URI
  • defaultBranch (string, default: "master") - the name of the default branch
  • mergeStrategy (list of strings, default: [merge]) - pull request merge options, could be one of:
    • merge - enable merge commits PR merging
    • rebase - enable rebase PR merge
    • squash - enable squash PR merge
  • deleteBranchOnMerge (bool) - enables delete branch options on PR merge
  • topics (list of strings) - repository topics, keywords in GitHub page description
  • archived (bool, readonly) - true if repsitory is archived
  • disabled (bool, readonly) - true if repository is disabled
  • license (string) - license GitHub key, e.g. (mit)
  • visibility (string. default: "public") - one of:
    • public - repository is public
    • private - repository is private
  • features (list of strings) - enables repository features:
    • issues - enable issues
    • wiki - enable wiki pages
    • pages - enable GitHub pages
    • projects - enable repository project board
    • downloads - ???

Repository metadata must specify repository name, and may have owner, in case if owner is not a current user (current user = token owner). When updating existing repository, metadata must contain id of the repository. The full metadata could be fetched with get command.

Example:

version: v2.0-alpha
kind: Repository
metadata:
    name: gitstrap
    owner: g4s8
    id: 12345
spec:
    description: CLI for managing GitHub repositories
    defaultBranch: master
    mergeStrategy:
        - squash
    deleteBranchOnMerge: true
    topics:
        - cli
        - git
        - github
        - webhooks
    license: mit
    visibility: public
    features:
        - issues
        - pages
        - wiki
        - downloads

Organization

Describes GitHub organization, it has:

  • name (string) - the shorthand name of the company.
  • description (string) - organization description
  • company (string) - organization company affiliation
  • blog (string) - URI for organization blog
  • location (string) - geo location of organization
  • email (string) - public email address
  • twitter (string) - twitter account username
  • verified (bool, readonly) - true if organization was verified by GitHub

Example:

version: v2.0-alpha
kind: Organization
metadata:
    name: artipie
    id: 12345
spec:
    name: Artipie
    description: Binary Artifact Management Toolkit
    blog: https://www.artipie.com
    email: team@artipie.com
    verified: true

WebHook

Describes repository or organization web-hook. It has:

  • url (string, required) - webhook URL
  • contentType (string, required) - one of:
    • json - send JSON payloads
    • form - send HTTP form payloads
  • events (list of strings, required) - list of GitHub events to trigger web-hook
  • insecureSsl (bool, default: false) - if true, disable SSL certificate verification
  • secret (string, writeonly) - specify secret payload when creating or updating the hook
  • active (bool, default: true) - if false, the hook will be disabled but now removed
  • selector (mapping, required) - specifies hook selector. It must have only one of two keys, either:
    • repository - the name of repository for this hook
    • organization - the name of organization for this hook

Metadata:

  • owner (string, optional) - may specify the owner of the repository if hook's selector is repository and repository owner is not a current user
  • id (number, required on update) - it must be specified to update existing web-hook, if not specified a new hook will be created. It could be fetched with get command.

Example:

version: v2.0-alpha
kind: WebHook
metadata:
    owner: g4s8
    id: 12345
spec:
    url: http://example.com/hook
    contentType: json
    events:
        - pull_request
    active: true
    selector:
        repository: gitstrap
Clone this wiki locally