ghdag

ghdag

:octocat: ghdag is a tiny workflow engine for GitHub issue and pull request.

Key features of ghdag are:

• Simple definition of workflows to improve the lifecycle of issues and pull requests.
• Built-in GitHub and Slack actions.
• Optimized for running on GitHub Actions, it is easier to configure when running on GitHub Actions.

See Examples page for practical usage.

Getting Started

Generate a workflow file

Execute ghdag init for generating a workflow YAML file for ghdag ( and a workflow YAML file for GitHub Actions ).

$ ghdag init myworkflow
2021-02-23T23:29:48+09:00 [INFO] ghdag version 0.2.3
2021-02-23T23:29:48+09:00 [INFO] Creating myworkflow.yml
Do you generate a workflow YAML file for GitHub Actions? (y/n) [y]: y
2021-02-23T23:29:48+09:00 [INFO] Creating .github/workflows/ghdag_workflow.yml
$ cat myworkflow.yml
---
# generate by ghdag init
tasks:
  -
    id: set-question-label
    if: 'is_issue && len(labels) == 0 && title endsWith "?"'
    do:
      labels: [question]
    ok:
      run: echo 'Set labels'
    ng:
      run: echo 'failed'
    name: Set 'question' label
$ cat .github/workflows/ghdag_workflow.yml
---
# generate by ghdag init
name: ghdag workflow
on:
  issues:
    types: [opened]
  issue_comment:
    types: [created]
  pull_request:
    types: [opened]

jobs:
  run-workflow:
    name: Run workflow
    runs-on: ubuntu-latest
    container: ghcr.io/k1low/ghdag:latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
      - name: Run ghdag
        run: ghdag run myworkflow.yml
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

And edit myworkflow.yml.

Run workflow on your machine

