diff --git a/DOCS.md b/DOCS.md new file mode 100644 index 0000000..54fb1f1 --- /dev/null +++ b/DOCS.md @@ -0,0 +1,287 @@ +--- +date: 2017-01-08T00:00:00+00:00 +title: Telegram +author: appleboy +tags: [ notifications, chat ] +repo: appleboy/drone-telegram +logo: telegram.svg +image: appleboy/drone-telegram +--- + +The Telegram plugin posts build status messages to your account. The below pipeline configuration demonstrates simple usage: + +```yaml +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id +``` + +Example configuration with photo message: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ photo: ++ - tests/1.png ++ - tests/2.png +``` + +Example configuration with document message: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ document: ++ - tests/1.pdf ++ - tests/2.pdf +``` + +Example configuration with sticker message: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ sticker: ++ - tests/3.png ++ - tests/4.png +``` + +Example configuration with audio message: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ audio: ++ - tests/audio1.mp3 ++ - tests/audio2.mp3 +``` + +Example configuration with voice message: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ voice: ++ - tests/voice1.ogg ++ - tests/voice2.ogg +``` + +Example configuration with location message: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ location: ++ - 24.9163213,121.1424972 ++ - 24.9263213,121.1224972 +``` + +Example configuration with venue message: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ venue: ++ - 24.9163213,121.1424972,title,address ++ - 24.3163213,121.1824972,title,address +``` + +Example configuration with video message: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ video: ++ - tests/video1.mp4 ++ - tests/video2.mp4 +``` + +Example configuration with message format: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ format: markdown +``` + +Example configuration for success and failure messages: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ when: ++ status: [ success, failure ] +``` + +Example configuration with a custom message template: + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram + token: xxxxxxxxxx + to: telegram_user_id ++ message: | ++ {{ #success build.status }} ++ build {{ build.number }} succeeded. Good job. ++ {{ else }} ++ build {{ build.number }} failed. Fix me please. ++ {{ /success }} +``` + +# Secrets + +The telegram plugin supports reading credentials from the Drone secret store. This is strongly recommended instead of storing credentials in the pipeline configuration in plain text. + +```diff +pipeline: + telegram: + image: appleboy/drone-telegram +- token: xxxxxxxxxx + to: telegram_user_id +``` + +The `token` attribute can be replaced with the below secret environment variables. Please see the Drone documentation to learn more about secrets. + +PLUGIN_TOKEN +: telegram token + +# Parameter Reference + +token +: telegram token from [telegram developer center](https://core.telegram.org/bots/api) + +to +: telegram user id + +message +: overwrite the default message template + +photo +: local file path + +document +: local file path + +sticker +: local file path + +audio +: local file path + +voice +: local file path + +location +: local file path + +video +: local file path + +venue +: local file path + +format +: `markdown` or `html` format + +# Template Reference + +repo.owner +: repository owner + +repo.name +: repository name + +build.status +: build status type enumeration, either `success` or `failure` + +build.event +: build event type enumeration, one of `push`, `pull_request`, `tag`, `deployment` + +build.number +: build number + +build.commit +: git sha for current commit + +build.branch +: git branch for current commit + +build.tag +: git tag for current commit + +build.ref +: git ref for current commit + +build.author +: git author for current commit + +build.link +: link the the build results in drone + +build.started +: unix timestamp for build started + +build.finished +: unix timestamp for build finished + +# Template Function Reference + +uppercasefirst +: converts the first letter of a string to uppercase + +uppercase +: converts a string to uppercase + +lowercase +: converts a string to lowercase. Example `{{lowercase build.author}}` + +datetime +: converts a unix timestamp to a date time string. Example `{{datetime build.started}}` + +success +: returns true if the build is successful + +failure +: returns true if the build is failed + +truncate +: returns a truncated string to n characters. Example `{{truncate build.sha 8}}` + +urlencode +: returns a url encoded string + +since +: returns a duration string between now and the given timestamp. Example `{{since build.started}}` diff --git a/logo.svg b/logo.svg new file mode 100644 index 0000000..ed2677e --- /dev/null +++ b/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file