Merge pull request #323 from merico-dev/feat-output-ref

feat: add plugin outputs reference

Author: daniel-hutao

docs/plugins/trello-github-integ_plugin.md

@@ -1,23 +1,10 @@
 ## 1 `trello-github-integ` Plugin
 
-This plugin creates a new Trello board and integrate it with your GitHub repo.
+This plugin creates a new GitHub Actions workflow(trello-github-integration) and uploads it to your GitHub repo.
 
 ## 2 Usage:
 
-_This plugin depends on the following two environment variables:_
-
-- TRELLO_API_KEY
-- TRELLO_TOKEN
-
-Set the values accordingly before using this plugin.
-
-If you don't know how to create these two tokens, check out:
-- [Generate a Trello API key and token](https://docs.servicenow.com/bundle/quebec-it-asset-management/page/product/software-asset-management2/task/generate-trello-apikey-token.html)
-
-## 3 Tips:
-_Trello board description is managed by DevStream, please don't modify it._
-
-To create a Trello API key and token, see [here](https://docs.servicenow.com/bundle/quebec-it-asset-management/page/product/software-asset-management2/task/generate-trello-apikey-token.html).
+_This plugin depends on the plugin `trello`:_
 
 ```yaml
 tools:
@@ -30,20 +17,58 @@ tools:
     # checkout the version from the GitHub releases
     version: 0.2.0
   # optional; if specified, dtm will make sure the dependency is applied first before handling this tool.
-  dependsOn: [ "TOOL1_NAME.TOOL1_KIND", "TOOL2_NAME.TOOL2_KIND" ]
+  dependsOn: [ "TRELLO_INSTANCE_NAME.trello" ]
   # options for the plugin
   options:
     # the repo's owner. It should be case-sensitive here; strictly use your GitHub user name; please change the value below.
     owner: YOUR_GITHUB_USERNAME
     # the repo where you'd like to setup GitHub Actions; please change the value below.
     repo: YOUR_REPO_NAME
-    # integration tool name
-    api:
-      name: trello
-      # name of the Trello kanban board
-      kanbanBoardName: kanban-name
+    # reference parameters come from dependency, their usage will be explained later
+    boardId: ${{ TRELLO_INSTANCE_NAME.trello.outputs.boardId }}
+    todoListId: ${{ TRELLO_INSTANCE_NAME.trello.outputs.todoListId }}
+    doingListId: ${{ TRELLO_INSTANCE_NAME.trello.outputs.doingListId }}
+    doneListId: ${{ TRELLO_INSTANCE_NAME.trello.outputs.doneListId }}
     # main branch of the repo (to which branch the plugin will submit the workflows)
     branch: main
 ```
 
-Currently, all the parameters in the example above are mandatory.
+## 3. Use Together with the `trello` Plugin
+
+This plugin can be used together with the `trello` plugin (see document [here](./trello_plugin.md).)
+
+See the example below:
+
+```yaml
+---
+tools:
+  - name: trello_init_demo
+    plugin:
+      kind: trello
+      version: 0.2.0
+    options:
+      owner: lfbdev
+      repo: golang-demo
+      kanbanBoardName: kanban-name
+  - name: trello_github_integ_demo
+    plugin:
+      kind: trello-github-integ
+      version: 0.2.0
+    dependsOn: ["trello_init_demo.trello"]
+    options:
+      owner: lfbdev
+      repo: golang-demo
+      boardId: ${{ trello_init_demo.trello.outputs.boardId }}
+      todoListId: ${{ trello_init_demo.trello.outputs.todoListId }}
+      doingListId: ${{ trello_init_demo.trello.outputs.doingListId }}
+      doneListId: ${{ trello_init_demo.trello.outputs.doneListId }}
+      branch: main
+```
+
+In the example above:
+
+- We put `trello_init_demo.trello` as a dependency by using the `dependsOn` keyword.
+- We use `trello_init_demo.trello`'s output as input for the `trello_github_integ_demo` plugin.
+
+Pay attention to the `${{ xxx }}` part in the example. `${{ TOOL_NAME.TOOL_KIND.outputs.var}}` is the syntax for using an output.
+

docs/plugins/trello_plugin.md

@@ -44,34 +44,32 @@ See the example below:
 ```yaml
 ---
 tools:
-  - name: default
+  - name: trello_init_demo
     plugin:
       kind: trello
       version: 0.2.0
     options:
       owner: lfbdev
       repo: golang-demo
       kanbanBoardName: kanban-name
-  - name: default_trello_github
+  - name: trello_github_integ_demo
     plugin:
       kind: trello-github-integ
       version: 0.2.0
-    dependsOn: ["default.trello"]
+    dependsOn: ["trello_init_demo.trello"]
     options:
       owner: lfbdev
       repo: golang-demo
-      api:
-        name: trello
-        boardId: ${{ default.trello.outputs.bid }}
-        todoListId: ${{ default.trello.outputs.todoid }}
-        doingListId: ${{ default.trello.outputs.doingid }}
-        doneListId: ${{ default.trello.outputs.doneid }}
+      boardId: ${{ trello_init_demo.trello.outputs.boardId }}
+      todoListId: ${{ trello_init_demo.trello.outputs.todoListId }}
+      doingListId: ${{ trello_init_demo.trello.outputs.doingListId }}
+      doneListId: ${{ trello_init_demo.trello.outputs.doneListId }}
       branch: main
 ```
 
 In the example above:
 
-- We put `default.trello` as dependency by using the `dependsOn` keyword.
+- We put `default.trello` as a dependency by using the `dependsOn` keyword.
 - We use `default.trello`'s output as input for the `default_trello_github` plugin.
 
 Pay attention to the `${{ xxx }}` part in the example. `${{ TOOL_NAME.TOOL_KIND.outputs.var}}` is the syntax for using an output.

internal/pkg/plugin/trello/helper.go

@@ -37,6 +37,13 @@ func buildReadState(options *Options) (map[string]interface{}, error) {
 		return nil, err
 	}
 
+	output := make(map[string]interface{})
+	output["boardId"] = fmt.Sprint(listIds["boardId"])
+	output["todoListId"] = fmt.Sprint(listIds["todoListId"])
+	output["doingListId"] = fmt.Sprint(listIds["doingListId"])
+	output["doneListId"] = fmt.Sprint(listIds["doneListId"])
+
+	listIds["outputs"] = output
 	return listIds, nil
 }
 

internal/pkg/plugin/trello/trello.go

@@ -28,6 +28,25 @@ func CreateTrelloBoard(options *Options) (*TrelloItemId, error) {
 		return nil, err
 	}
 
+	exist, err := c.CheckBoardExists(options.Owner, options.Repo, options.KanbanBoardName)
+	if err != nil {
+		return nil, err
+	}
+
+	if exist {
+		log.Infof("Board already exists, owner: %s, repo: %s, kanbanName: %s.", options.Owner, options.Repo, options.KanbanBoardName)
+		listIds, err := c.GetBoardIdAndListId(options.Owner, options.Repo, options.KanbanBoardName)
+		if err != nil {
+			return nil, err
+		}
+		return &TrelloItemId{
+			boardId:     fmt.Sprint(listIds["boardId"]),
+			todoListId:  fmt.Sprint(listIds["todoListId"]),
+			doingListId: fmt.Sprint(listIds["doingListId"]),
+			doneListId:  fmt.Sprint(listIds["doneListId"]),
+		}, nil
+	}
+
 	board, err := c.CreateBoard(options.KanbanBoardName, options.Owner, options.Repo)
 	if err != nil {
 		return nil, err

internal/pkg/plugin/trellogithub/create.go

@@ -11,29 +11,24 @@ func Create(options map[string]interface{}) (map[string]interface{}, error) {
 		return nil, err
 	}
 
-	api := tg.GetApi()
-	log.Infof("API is: %s.", api.Name)
-	ws := defaultWorkflows.GetWorkflowByNameVersionTypeString(api.Name)
-
-	for _, w := range ws {
-		if err := tg.renderTemplate(w); err != nil {
-			return nil, err
-		}
-		if err := tg.client.AddWorkflow(w, tg.options.Branch); err != nil {
-			return nil, err
-		}
+	if err := tg.client.AddWorkflow(trelloWorkflow, tg.options.Branch); err != nil {
+		return nil, err
 	}
+
 	log.Success("Adding workflow file succeeded.")
-	trelloIds, err := tg.CreateTrelloItems()
-	if err != nil {
-		return nil, err
+
+	trelloItemId := &TrelloItemId{
+		boardId:     tg.options.BoardId,
+		todoListId:  tg.options.todoListId,
+		doingListId: tg.options.doingListId,
+		doneListId:  tg.options.doneListId,
 	}
-	log.Success("Creating trello board succeeded.")
-	if err := tg.AddTrelloIdSecret(trelloIds); err != nil {
+
+	if err := tg.AddTrelloIdSecret(trelloItemId); err != nil {
 		return nil, err
 	}
 
 	log.Success("Adding secret keys for trello succeeded.")
 
-	return buildState(tg, trelloIds), nil
+	return buildState(tg), nil
 }

internal/pkg/plugin/trellogithub/delete.go

@@ -1,25 +1,15 @@
 package trellogithub
 
-import (
-	"github.com/merico-dev/stream/pkg/util/log"
-)
-
 // Delete remove trello-github-integ workflows.
 func Delete(options map[string]interface{}) (bool, error) {
 	tg, err := NewTrelloGithub(options)
 	if err != nil {
 		return false, err
 	}
 
-	api := tg.GetApi()
-	log.Infof("API is %s.", api.Name)
-	ws := defaultWorkflows.GetWorkflowByNameVersionTypeString(api.Name)
-
-	for _, w := range ws {
-		err := tg.client.DeleteWorkflow(w, tg.options.Branch)
-		if err != nil {
-			return false, err
-		}
+	err = tg.client.DeleteWorkflow(trelloWorkflow, tg.options.Branch)
+	if err != nil {
+		return false, err
 	}
 
 	return true, nil

internal/pkg/plugin/trellogithub/helper.go

@@ -1,62 +1,23 @@
 package trellogithub
 
 import (
-	"bytes"
 	"fmt"
-	"text/template"
-
-	"github.com/mitchellh/mapstructure"
-
-	"github.com/merico-dev/stream/pkg/util/github"
-	"github.com/merico-dev/stream/pkg/util/trello"
 )
 
-// renderTemplate render the github actions template with config.yaml
-func (tg *TrelloGithub) renderTemplate(workflow *github.Workflow) error {
-	var jobs Jobs
-	err := mapstructure.Decode(tg.options.Jobs, &jobs)
-	if err != nil {
-		return err
-	}
-	//if use default {{.}}, it will confict (github actions vars also use them)
-	t, err := template.New("trellogithub").Delims("[[", "]]").Parse(workflow.WorkflowContent)
-	if err != nil {
-		return err
-	}
-
-	var buff bytes.Buffer
-	err = t.Execute(&buff, jobs)
-	if err != nil {
-		return err
-	}
-	workflow.WorkflowContent = buff.String()
-	return nil
-}
-
-func buildState(tg *TrelloGithub, ti *TrelloItemId) map[string]interface{} {
+func buildState(tg *TrelloGithub) map[string]interface{} {
 	res := make(map[string]interface{})
 	res["workflowDir"] = fmt.Sprintf("/repos/%s/%s/contents/.github/workflows", tg.options.Owner, tg.options.Repo)
-	res["boardId"] = ti.boardId
-	res["todoListId"] = ti.todoListId
-	res["doingListId"] = ti.doingListId
-	res["doneListId"] = ti.doneListId
 	return res
 }
 
-func (tg *TrelloGithub) buildReadState(api *Api) (map[string]interface{}, error) {
-	c, err := trello.NewClient()
-	if err != nil {
-		return nil, err
-	}
-	listIds, err := c.GetBoardIdAndListId(tg.options.Owner, tg.options.Repo, api.KanbanBoardName)
-	if err != nil {
-		return nil, err
-	}
+func (tg *TrelloGithub) buildReadState() (map[string]interface{}, error) {
+	listIds := make(map[string]interface{})
 
 	path, err := tg.client.GetWorkflowPath()
 	if err != nil {
 		return nil, err
 	}
 	listIds["workflowDir"] = path
+
 	return listIds, nil
 }

internal/pkg/plugin/trellogithub/read.go

@@ -1,6 +1,7 @@
 package trellogithub
 
 import (
+	"github.com/merico-dev/stream/pkg/util/github"
 	"github.com/merico-dev/stream/pkg/util/log"
 )
 
@@ -10,10 +11,7 @@ func Read(options map[string]interface{}) (map[string]interface{}, error) {
 		return nil, err
 	}
 
-	api := tg.GetApi()
-	log.Infof("API is: %s.", api.Name)
-
-	ws := defaultWorkflows.GetWorkflowByNameVersionTypeString(api.Name)
+	var ws = []*github.Workflow{trelloWorkflow}
 	retMap, err := tg.VerifyWorkflows(ws)
 	if err != nil {
 		return nil, err
@@ -31,5 +29,5 @@ func Read(options map[string]interface{}) (map[string]interface{}, error) {
 		return nil, nil
 	}
 
-	return tg.buildReadState(api)
+	return tg.buildReadState()
 }