> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# gluegroups/glue

Implement event-based notifications across all of your CI/CD pipelines. Utilize built-in message templates or customize notifications using Markdown specific to your organization's needs. Supports Linux x86_64, MacOS, Arm64 V8, and Windows.


## Commands

### notify

Notify a Glue target with a custom message.
The environment variables GLUE_ACCESS_TOKEN and GLUE_DEFAULT_TARGET must be set for this orb to work.
For instructions on how to set them, follow the setup guide available in the wiki: https://github.com/gluegroups/circle-orb/wiki/Setup.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch_pattern` | string | .+ | A comma separated list of regex matchable branch names. Notifications will only be sent if sent from a job from these branches.
By default ".+" will be used to match all branches. Pattern must match the full string, no partial matches.
 |
| `circleci_host` | string | https://circleci.com | A CircleCI Host which used in a message template.
 |
| `custom` | string |  | Enter a custom message template.

1. Create your message template using the Glue markdown.
2. Insert any desired environment variables.
3. Paste value here.
 |
| `debug` | boolean | false | Enable to view full payload being sent to Glue and response being received from the API call.
Redacted content can be viewed by re-running the job with SSH and accessing the log files referenced in the job output.
When run in a persistent build environment such as CircleCI Runner, these debug log files may remain in the system's temporary filesystem indefinitely and accumulate over time.
 |
| `event` | enum | always | In what event should this message send? Options: ["fail", "pass", "always"]
 |
| `ignore_errors` | boolean | true | Ignore errors posting to Glue.
Disable to catch initial setup errors. Re-enable to prevent Glue errors from affecting your pipeline.
 |
| `invert_match` | boolean | false | Invert the branch and tag patterns.
If set to true, notifications will only be sent if sent from a job from branches and tags that do not match the patterns.
 |
| `mentions` | string |  | Exports to the "$GLUE_PARAM_MENTIONS" environment variable for use in templates.
Mention users by creating a link to their user ID. Mention groups by creating a link to the group ID. For example:
[User Name](glue:usr_ABCXYZ)
[Group Name](glue:grp_123456)
 |
| `step_name` | string | Glue - Sending Notification | Specify a custom step name for this command, if desired |
| `tag_pattern` | string | .+ | A comma separated list of regex matchable tag names. Notifications will only be sent if sent from a job from these branches.
By default ".+" will be used to match all tags. Pattern must match the full string, no partial matches.
 |
| `target` | string | $GLUE_DEFAULT_TARGET | Specify a Glue thread ID (thr_ABCXYZ) or group ID (grp_ABCXYZ) to post to. If you specify a group ID, this will post a message to the group chat by default,
but you can also specify a `thread_subject` in order ot create a thread. If You may include a comma separated list of targets if you wish to post to multiple targets at once.
Set the "GLUE_DEFAULT_TARGET" environment variable for the default target.
 |
| `template` | string |  | Select which template to use for the notification by its name. The name must be available as an environment variable.
The built-in templates can be found and previewed at: https://github.com/gluegroups/circle-orb/wiki#templates.
Alternatively, you can create and use your own dynamic templates: https://github.com/gluegroups/circle-orb/wiki/Dynamic-Templates.
If left empty and no custom template is provided, the template will be automatically selected based on the job status.
 |
| `thread_by` | string |  | When set, the first `notify` with a given `thread_by` will create new Glue thread.
Any subsequent `notify` usage with the same identifier will be posted within that same thread.
`thread_by` should be set to any arbitrary string to help you identify different threads. See examples for more information.
To use this feature, a group ID must be used as the `target` and `threadSubject` must be specified.
 |
| `thread_subject` | string |  | When specified, a new Glue thread will be created with this thread subject.
To use this feature, a group ID must be used as the `target`.
 |

## Jobs

### on-hold

