166 lines
4.5 KiB
Markdown
166 lines
4.5 KiB
Markdown
# slackecho
|
|
|
|
Need a quick way to send a message to Slack from the command line? This will do the job (and not much else).
|
|
|
|
Useful inside scripts to report back to an administrator, monitor cron jobs, or integrate with CI/CD pipelines.
|
|
|
|
## What is this repository for?
|
|
|
|
- **Single-purpose shell script** that uses `curl` to send messages to Slack via incoming webhooks
|
|
- **Minimal scope**: Message delivery only, no complex features or dependencies beyond `curl`
|
|
- **Lightweight**: Designed for integration into bash scripts, cron jobs, and automation pipelines
|
|
- Maintained by [Hansen IT Solutions](https://hansenit.solutions)
|
|
|
|
## Installation
|
|
|
|
1. **Install curl** (if not already present)
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt-get install curl
|
|
|
|
# macOS
|
|
brew install curl
|
|
|
|
# CentOS/RHEL
|
|
sudo yum install curl
|
|
```
|
|
|
|
2. **Copy script to binary path**
|
|
```bash
|
|
sudo cp slackecho /usr/local/bin/
|
|
sudo chmod +x /usr/local/bin/slackecho
|
|
```
|
|
|
|
3. **Configure Slack webhook URL**
|
|
- Update the `SLACKURL` variable in the script with your Slack incoming webhook URL
|
|
- Create a Slack webhook: https://api.slack.com/messaging/webhooks
|
|
|
|
## Usage
|
|
|
|
### Command Signature
|
|
|
|
```bash
|
|
slackecho <message> [username] [channel] [icon]
|
|
```
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Required | Default | Description |
|
|
|-----------|----------|---------|-------------|
|
|
| `message` | Yes | N/A | Text to send to Slack |
|
|
| `username` | No | `slackecho-user` | Display name of the Slack message sender |
|
|
| `channel` | No | `general` | Target Slack channel (without # prefix) |
|
|
| `icon` | No | `:robot_face:` | Slack emoji icon for the message |
|
|
|
|
### Examples
|
|
|
|
Send a simple message to the default channel:
|
|
```bash
|
|
slackecho "Backup complete"
|
|
```
|
|
|
|
Send a message with a custom username:
|
|
```bash
|
|
slackecho "Build failed" "CI-Bot"
|
|
```
|
|
|
|
Send to a specific channel:
|
|
```bash
|
|
slackecho "Deployment complete" "deploy-bot" "deployments"
|
|
```
|
|
|
|
Use a custom icon:
|
|
```bash
|
|
slackecho "Alert!" "monitoring" "alerts" ":warning:"
|
|
```
|
|
|
|
## Integration Examples
|
|
|
|
### Cron Job
|
|
```bash
|
|
# Report cron job status to Slack
|
|
0 2 * * * /path/to/backup.sh && slackecho "Daily backup succeeded" || slackecho "Daily backup failed"
|
|
```
|
|
|
|
### Bash Script
|
|
```bash
|
|
#!/bin/bash
|
|
if command -v someapp &> /dev/null; then
|
|
slackecho "someapp is installed" "admin"
|
|
else
|
|
slackecho "someapp is NOT installed" "admin" "alerts" ":warning:"
|
|
fi
|
|
```
|
|
|
|
### CI/CD Pipeline
|
|
```bash
|
|
# In your CI/CD script
|
|
slackecho "Build #${CI_JOB_ID} completed" "CI" "builds"
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Currently, the webhook URL and default values are hardcoded in the script. Future versions will support:
|
|
- External configuration file
|
|
- Environment variables for SLACKURL
|
|
- Customizable default values per installation
|
|
|
|
To customize now, edit these variables in the `slackecho` script:
|
|
- `SLACKURL`: Your Slack incoming webhook URL
|
|
- `SLACKUSER`: Default username (default: "slackecho-user")
|
|
- `SLACKCH`: Default channel (default: "general")
|
|
- `SLACKICON`: Default emoji icon (default: ":robot_face:")
|
|
|
|
## Dependencies
|
|
|
|
- **curl**: For HTTP POST requests to Slack
|
|
- **bash**: Shell script runtime
|
|
|
|
## Architecture
|
|
|
|
The script follows a simple flow:
|
|
1. Validate that at least one argument (message) is provided
|
|
2. Set default values for optional parameters
|
|
3. Build a JSON payload with channel, username, text, and icon_emoji fields
|
|
4. POST the payload to the Slack webhook URL using `curl`
|
|
5. Suppress output and errors
|
|
|
|
## Testing
|
|
|
|
Currently no automated tests are in place. Contributions for a lightweight bash test framework (e.g., BATS) are welcome.
|
|
|
|
To manually test:
|
|
```bash
|
|
./slackecho "Test message" "TestBot" "general"
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
Currently, the script silently ignores POST failures. Output is suppressed to `/dev/null`. For debugging:
|
|
1. Comment out the `>/dev/null 2>&1` at the end of the curl command
|
|
2. Verify your SLACKURL is correct
|
|
3. Ensure the webhook still exists in your Slack workspace
|
|
|
|
## Contribution Guidelines
|
|
|
|
Contributions are welcome! Please:
|
|
1. Keep changes minimal and focused on core functionality
|
|
2. Maintain bash compatibility
|
|
3. Test changes before submitting
|
|
4. Follow the existing code style (parameter handling, error suppression)
|
|
|
|
See [TODO](#todo) for planned improvements.
|
|
|
|
## TODO
|
|
|
|
- [ ] Create external configuration file
|
|
- [ ] Support environment variables for SLACKURL
|
|
- [ ] Add bash syntax checking to CI/CD pipeline
|
|
- [ ] Create BATS-based test framework
|
|
- [ ] Implement optional logging
|
|
- [ ] Formalize code review process
|
|
|
|
## Contact
|
|
|
|
- **Maintainer**: gary@hansenit.solutions
|
|
- **Organization**: [Hansen IT Solutions](https://hansenit.solutions) |