$ export GITHUB_TOKEN=xxXxXXxxXXxx
$ export GITHUB_REPOGITORY=k1LoW/myrepo
$ ghdag run myworkflow.yml
2021-02-28T00:26:41+09:00 [INFO] ghdag version 0.2.3
2021-02-28T00:26:41+09:00 [INFO] Start session
2021-02-28T00:26:41+09:00 [INFO] Fetch all open issues and pull requests from k1LoW/myrepo
2021-02-28T00:26:42+09:00 [INFO] 3 issues and pull requests are fetched
2021-02-28T00:26:42+09:00 [INFO] 1 tasks are loaded
2021-02-28T00:26:42+09:00 [INFO] [#14 << set-question-label] [DO] Replace labels: question
Set labels
2021-02-28T00:26:43+09:00 [INFO] Session finished
$

Run workflow on GitHub Actions

$ git add myworkflow.yml
$ git add .github/workflows/ghdag_workflow.yml
$ git commit -m'Initial commit for ghdag workflow'
$ git push origin

And, see https://github.com/[owner]/[repo]/actions

Issues and pull requests targeted by ghdag

📝 The issues and pull requests that ghdag fetches varies depending on the environment in which it is run.

Workflow syntax

ghdag requires a YAML file to define your workflow configuration.

env:

A map of environment environment variables in global scope (available to all tasks in the workflow).

Example

env:
  SERVER: production
  GITHUB_TOKEN: ${GHDAG_GITHUB_TOKEN}

tasks:

A workflow run is made up of one or more tasks. Tasks run in sequentially.

Example

tasks:
  -
    id: first
    if: 'is_issue && len(labels) == 0 && title endsWith "?"'
    do:
      labels: [question]
    ok:
      run: echo 'Set labels'
    ng:
      run: echo 'failed'
    name: Set 'question' label
  -
    id: second
    if: len(assignees) == 0
    do:
      assignees: [k1LoW]
    name: Assign me

tasks[*].id:

Each task have an id to be called by another task.

tasks[*].name:

Name of task.

tasks[*].if:

The task will not be performed unless the condition in the if section is met.

If the if section is missing, the task will not be performed unless it is called by another task.

ghdag use antonmedv/expr.

See Language Definition.

The variables available in the if section are as follows

tasks[*].env:

A map of environment environment variables in the scope of each task.

tasks[*].do:, tasks[*].ok:, tasks[*].ng:

A task has 3 actions ( called do, ok and ng ) with predetermined steps to be performed.

1. Perform do: action.
2. If the do: action succeeds, perform the ok: action.
3. If the do: action fails, perform the ng: action.

tasks[*].<action_type>.run:

Execute command using sh -c.

Example

do:
  run: echo 'execute command'

tasks[*].<action_type>.labels:

Update the labels of the target issue or pull request.

Example

do:
  labels: [question, bug]

tasks[*].<action_type>.assignees:

Update the assignees of the target issue or pull request.

Example

do:
  assignees: [alice, bob, charlie]
env:
  GITHUB_ASSIGNEES_SAMPLE: 1

tasks[*].<action_type>.reviewers:

Update the reviewers for the target pull request.

However, Code owners has already been registered as a reviewer, so it is excluded.

Example

do:
  reviewers: [alice, bob, charlie]
env:
  GITHUB_REVIEWERS_SAMPLE: 2

tasks[*].<action_type>.comment:

Create new comment to the target issue or pull request.

Example

do:
  labels: [question]
ok:
  comment: Thank you for your question :+1:

tasks[*].<action_type>.state:

Change state the the target issue or pull request.

Example

if: hours_elapsed_since_updated > (24 * 30)
do:
  state: close

tasks[*].<action_type>.notify:

Send notify message to Slack channel.

Example

ng:
  notify: error ${GHDAG_ACTION_OK_ERROR}
env:
  SLACK_CHANNEL: workflow-alerts
  SLACK_MENTIONS: bob

• ( SLACK_API_TOKEN and SLACK_CHANNEL ) or SLACK_WEBHOOK_URL

tasks[*].<action_type>.next:

Call next tasks in the same session.

Example

tasks:
  -
    id: set-question-label
    if: 'is_issue && len(labels) == 0 && title endsWith "?"'
    do:
      labels: [question]
    ok:
      next [notify-slack, add-comment]
  -
    id: notify-slack
    do:
      notify: A question has been posted.
  -
    id: add-comment
    do:
      comment: Thank you your comment !!!

Environment variables for configuration

Required scope of SLACK_API_TOKEN

• channel:read
• chat:write
• chat:write.public
• users:read
• usergroups:read
• chat:write.customize ( optional )

Link the GitHub user or team name to the Slack user or team account name

Provides the feature linkedNames: to link GitHub and Slack transparently even if they have different account names.

Example

Send a Slack message with a mention ( @bob_marly ) to the author ( @bob ) of the pull request.

tasks:
  -
    id: notify-slack
    if: 'is_pull_request && is_approved && mergeable'
    do:
      notify: Your pull request is ready for merge !
    env:
      SLACK_MENTIONS: ${GHDAG_TASK_AUTHOR}
linkedNames:
  -
    github: bob
    slack: bob_marly

Use ghdag as the one-shot command on GitHub Actions

ghdag can be used not only as a workflow engine, but also as a utility command in jobs on GitHub Actions.

$ ghdag do --help
do action.

Usage:
  ghdag do [command]

Available Commands:
  assignees   update the assignees of the target issue or pull request
  comment     create the comment of the target issue or pull request
  labels      update the labels of the target issue or pull request
  notify      send notify message to slack channel
  reviewers   update the reviewers of the target issue or pull request
  run         execute command using `sh -c`
  state       change state of the target issue or pull request

Flags:
  -h, --help   help for do

Use "ghdag do [command] --help" for more information about a command.
$ ghdag if --help
check condition.

Usage:
  ghdag if [CONDITION] [flags]

Flags:
  -h, --help         help for if
  -n, --number int   issue or pull request number

Example

name: labels

on:
  issues:
    types: [created]

jobs:
  set-labels:
    name: Set labels
    runs-on: ubuntu-latest
    container: ghcr.io/k1low/ghdag:latest
    steps:
      - name: Set labels
        run: ghdag do labels question
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: build

jobs:
  job-tests:

# snip

      - name: Send notification to channel
        if: failure()
        run: ghdag do notify 'Test faild'
        env:
          SLACK_API_TOKEN: ${{ secrets.SLACK_API_TOKEN }}
          SLACK_CHANNEL: operations
          SLACK_MENTIONS: bob

Install

deb:

Use dpkg-i-from-url

$ export GHDAG_VERSION=X.X.X
$ curl -L https://git.io/dpkg-i-from-url | bash -s -- https://github.com/k1LoW/ghdag/releases/download/v$GHDAG_VERSION/ghdag_$GHDAG_VERSION-1_amd64.deb

RPM:

$ export GHDAG_VERSION=X.X.X
$ yum install https://github.com/k1LoW/ghdag/releases/download/v$GHDAG_VERSION/ghdag_$GHDAG_VERSION-1_amd64.rpm

apk:

Use apk-add-from-url

$ export GHDAG_VERSION=X.X.X
$ curl -L https://git.io/apk-add-from-url | sh -s -- https://github.com/k1LoW/ghdag/releases/download/v$GHDAG_VERSION/ghdag_$GHDAG_VERSION-1_amd64.apk

homebrew tap:

$ brew install k1LoW/tap/ghdag

manually:

Download binary from releases page

go get:

$ go get github.com/k1LoW/ghdag

docker:

$ docker pull ghcr.io/k1low/ghdag:latest