circleci.yaml

---
systems:
  circleci:
    description: |
      This system enables Honeydipper to integrate with `circleci`, so Honeydipper can
      trigger pipelines in `circleci`.

    meta:
      configurations:
        - name: circle_token
          description: The token for making API calls to `circleci`.
        - name: url
          description: The base url of the API calls, defaults to :code:`https://circleci.com/api/v2`
        - name: org
          description: The default org name

    data:
      circle_token: _place_holder_
      url: https://circleci.com/api/v2
      org: _place_holder_

    functions:
      api:
        driver: web
        rawAction: request
        parameters:
          URL: '{{ .sysData.url }}/{{ .ctx.request_path }}'
          header:
            Circle-Token: $sysData.circle_token
            Accept: application/json
            Content-Type: application/json; charset=utf-8

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

      add_env_var:
        target:
          system: circleci
          function: api
        parameters:
          URL: '{{ .sysData.url }}/project/{{ default "gh" .ctx.vcs }}/{{ coalesce .ctx.git_repo (print .sysData.org "/" .ctx.repo) }}/envvar'
          method: POST
          content:
            name: $ctx.name
            value: $ctx.value

        description: >
          Add env var to a project.

        meta:
          inputs:
            - name: vcs
              description: The VCS system integrated with this circle project, :code:`github` (default) or :code:`bitbucket`.
            - name: git_repo
              description: The repo that the env var is for, e.g. :code:`myorg/myrepo`, takes precedent over :code:`repo`.
            - name: repo
              description: The repo name that the env var is for, without the org, e.g. :code:`myrepo`
            - name: name
              description: Env var name
            - name: value
              description: Env var value

      start_pipeline:
        target:
          system: circleci
          function: api
        parameters:
          URL: '{{ .sysData.url }}/project/{{ default "gh" .ctx.vcs }}/{{ coalesce .ctx.git_repo  (print .sysData.org "/" .ctx.repo) }}/pipeline'
          method: POST
          content:
            branch: $ctx.git_branch
            parameters: ':yaml:{{ set (default (dict) .ctx.pipeline_parameters) "via" (dict "honeydipper" "true") | toJson }}'

        description: >
          This function will trigger a pipeline in the given circleci project and branch.

        meta:
          inputs:
            - name: vcs
              description: The VCS system integrated with this circle project, :code:`github` (default) or :code:`bitbucket`.
            - name: git_repo
              description: The repo that the pipeline execution is for, e.g. :code:`myorg/myrepo`, takes precedent over :code:`repo`.
            - name: repo
              description: The repo name that the pipeline execution is for, without the org, e.g. :code:`myrepo`
            - name: git_branch
              description: The branch that the pipeline execution is on.
            - name: pipeline_parameters
              description: The parameters passed to the pipeline.

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      driver: webhook
                      if_match:
                        url: /from_circle
                      export:
                        git_repo: $event.form.git_repo.0
                        git_branch: $event.form.git_branch.0
                        ci_workflow: $event.form.ci_workflow.0
                    do:
                      call_workflow: process_and_return_to_circle

                workflows:
                  process_and_return_to_circle:
                    on_error: continue
                    steps:
                      - call_workflow: $ctx.ci_workflow
                        export_on_success:
                          pipeline_parameters:
                            deploy_success: "true"
                      - call_function: circleci.start_pipeline

            - "Your :code:`circleci.yaml` might look like below"
            - example: |
                ---
                jobs:
                  version: 2
                  deploy:
                    unless: << pipeline.parameters.via.honeydipper >>
                    steps:
                      - ...
                      - run: curl <honeydipper webhook> # trigger workflow on honeydipper
                  continue_on_success:
                    when: << pipeline.parameters.deploy_success >>
                    steps:
                      - ...
                      - run: celebration
                  continue_on_failure:
                    when:
                      and:
                        - << pipeline.parameters.via.honeydipper >>
                        - not: << pipeline.parameters.deploy_success >>
                    steps:
                      - ...
                      - run: recovering
                      - run: # return error here

                workflows:
                  version: 2
                  deploy:
                    jobs:
                      - deploy
                      - continue_on_success
                      - continue_on_failure
                  filters:
                    branches:
                      only: /^main$/
            - |
              For detailed information on conditional jobs and workflows please see the
              `circleci support document <https://support.circleci.com/hc/en-us/articles/360043638052-Conditional-steps-in-jobs-and-conditional-workflows>`_.

      create_context:
        target:
          system: circleci
          function: api
        parameters:
          URL: '{{ .sysData.url }}/context'
          method: POST
          content:
            name: $ctx.circleci_context_name
            owner:
              slug: '{{ default "gh" .sysData.vcs }}/{{ .sysData.org }}'
              type: '$sysData.owner-type,"organization"'
        export:
          circleci_context: $data.json

        description: >
          This function will create a new context with the given name.

        meta:
          inputs:
            - name: circleci_context_name
              description: The name of the context to create.

      list_context:
        target:
          system: circleci
          function: api
        parameters:
          URL: '{{ .sysData.url }}/context'
          method: GET
          form:
            owner-slug: '{{ default "gh" .sysData.vcs }}/{{ .sysData.org }}'
            owner-type: '$sysData.owner-type,"organization"'
            page-token: $?ctx.circleci-api-page-token
        export:
          circleci_contexts_page: $?data.json.items
          circleci-api-page-token: $?data.json.next_page_token

        description: >
          This function will return a list of contexts owned by the owner.
          Please use the workflow to manage the pagination.

        meta:
          inputs:
            - name: circleci-api-page-token
              description: Continue the query after a page break.

      put_context_variable:
        target:
          system: circleci
          function: api
        parameters:
          URL: '{{ .sysData.url }}/context/{{ with .ctx.circleci_context }}{{ .id }}{{ else }}{{ .ctx.circleci_context_id }}{{ end }}/environment-variable/{{ .ctx.circleci_var.name }}'
          method: PUT
          content:
            value: '$ctx.circleci_var.value'

        description: >
          This function will add a new secret variable to the named context.

        meta:
          inputs:
            - name: circleci_context.id
              description: The UUID of the context in your org.
            - name: circleci_context_id
              description: The UUID of the context in your org, only used when :code:`circleci_context.id` is not available.
            - name: circleci_var.name
              description: The name of the variable.
            - name: circleci_var.value
              description: The value of the variable.

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      driver: webhook
                      if_match:
                        url: /from_circle
                      export:
                        circleci_context_id: $event.form.context.0
                        circleci_var:
                          name: $event.form.var.0
                          value: $event.form.value.0
                    do:
                      call_workflow: add_variable_circle

                workflows:
                  add_variable_circle:
                    call_function: circleci.put_context_variable

      put_project_variable:
        target:
          system: circleci
          function: api
        parameters:
          URL: '{{ .sysData.url }}/project/{{ default "gh" .ctx.vcs }}/{{ coalesce .ctx.git_repo  (print .sysData.org "/" .ctx.repo) }}/envvar'
          method: POST
          content:
            name: '$ctx.circleci_var.name'
            value: '$ctx.circleci_var.value'

        description: >
          This function will add a new secret variable to the named context.

        meta:
          inputs:
            - name: vcs
              description: The VCS system integrated with this circle project, :code:`github` (default) or :code:`bitbucket`.
            - name: git_repo
              description: The repo that the secret variable is for, e.g. :code:`myorg/myrepo`, takes precedent over :code:`repo`.
            - name: repo
              description: The repo name that the secret variable is for, without the org, e.g. :code:`myrepo`
            - name: circleci_var.name
              description: The name of the variable.
            - name: circleci_var.value
              description: The value of the variable.

          notes:
            - See below for example
            - example: |
                ---
                rules:
                  - when:
                      driver: webhook
                      if_match:
                        url: /from_circle
                      export:
                        git_repo: $event.form.git_repo.0
                        circleci_var:
                          name: $event.form.var.0
                          value: $event.form.value.0
                    do:
                      call_workflow: add_variable_circle

                workflows:
                  add_variable_circle:
                    call_function: circleci.put_project_variable
                    with:
                      vcs: gh

