diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 0000000..5836978 --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,38 @@ +version: 2.1 + +setup: true + +orbs: + orb-tools: circleci/orb-tools@11.5 + shellcheck: circleci/shellcheck@3.1 + +filters: &filters + tags: + only: /.*/ + +workflows: + main-wf: + jobs: + - orb-tools/pack: + filters: *filters + - orb-tools/review: + exclude: "RC009" + filters: *filters + - shellcheck/check: + filters: *filters + - orb-tools/publish: + orb-name: hubci/notify + vcs-type: << pipeline.project.type >> + requires: + - orb-tools/review + - orb-tools/pack + - shellcheck/check + context: circleci-ctx + filters: *filters + - orb-tools/continue: + pipeline-number: << pipeline.number >> + vcs-type: << pipeline.project.type >> + config-path: ".circleci/int-testing.yml" + requires: + - orb-tools/publish + filters: *filters diff --git a/.circleci/int-testing.yml b/.circleci/int-testing.yml new file mode 100644 index 0000000..b98e2e0 --- /dev/null +++ b/.circleci/int-testing.yml @@ -0,0 +1,38 @@ +version: 2.1 + +filters: &filters + tags: + only: /.*/ + +orbs: + orb-tools: circleci/orb-tools@11.5 + orb: hubci/notify@dev:<< pipeline.git.revision >> + +workflows: + int-testing-wf: + jobs: + - int-test-notify-mattermost: + filters: *filters + - orb-tools/pack: + filters: *filters + - orb-tools/publish: + orb-name: hubci/notify + vcs-type: << pipeline.project.type >> + pub-type: production + requires: + - orb-tools/pack + - int-test-notify-mattermost + context: circleci-ctx + filters: + branches: + ignore: /.*/ + tags: + only: /^v[0-9]+\.[0-9]+\.[0-9]+$/ + +jobs: + int-test-notify-mattermost: + docker: + - image: cimg/base:2023.01 + steps: + - orb/notify-mattermost: + text: "This message is from testing the Mattermost CircleCI orb. It can be found here: ${CIRCLE_BUILD_URL}." diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..adc61bb --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +orb.yml diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..969acdd --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright © 2023 Ricardo N Feliciano + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..e387391 --- /dev/null +++ b/README.md @@ -0,0 +1,33 @@ +![Notify Orb Logo](./img/header.png) + +# Notify Orb [![CircleCI Build Status](https://circleci.com/gh/hubci/notify-orb.svg?style=shield "CircleCI Build Status")](https://app.circleci.com/pipelines/github/hubci/notify-orb) [![CircleCI Orb Version](https://badges.circleci.com/orbs/hubci/notify.svg)][reg-page] [![GitHub License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](https://github.com/hubci/notify-orb/blob/trunk/LICENSE) + + +An orb to send messages from within a CircleCI job to to a chat platform. +The only platform supported at the moment is Mattermost. + +Executor support is a Linux or macOS based system on amd64 or arm64. + + +## Usage + +Example usage as well as a list of available executors, commands, and jobs are available on this orb's [registry page][reg-page]. + + +## Resources + +[CircleCI Orb Registry Page][reg-page] - The official registry page for this orb will all versions, executors, commands, and jobs described. +[CircleCI Orb Docs](https://circleci.com/docs/2.0/orb-intro/#section=configuration) - Docs for using and creating CircleCI Orbs. + + +## Contributing + +I welcome [issues](https://github.com/hubci/notify-orb/issues) and [pull requests](https://github.com/hubci/notify-orb/pulls) against this repository! +For further questions/comments about this or other orbs, visit the Orb Category of [CircleCI Discuss](https://discuss.circleci.com/c/orbs). + +### Publishing +New versions of this orb are published by pushing a SemVer git tag. + + + +[reg-page]: https://circleci.com/developer/orbs/orb/hubci/notify diff --git a/img/header.png b/img/header.png new file mode 100644 index 0000000..ca3edf2 Binary files /dev/null and b/img/header.png differ diff --git a/src/@orb.yml b/src/@orb.yml new file mode 100644 index 0000000..f4cdeb9 --- /dev/null +++ b/src/@orb.yml @@ -0,0 +1,11 @@ +version: 2.1 + +description: | + Send notifications from a CircleCI Pipeline to a Mattermost channel. + + Bash is required on the executor image. This orb supports Linux and macOS + based images on both the amd64 and arm64 architectures. + +display: + home_url: "https://circleci.com/developer/orbs/orb/hubci/notify" + source_url: "https://github.com/hubci/notify-orb" diff --git a/src/commands/notify-mattermost.yml b/src/commands/notify-mattermost.yml new file mode 100644 index 0000000..77ee559 --- /dev/null +++ b/src/commands/notify-mattermost.yml @@ -0,0 +1,52 @@ +description: | + Send a message to a Mattermost channel or user (DM). +parameters: + text: + description: | + Markdown-formatted message to send to Mattermost. To trigger + notifications, use @, @channel, and @here like you would in + other Mattermost messages. + type: string + channel: + description: | + Mattermost webhooks have a default channel. Use this to send the text to + a channel other than the default. Use the channel’s name and not the + display name, e.g. use town-square, not Town Square. Use an "@" followed + by a username to send to a Direct Message. + type: string + default: "" + webhook: + description: | + The name of the environment variable to use to read in the webhook. The + default value should be fine for most people. + type: env_var_name + default: MM_WEBHOOK +steps: + - run: + name: "Check Dependencies" + command: | + if ! echo $0 | grep --quiet "bash"; then + echo "The running shell is not Bash and it is a requirement." + exit 2 + fi + + if ! command -v curl &> /dev/null; then + echo "The running shell is not Bash and it is a requirement." + exit 3 + fi + + if [ -z ${<< parameters.webhook >>}]; then + echo "The Mattermost webhook needs to be set." + exit 4 + fi + - run: + name: "Send Message" + command: | + HTTP_STATUS=$( curl --write-out "%{http_code}\n" --request POST --header "Content-Type: application/json" --data "{\"text\": \"<< parameters.text >>\"}" ${<< parameters.webhook>>} ) + + if [ "$HTTP_STATUS" -ne "200" ]; then + echo "There was an error sending the webhook. The return code was ${HTTP_STATUS}" + exit 5 + fi + + echo "Message sent." diff --git a/src/commands/status.yml.bak b/src/commands/status.yml.bak new file mode 100644 index 0000000..02b7ff4 --- /dev/null +++ b/src/commands/status.yml.bak @@ -0,0 +1,46 @@ +description: | + Notify a Mattermost channel on the final status of a CircleCI job. Only + notifies on failure by default. This command should be the final + command/step in a job in order to work correctly. +parameters: + success-message: + description: | + Markdown-formatted message to send to Mattermost to indicate a successful + job. This parameter is only needed to customize the default message. + type: string + default: | + The CircleCI job ${CIRCLE_JOB} has completed successfully. You can view + it here: CIRCLE_BUILD_URL + failed-message: + description: | + Markdown-formatted message to send to Mattermost to indicate a failed job + . This parameter is only needed to customize the default message. + type: string + default: | + The CircleCI job ${CIRCLE_JOB} has failed. You can view it here: + CIRCLE_BUILD_URL + channel: + description: | + Mattermost webhooks have a default channel. Use this to send the text to + a channel other than the default. Use the channel’s name and not the + display name, e.g. use town-square, not Town Square. Use an "@" followed + by a username to send to a Direct Message. + type: string + default: "" + webhook: + description: | + The name of the environment variable to use to read in the webhook. The + default value should be fine for most people. + type: env_var_name + default: MM_WEBHOOK +steps: + - message: + text: << parameters.success-message >> + channel: << parameters.channel >> + webhook: << parameters.webhook >> + when: on_success + - message: + text: << parameters.failed-message >> + channel: << parameters.channel >> + webhook: << parameters.webhook >> + #when: on_fail diff --git a/src/examples/audit.yml b/src/examples/audit.yml new file mode 100644 index 0000000..038a7a6 --- /dev/null +++ b/src/examples/audit.yml @@ -0,0 +1,22 @@ +description: | + An extremely simple example of sending a notification. + +usage: + version: 2.1 + + orbs: + notify: hubci/notify@x.y + + workflows: + main-wf: + jobs: + - build + + jobs: + build: + docker: + - image: cimg/base:2023.01 + steps: + - checkout + - notify/notify-mattermost: + text: "Hi friends!"