github.yaml

---
systems:
  github:
    description: |
      This system enables Honeydipper to integrate with `github`, so Honeydipper can
      react to github events and take actions on `github`.

    meta:
      configurations:
        - name: oauth_token
          description: The token or API ID used for making API calls to `github`
        - name: token
          description: >
            A token used for authenticate incoming webhook requests, every webhook request
            must carry a form field **Token** in the post body or url query that matches the value
        - name: path
          description: The path portion of the webhook url, by default :code:`/github/push`
        - name: tokenSource
          description: This is used for authentication with oauth2 jwt. The name maps to an entry defined in :code:`token_sources` of the **web** driver.

      notes:
        - For example
        - example: |
            ---
            systems:
              github:
                data:
                  oauth_token: ENC[gcloud-kms,...masked...]
                  token: ENC[gcloud-kms,...masked...]
                  path: "/webhook/github"
        - Assuming the domain name for the webhook server is :code:`myhoneydipper.com', you should
          configure the webhook in your repo with url like below
        - |
          .. code-block::

             https://myhoneydipper.com/webhook/github?token=...masked...

    data:
      oauth_token: _place_holder_
      token: _place_holder_
      path: "/github/push"

    functions:
      api:
        driver: web
        rawAction: request
        parameters:
          URL: https://api.github.com/{{ .ctx.resource_path }}
          header:
            Authorization: Bearer {{ coalesce .ctx.github_oauth_token .sysData.oauth_token }}
            Accept: application/vnd.github.v3+json
            Content-Type: application/json; charset=utf-8
          tokenSource: $?sysData.tokenSource

        description: >
          This is a generic function to make a github API call with the configured oauth_token. This
          function is meant to be used for defining other functions.

        meta:
          inputs:
            - name: resource_path
              description: This field is used as the path portion of the API call url

      createPR:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/repos/{{ .ctx.git_repo }}/pulls'
          method: POST
          content: $ctx.PR_content
        export:
          PR: '{{ .data.json }}'

        description: >
          This function will create a pull request with given infomation

        meta:
          inputs:
            - name: git_repo
              description: The repo that the new PR is for, e.g. :code:`myorg/myrepo`
            - name: PR_content
              description: The data structure to be passed to github for creating the PR, see `here <https://developer.github.com/v3/pulls/#input>`_ for detail

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      driver: webhook
                      if_match:
                        url: /createPR
                    do:
                      call_workflow: github_create_PR

                workflows:
                  github_create_PR:
                    call_function: github.createPR
                    with:
                      git_repo: myorg/myreop
                      PR_content:
                        title: update the data
                        head: mybranch
                        body: |
                          The data needs to be updated

                          This PR is created using honeydipper
      getRepo:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/repos/{{ .ctx.git_repo }}'
          method: GET
        export:
          repo: $data.json
          repoid: '{{ .data.json.id | int }}'

        description: >
          This function will query the detailed information about the repo.

        meta:
          inputs:
            - name: git_repo
              description: The repo that the query is for, e.g. :code:`myorg/myrepo`

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      driver: webhook
                      if_match:
                        url: /displayRepo
                    do:
                      call_workflow: query_repo

                workflows:
                  query_repo:
                    steps:
                      - call_function: github.getRepo
                        with:
                          git_repo: myorg/myreop
                      - call_workflow: notify
                        with:
                          message: The repo is created at {{ .ctx.repo.created_at }}

      createRepo:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/orgs/{{ .ctx.org }}/repos'
          method: POST
          content:
            name: $ctx.name
            private: $ctx.private,"false"
        export:
          repoid: '{{ .data.json.id | int }}'

        description: >
          This function will create a github repository for your org

        meta:
          inputs:
            - name: org
              description: the name of your org
            - name: name
              description: The name of your repository
            - name: private
              description: privacy of your repo, either true or false(it's default to false if not declared)

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      driver: webhook
                      if_match:
                        url: /createrepo
                    do:
                      call_workflow: github_create_repo

                workflows:
                  github_create_repo:
                    call_function: github.createRepo
                    with:
                      org: testing
                      name: testing-repo

      addRepoToInstallation:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/user/installations/{{ .ctx.installationid }}/repositories/{{ .ctx.repoid }}'
          method: PUT
          header:
            Accept: application/vnd.github.v3+json, application/vnd.github.machine-man-preview+json
            Content-Type: application/json; charset=utf-8

        description: >
          This function will add a repo into an installed github app

        meta:
          inputs:
            - name: installation_id
              description: The installation_id of your github app
            - name: repoid
              description: The Id of your github repository

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      driver: webhook
                      if_match:
                        url: /addrepoinstallation
                    do:
                      call_workflow: github_add_repo_installation

                workflows:
                  github_add_repo_installation:
                    call_function: github.addRepoToInstallation
                    with:
                      repoid: 12345678
                      intallationid: 12345678

      removeRepoFromInstallation:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/user/installations/{{ .ctx.installationid }}/repositories/{{ .ctx.repoid }}'
          method: DELETE
          header:
            Accept: application/vnd.github.v3+json, application/vnd.github.machine-man-preview+json
            Content-Type: application/json; charset=utf-8

        description: >
          This function will remove a repo from an installed github app

        meta:
          inputs:
            - name: installation_id
              description: The installation_id of your github app
            - name: repoid
              description: The Id of your github repository

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      driver: webhook
                      if_match:
                        url: /removerepoinstallation
                    do:
                      call_workflow: github_remove_repo_installation

                workflows:
                  github_remove_repo_installation:
                    call_function: github.removeRepoFromInstallation
                    with:
                      repoid: 12345678
                      intallationid: 12345678

      createStatus:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/repos/{{ .ctx.git_repo }}/statuses/{{ .ctx.git_commit }}'
          method: POST
          content: '{{ set .ctx.status "context" (coalesce .ctx.context .sysData.context "Honeydipper") | toJson }}'

        description: >
          This function will create a commit status on the given commit.

        meta:
          inputs:
            - name: git_repo
              description: The repo that commit is for, e.g. :code:`myorg/myrepo`
            - name: git_commit
              description: The short commit hash for the commit the status is for
            - name: context
              description: the status context, a name for the status message, by default :code:`Honeydipper`
            - name: status
              description: the status data structure according github API `here <https://developer.github.com/v3/repos/statuses/#parameters>`_

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      source:
                        system: github
                        trigger: push
                    do:
                      if_match:
                        git_repo: myorg/myrepo
                        git_ref: ref/heads/testbranch
                      call_workflow: post_status

                workflows:
                  post_status:
                    call_function: github.createStatus
                    with:
                      # the git_repo is available from event export
                      # the git_commit is available from event export
                      status:
                        state: pending
                        description: Honeydipper is scanning your commit ...

      createComment:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/repos/{{ .ctx.git_repo }}/issues/{{ .ctx.git_issue }}/comments'
          method: POST
          content: '{{ dict "body" .ctx.message | toJson }}'

        description: >
          This function will create a comment on the given PR

        meta:
          inputs:
            - name: git_repo
              description: The repo that commit is for, e.g. :code:`myorg/myrepo`
            - name: git_issue
              description: The issue number of the PR
            - name: message
              description: The content of the comment to be posted to the PR

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      source:
                        system: github
                        trigger: pull_request
                    do:
                      if_match:
                        git_repo: myorg/myrepo
                        git_ref: master
                      call_function: github.createComment
                      with:
                        # the git_repo is available from event export
                        # the git_issue is available from event export
                        message: type `honeydipper help` to see a list of available commands

      getContent:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/repos/{{ .ctx.git_repo }}/contents/{{ .ctx.path }}{{ if .ctx.git_ref }}?ref={{ .ctx.git_ref }}{{ end }}'
          method: GET
        export:
          file_content: '{{ b64dec .data.json.content }}'

        description: >
          This function will fetch a file from the specified repo and branch.

        meta:
          inputs:
            - name: git_repo
              description: The repo from where to download the file, e.g. :code:`myorg/myrepo`
            - name: git_ref
              description: The branch from where to download the file, no :code:`ref/heads/` prefix, e.g. :code:`master`
            - name: path
              description: The path for fetching the file, no slash in the front, e.g. :code:`conf/nginx.conf`

          exports:
            - name: file_content
              description: The file content as a string

          notes:
            - See below for example
            - example: |
                ---
                workflows:
                  fetch_circle:
                    call_function: github.getContent
                    with:
                      git_repo: myorg/mybranch
                      git_ref: master
                      path: .circleci/config.yml
                    export:
                      circleci_conf: :yaml:{{ .ctx.file_content }}

      mergeBranch:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/repos/{{ .ctx.git_repo }}/merges'
          method: POST
          content:
            base: $ctx.base_branch
            head: $ctx.head_branch
            commit_message: $ctx.commit_message
        export_on_success:
          merge_commit_sha: $data.json.sha,""

        description: >
          This function will merge the head branch into base branch with a merge commit.

        meta:
          inputs:
            - name: git_repo
              description: The repo where the merge operation takes place, e.g. :code:`myorg/myrepo`
            - name: base_branch
              description: The base branch to merge into, no :code:`refs/heads/` prefix, e.g. :code:`main` or :code:`staging` etc.
            - name: head_branch
              description: The head branch where the changes are, e.g. :code:`my-patch`, :code:`fix-issue-123` etc.
            - name: commit_message
              description: The message for the merge commit. for example :code:`merged by Honeydipepr`

          exports:
            - name: merge_commit_sha
              description: The sha for the merge commit.

          notes:
            - See below for example
            - example: |
                ---
                workflows:
                  merge_work_branch:
                    call_function: github.mergeBranch
                    with:
                      git_repo: myorg/mybranch
                      base_branch: main
                      head_branch: mywork
                      commit_messga: |
                        chore(release): release

                        Work is done. Released!

      getCommit:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/repos/{{ .ctx.git_repo }}/commits/{{ .ctx.git_ref }}'
          method: GET
        export_on_success:
          git_commit_full: $data.json.sha
          git_commit: '{{ .data.json.sha | trunc 7 }}'
          git_commit_message: $data.json.commit.message
          git_commit_info: $data.json

        description: >
          This function will get the commit info for a git ref, a commmit hash, a branch or a tag.

        meta:
          inputs:
            - name: git_repo
              description: The repo where the commit is for, e.g. :code:`myorg/myrepo`
            - name: git_ref
              description: A commit hash, a branch ref or a tag ref, with prefix :code:`refs/`, e.g. :code:`refs/heads/main` etc.

          exports:
            - name: git_commit_full
              description: The git commit full sha for the new commit.
            - name: git_commit
              description: The short git commit sha for the commit.
            - name: git_commit_message
              description: The commit message for the commit.
            - name: git_commit_info
              description: The whole commit info data structure.

          notes:
            - See below for example
            - example: |
                ---
                workflows:
                  getCommitInfo:
                    with:
                      git_repo: myorg/myrepo
                    steps:
                      - call_function: github.getCommit
                        with:
                          git_ref: heads/mybranch

      updateRef:
        target:
          system: github
          function: api
        parameters:
          URL: 'https://api.github.com/repos/{{ .ctx.git_repo }}/git/{{ .ctx.git_ref }}'
          method: PATCH
          content:
            sha: $ctx.git_commit_full
            force: false

        description: >
          This function will update the ref to point to a new commit, in other words, push the new commit into the branch.
          No force push is allowed, so there is no overwriting.

        meta:
          inputs:
            - name: git_repo
              description: The repo where the update takes place, e.g. :code:`myorg/myrepo`
            - name: git_ref
              description: The ref/branch to be updated, must with prefix :code:`refs/heads/`, e.g. :code:`refs/heads/main` or :code:`refs/heads/staging` etc.
            - name: git_commit_full
              description: The git commit full sha for the new commit.

          notes:
            - See below for example
            - example: |
                ---
                workflows:
                  releaseStagingToMain:
                    with:
                      git_repo: myorg/mybranch
                    steps:
                      - call_function: github.mergeBranch
                        with:
                          base_branch: main
                          head_branch: staging
                          commit_messga: |
                            chore(release): release

                            Test is done. Released!
                      - call_function: github.updateRef
                        with:
                          git_ref: refs/heads/staging
                          git_commit_full: $ctx.merge_commit_sha

    triggers:
      hit:
        driver: webhook
        if_match:
          method: POST
          form:
            token: '{{ .sysData.token }}'
          url: '{{ .sysData.path }}'
        description: >
          This is a catch all event for github webhook requests. It is not to be used
          directly, instead should be used as source for defining other triggers.

      commit_status:
        source:
          system: github
          trigger: hit
        if_match:
          headers:
            X-Github-Event: status
          json:
            state: success
        export:
          git_repo: $event.json.repository.full_name
          branches: $event.json.branches
          git_commit: '{{ .event.json.sha | trunc 7 }}'
          git_commit_full: $event.json.sha
          git_commit_message: $event.json.commit.commit.message
          git_status_state: $event.json.state
          git_status_context: $event.json.context
          git_status_description: $event.json.description
          github_commit_status: $event.json
          _event_id: '{{ .event.json.sha | trunc 7 }}'
          _event_url: $event.json.target_url
          _event_detail: |-

            *Repo: {{ .event.json.repository.full_name }}*
            • `{{ .event.json.sha | trunc 7 }}` *{{ .event.json.context }}: {{ .event.json.state }}*
            {{ .event.json.description }}

        description: This is triggered when a **github** commit status is updated.
        meta:
          matching_parameters:
            - name: .json.repository.full_name
              description: Specify this in the :code:`when` section of the rule using :code:`if_match`, to filter the events for the repo
            - name: .json.branches.name
              description: This field is to match only the status events happened on certain branches
            - name: .json.context
              description: "This field is to match only the status events with certain check name, e.g. :code:`ci/circleci: yamllint`"
            - name: .json.state
              description: This field is to match only the status events with certain state, :code:`pending`, :code:`success`(default), :code:`failure` or :code:`error`
          exports:
            - name: git_repo
              description: This context variable will be set to the name of the repo, e.g. :code:`myorg/myrepo`
            - name: branches
              description: A list of branches that contain the commit
            - name: git_commit
              description: This context variable will be set to the short (7 characters) commit hash of the head commit of the push
            - name: git_status_state
              description: This context variable will be set to the state of the status, e.g. :code:`pending`, :code:`success`, :code:`failure` or :code:`error`
            - name: git_status_context
              description: "This context variable will be set to the name of the status, e.g. :code:`ci/circleci: yamllint`"
            - name: git_status_description
              description: This context variable will be set to the description of the status, e.g. :code:`Your tests passed on CircleCI!`
          notes:
            - See below snippet for example
            - example: |
                ---
                rules:
                  - when:
                      source:
                        system: github
                        trigger: commit_status
                      if_match:
                        json:
                          repository:
                            full_name: myorg/myrepo # .json.repository.full_name
                          branches:
                            name: main              # .json.branches.name
                          context: mycheck          # .json.context
                          state: success            # .json.state
                    do:
                      call_workflow: do_something
                      # following context variables are available
                      #   git_repo
                      #   branches
                      #   git_commit
                      #   git_status_state
                      #   git_status_context
                      #   git_status_description
                      #

      push:
        source:
          system: github
          trigger: hit
        if_match:
          headers:
            X-Github-Event: push
        export:
          git_repo: $event.json.repository.full_name
          git_ref: $event.json.ref
          git_commit_full: $event.json.head_commit.id
          git_commit: '{{ .event.json.head_commit.id | trunc 7 }}'
          commits: $event.json.commits
          _event_id: '{{ .event.json.head_commit.id | trunc 7 }}'
          _event_url: $event.json.head_commit.url
          _event_detail: |-

            *Repo: {{ .event.json.repository.full_name }}   Branch: {{ .event.json.ref | base }}*
            {{- range .event.json.commits }}
            • `{{ .id | trunc 7 }}`: {{ .message | abbrev 40 }}
            {{- end }}

        description: This is triggered when **github** receives a push.
        meta:
          matching_parameters:
            - name: .json.repository.full_name
              description: Specify this in the :code:`when` section of the rule using :code:`if_match`, to filter the push events for the repo
            - name: .json.ref
              description: This field is to match only the push events happened on certain branch
          exports:
            - name: git_repo
              description: This context variable will be set to the name of the repo, e.g. :code:`myorg/myrepo`
            - name: git_ref
              description: This context variable will be set to the name of the branch, e.g. :code:`ref/heads/mybrach`
            - name: git_commit
              description: This context variable will be set to the short (7 characters) commit hash of the head commit of the push
          notes:
            - See below snippet for example
            - example: |
                ---
                rules:
                  - when:
                      source:
                        system: github
                        trigger: push
                      if_match:
                        json:
                          repository:
                            full_name: myorg/myrepo # .json.repository.full_name
                          ref: ref/heads/mybranch   # .json.ref
                    do:
                      call_workflow: do_something
                      # following context variables are available
                      #   git_repo
                      #   git_ref
                      #   git_commit
                      #
            - Or, you can match the conditions in workflow using exported context variables instead of in the rules
            - example: |
                ---
                rules:
                  - when:
                      source:
                        system: github
                        trigger: push
                    do:
                      if_match:
                        - git_repo: mycompany/myrepo
                          git_ref: ref/heads/master
                        - git_repo: myorg/myfork
                          git_ref: ref/heads/mybranch
                      call_workflow: do_something

      release_published:
        source:
          system: github
          trigger: hit
        if_match:
          headers:
            X-Github-Event: release
          json:
            action: published
        export:
          git_repo: $event.json.repository.full_name
          git_tag: $event.json.release.tag_name
          _event_id: $event.json.release.tag_name
          _event_url: $event.json.release.url
          _event_detail: |-

            *Repo: {{ .event.json.repository.full_name }}*
            *Release: {{ .event.json.release.name }}*
            {{ .event.json.release.body }}

        description: This is triggered when a new release is published.
        meta:
          matching_parameters:
            - name: .json.repository.full_name
              description: This field is to match only the pull requests from certain repo
            - name: .json.release.tag_name
              description: >
                This field can be used for pattern matching the tag names. Note that, It does not include the
                prefix :code:`ref/heads/` (different from push event).
          exports:
            - name: git_repo
              description: This context variable will be set to the name of the repo, e.g. :code:`myorg/myrepo`
            - name: git_tag
              description: This context variable will be set to the name of the tag, e.g. :code:`v1.3.3`
          notes:
            - See below snippet for example
            - example: |
                ---
                rules:
                  - when:
                      source:
                        system: github
                        trigger: release_published
                      if_match:
                        json:
                          repository:
                            full_name: myorg/myrepo # .json.repository.full_name
                          release:
                            tag_name: ':regex:v[0-9]*[02468]\.' # matching only even major version number
                    do:
                      call_workflow: do_something
                      # following context variables are available
                      #   git_repo
                      #   git_tag

      pull_request:
        source:
          system: github
          trigger: hit
        if_match:
          headers:
            X-Github-Event: pull_request
          json:
            action: opened
        export:
          git_issue: $event.json.number
          git_repo: $event.json.repository.full_name
          git_ref: $event.json.pull_request.base.ref
          git_commit: $event.json.pull_request.head.sha
          git_title: $event.json.pull_request.title
          git_user: $event.json.pull_request.user
          _event_id: '#{{ .event.json.number }}'
          _event_url: $event.json.pull_request.html_url
          _event_detail: |-

            *PR Repo: {{ .event.json.repository.full_name }}   Base: {{ .event.json.pull_request.base.ref | base }}   Head: {{ .event.json.pull_request.head.ref | base }}*
            Title: `{{ .event.json.pull_request.title }}`
            By: `{{ .event.json.pull_request.user.login }}`

        description: This is triggered when a new pull request is created
        meta:
          matching_parameters:
            - name: .json.repository.full_name
              description: This field is to match only the pull requests from certain repo
            - name: .json.pull_request.base.ref
              description: >
                This field is to match only the pull requests made to certain base branch,
                note that the ref value here does not have the :code:`ref/heads/` prefix (different from push event). So
                to match master branch, just use :code:`master` instead of :code:`ref/heads/master`.
            - name: .json.pull_request.user.login
              description: This field is to match only the pull requests made by certain user
          exports:
            - name: git_repo
              description: This context variable will be set to the name of the repo, e.g. :code:`myorg/myrepo`
            - name: git_ref
              description: This context variable will be set to the name of the branch, e.g. :code:`mybrach`, no :code:`ref/heads/` prefix
            - name: git_commit
              description: This context variable will be set to the short (7 characters) commit hash of the head commit of the PR
            - name: git_user
              description: This context variable will be set to the user object who created the PR
            - name: git_issue
              description: This context variable will be set to the issue number of the PR
            - name: git_title
              description: This context variable will be set to the title of the PR
          notes:
            - See below snippet for example
            - example: |
                ---
                rules:
                  - when:
                      source:
                        system: github
                        trigger: pull_request
                      if_match:
                        json:
                          repository:
                            full_name: myorg/myrepo # .json.repository.full_name
                          pull_request:
                            base:
                              ref: master           # .json.pull_request.base.ref
                    do:
                      call_workflow: do_something
                      # following context variables are available
                      #   git_repo
                      #   git_ref
                      #   git_commit
                      #   git_issue
                      #   git_title
                      #   git_user
                      #

      pr_comment:
        source:
          system: github
          trigger: hit
        if_match:
          headers:
            X-Github-Event: issue_comment
          json:
            action: created
            issue:
              pull_request:
                url: :regex:.+
        export:
          git_issue: $event.json.issue.number
          git_repo: $event.json.repository.full_name
          git_message: $event.json.comment.body
          git_user: $event.json.comment.user

        description: This is triggered when a comment is added to a  pull request.
        meta:
          matching_parameters:
            - name: .json.repository.full_name
              description: This field is to match only the pull requests from certain repo
            - name: .json.comment.user.login
              description: This is to match only the comments from certain username
            - name: .json.comment.author_association
              description: >
                This is to match only the comments from certain type of user. See github API reference
                `here <https://developer.github.com/v4/enum/commentauthorassociation/>`_ for detail.
            - name: .json.comment.body
              description: >
                This field contains the comment message, you can use regular express pattern
                to match the content of the message.
          exports:
            - name: git_repo
              description: This context variable will be set to the name of the repo, e.g. :code:`myorg/myrepo`
            - name: git_user
              description: This context variable will be set to the user object who made the comment
            - name: git_issue
              description: This context variable will be set to the issue number of the PR
            - name: git_message
              description: This context variable will be set to the comment message
          notes:
            - See below snippet for example
            - example: |
                ---
                rules:
                  - when:
                      source:
                        system: github
                        trigger: pr_commented
                      if_match:
                        json:
                          repository:
                            full_name: myorg/myrepo # .json.repository.full_name
                          comment:
                            autho_association: CONTRIBUTOR
                            body: ':regex:^\s*terraform\s+plan\s*$'
                    do:
                      call_workflow: do_terraform_plan
                      # following context variables are available
                      #   git_repo
                      #   git_issue
                      #   git_message
                      #   git_user
                      #

rules:
  - when:
      source:
        system: github
        trigger: hit
    do:
      context: mute
      description: no op