workflows:
  circleci_pipeline:
    call_function: circleci.start_pipeline

    description: This workflows wrap around the :code:`circleci.start_pipeline` function so it can be used as a hook.

    meta:
      notes:
        - For example, below workflow uses a hook to invoke the pipeline.
        - example: |
            ---
            rules:
              - when:
                  driver: webhook
                  if_match:
                    url: /from_circle
                  export:
                    git_repo: $event.form.git_repo.0
                    git_branch: $event.form.git_branch.0
                    ci_workflow: $event.form.ci_workflow.0
                do:
                  call_workflow: process_and_return_to_circle

            workflows:
              process_and_return_to_circle:
                with:
                  hooks:
                    on_exit+:
                      - circleci_pipeline
                steps:
                  - call_workflow: $ctx.ci_workflow
                    export_on_success:
                      pipeline_parameters:
                        deploy_success: "true"

  circleci_list_context:
    no_export:
      - circleci_end_of_list
      - circleci-api-page-token
      - circleci_contexts_page
    until_match:
      circleci_end_of_list: "true"
    steps:
      - call_function: '{{ default "circleci" .ctx.circleci_system }}.list_context'
        export:
          circleci_end_of_list: '{{ get .ctx "circleci-api-page-token" | empty }}'
          circleci_contexts+: $?ctx.circleci_contexts_page

    description: >
      This workflows wrap around the :code:`circleci.list_context` function so
      multiple page of results can be combined.
    meta:
      notes:
        - For example,
        - example: |
            ---
            system:
              my_circleci:
                extends:
                  - circleci
                data:
                  token: xxx
                  org: myorg
                  vcs: gh
                  owner-type: account

            workflows:
              test:
                call_workflow: circleci_list_context
                with:
                  circleci_system: my_circleci

  circleci_get_context:
    steps:
      - call_workflow: circleci_list_context
        export:
          circleci_context: '{{ $ret := .nil }}{{ range .ctx.circleci_contexts }}{{ if eq .name $.ctx.circleci_context_name }}{{ $ret = . }}{{ end }}{{ end }}{{ return $ret }}'
      - if:
          - '{{ empty .ctx.circleci_context }}'
          - '{{ not (empty .ctx.circleci_create_missing_context) }}'
        call_function: '{{ default "circleci" .ctx.circleci_system }}.create_context'

    description: >
      This workflows wrap around the :code:`circleci.list_context` function so
      get the detail of a context with name :code:`circleci_context_name`. You
      can use :code:`circleci_create_missing_context` flag to ensure a context
      is created if needed.
    meta:
      notes:
        - For example,
        - example: |
            ---
            system:
              my_circleci:
                extends:
                  - circleci
                data:
                  token: xxx
                  org: myorg
                  vcs: gh
                  owner-type: account

            workflows:
              with:
                circleci_system: my_circleci
                circleci_context_name: my_context
              steps:
                - call_workflow: circleci_get_context
                - call_function: my_circleci.put_context_variable
                  with:
                    circle_var:
                      name: foo
                      value: bar