Insert this job in-line with your standard CircleCI on-hold notification jobs to simultaneously send a Glue notification containing a link to the paused Workflow.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch_pattern` | string | .+ | A comma separated list of regex matchable branch names.
Notifications will only be sent if sent from a job from these branches.
By default ".+" will be used to match all branches. Pattern must be a POSIX expression and match the full string, no partial matches.
 |
| `circleci_host` | string | https://circleci.com | CircleCI Host (used as the base for the Workflow URL)
 |
| `custom` | string |  | (optional) Enter a custom message template.

1. Create your message template using Glue Markdown.
2. Insert any desired environment variables.
3. Paste value here.
 |
| `debug` | boolean | false | View payload and response being sent to Glue API.
Enable to view the full payload being sent to Glue and the response being received from the API call.
 |
| `invert_match` | boolean | false | Invert the branch and tag patterns.
If set to true, notifications will only be sent if sent from a job from branches and tags that do not match the patterns.
 |
| `mentions` | string |  | Exports to the "$GLUE_PARAM_MENTIONS" environment variable for use in templates.
Mention users by creating a link to their user ID. Mention groups by creating a link to the group ID. For example:
[User Name](glue:usr_ABCXYZ)
[Group Name](glue:grp_123456)
 |
| `step_name` | string | Glue - Sending Notification | Specify a custom step name for this command, if desired |
| `target` | string | $GLUE_DEFAULT_TARGET | Specify a Glue thread ID (thr_ABCXYZ) or group ID (grp_ABCXYZ) to post to. If you specify a group ID, this will post a message to the group chat by default,
but you can also specify a `thread_subject` in order ot create a thread. If You may include a comma separated list of targets if you wish to post to multiple targets at once.
Set the "GLUE_DEFAULT_TARGET" environment variable for the default target.
 |
| `template` | string | basic_on_hold_1 | (optional) By default this job will send the standard "basic_on_hold_1" template. In order to use a custom template you must also set this value to an empty string. |

## Examples

### custom_notification

Send a custom notification using Glue's Markdown.
Create the payload code and paste it in your notify command's custom parameter.
Detailed instructions can be found in the GitHub readme.


```yaml
version: '2.1'
orbs:
  glue: gluegroups/glue@1.0
jobs:
  notify:
    docker:
      - image: cimg/base:stable
    steps:
      - glue/notify:
          custom: |
            **This is a text notification**
          event: always
workflows:
  send-notification:
    jobs:
      - notify:
          context: glue-secrets
```

### full_deployment_sample

A full test and deploy sample configuration.
Test your app on every commit. On tagged commits, place the workflow on-hold after testing, pending manual approval for deployment.
Receive a Glue notification when the workflow is placed on hold, and a notification whether the deployment fails or deploys successfully.


```yaml
version: '2.1'
orbs:
  glue: gluegroups/glue@1.0
jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - run: echo "deploy my app"
      - glue/notify:
          event: fail
          mentions: '[Engineering](glue:grp_123456)'
          template: basic_fail_1
      - glue/notify:
          event: pass
          template: success_tagged_deploy_1
  test:
    docker:
      - image: cimg/base:stable
    steps:
      - run: echo "test my app"
workflows:
  test-and-deploy:
    jobs:
      - test
      - glue/on-hold:
          context: glue-secrets
          filters:
            tags:
              only: /^v.*/
          requires:
            - test
      - pause_workflow:
          filters:
            tags:
              only: /^v.*/
          requires:
            - test
            - glue/on-hold
          type: approval
      - deploy:
          filters:
            tags:
              only: /^v.*/
          requires:
            - pause_workflow
```

### notify_on_fail_with_template

Send a Glue notification when a job fails. This example uses a pre-included template. Custom templates can also be used.
The target parameter can be used to alert a specific Glue group or thread.
Ensure the "glue/notify" command is the last command in a job to accurately capture the status.


```yaml
version: '2.1'
orbs:
  glue: gluegroups/glue@1.0
  node: circleci/node@4.1
jobs:
  deploy:
    executor:
      name: node/default
    steps:
      - checkout
      - node/install-packages
      - run:
          command: npm run deploy
      - glue/notify:
          event: fail
          target: grp_ABCXYZ
          template: basic_fail_1
workflows:
  deploy_and_notify:
    jobs:
      - deploy:
          context: glue-secrets
```

### notify_thread

Create a Glue thread in the `target` group and send subsequent `notify` messages to the same thread.
`thread_subject` parameter determines the subject of the thread.
`thread_by` parameter holds a thread identifier in case there are multiple notifications in the pipeline.

Note: target must be a group(s) if a `thread_subject` is specified.


```yaml
version: '2.1'
orbs:
  glue: gluegroups/glue@1.0
  node: circleci/node@4.1
jobs:
  deploy:
    executor:
      name: node/default
    steps:
      - glue/notify:
          custom: |
            **Deployment started.**
          event: always
          target: grp_ABCXYZ
          thread_by: testing-$CIRCLE_SHA1
          thread_subject: CI workflow for $CIRCLE_SHA1
      - glue/notify:
          custom: |
            **Deployment finished.**
          event: always
          target: grp_ABCXYZ
          thread_by: testing-$CIRCLE_SHA1
          thread_subject: CI workflow for $CIRCLE_SHA1
  test:
    executor:
      name: node/default
    steps:
      - glue/notify:
          custom: |
            **Tests started.**
          event: always
          target: grp_ABCXYZ
          thread_by: testing-$CIRCLE_SHA1
          thread_subject: CI workflow for $CIRCLE_SHA1
      - glue/notify:
          custom: |
            **Tests finished.**
          event: always
          target: grp_ABCXYZ
          thread_by: testing-$CIRCLE_SHA1
          thread_subject: CI workflow for $CIRCLE_SHA1
workflows:
  deploy_and_notify:
    jobs:
      - deploy
      - test:
          requires:
            - deploy
```

### notify_two_targets

Send a Glue notification to two targets simultaneously.
By default, if no target parameter is set, the $GLUE_DEFAULT_TARGET value will be used (must be set).
A custom target, or comma-separated list of targets (no spaces) can be supplied via the "target" parameter.

It is recommended to use the "target ID" for the value(s).


```yaml
version: '2.1'
orbs:
  glue: gluegroups/glue@1.0
  node: circleci/node@4.1
jobs:
  deploy:
    executor:
      name: node/default
    steps:
      - glue/notify:
          custom: |
            **This is a text notification**
          event: always
          target: grp_ABCXYZ,grp_ZXCVBN
workflows:
  deploy_and_notify:
    jobs:
      - deploy:
          context: glue-secrets
```

### on_hold_notification

Pause a Workflow for manual approval and send a Glue notification with a link to the Workflow.


```yaml
version: '2.1'
orbs:
  glue: gluegroups/glue@1.0
workflows:
  on-hold-example:
    jobs:
      - my_test_job
      - glue/on-hold:
          context: glue-secrets
          requires:
            - my_test_job
      - pause_workflow:
          requires:
            - my_test_job
            - glue/on-hold
          type: approval
      - my_deploy_job:
          requires:
            - pause_workflow
```

### only_notify_on_branch

Use the "branch_pattern" parameter to limit notifications to specified branches. Useful when a job is executed on multiple branches but you only wish to be notified on a subset of branches. For example: If your "build" job runs on every branch, but you wish to only be notified when a failure occurs on the "main" branch, your config may look like this.


```yaml
version: '2.1'
orbs:
  glue: gluegroups/glue@1.0
jobs:
  build:
    machine: true
    steps:
      - run: some build command
      - glue/notify:
          branch_pattern: main
          event: fail
          template: basic_fail_1
      - glue/notify:
          branch_pattern: production
          event: fail
          mentions: '[User Name](glue:usr_ABCXYZ)'
          template: basic_fail_1
workflows:
  deploy_and_notify:
    jobs:
      - build:
          context: glue-secrets
      - deploy:
          filters:
            branches:
              only:
                - production
          requires:
            - build
```

### successful_tagged_deployment

Use one of our pre-included templates for sending a success notification when a tagged deployment passes.
Enter a Target ID in the target parameter to specify which Glue group or thread to ping.
Ensure the "glue/notify" command is the last command in a job to accurately capture the status.


```yaml
version: '2.1'
orbs:
  glue: gluegroups/glue@1.0
  node: circleci/node@4.1
jobs:
  deploy:
    executor:
      name: node/default
    steps:
      - checkout
      - node/install-packages
      - run:
          command: npm run deploy
      - glue/notify:
          event: pass
          target: grp_ABCXYZ
          template: success_tagged_deploy_1
workflows:
  deploy_and_notify:
    jobs:
      - deploy:
          context:
            - glue-secrets
```