From 6023a0f3b441db31b1ac7dc525be475d17d12634 Mon Sep 17 00:00:00 2001 From: Gary Date: Sat, 10 Jan 2026 22:55:56 +1100 Subject: [PATCH] add GitHub Actions workflow for Bash syntax checking and enhance README with usage examples --- .gitea/workflows/syntax-check.yml | 43 +++++++ README.md | 182 +++++++++++++++++++++++++----- 2 files changed, 199 insertions(+), 26 deletions(-) create mode 100644 .gitea/workflows/syntax-check.yml diff --git a/.gitea/workflows/syntax-check.yml b/.gitea/workflows/syntax-check.yml new file mode 100644 index 0000000..1e3fed6 --- /dev/null +++ b/.gitea/workflows/syntax-check.yml @@ -0,0 +1,43 @@ +name: Bash Syntax Check + +on: + push: + branches: + - main + - master + - develop + paths: + - 'slackecho' + - '.gitea/workflows/syntax-check.yml' + pull_request: + branches: + - main + - master + - develop + paths: + - 'slackecho' + +jobs: + syntax-check: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v3 + + - name: Install shellcheck + run: sudo apt-get update && sudo apt-get install -y shellcheck + + - name: Run bash syntax check + run: bash -n slackecho + + - name: Run shellcheck analysis + run: shellcheck slackecho + + - name: Verify script is executable + run: | + if [[ -x slackecho ]]; then + echo "✓ slackecho has executable permission" + else + echo "✗ slackecho is missing executable permission" + exit 1 + fi diff --git a/README.md b/README.md index ca4406c..3aa1016 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,166 @@ -# README # +# slackecho -Need a quick way to send a message to slack from the command line? This will do the job (and not much else) +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. +Useful inside scripts to report back to an administrator, monitor cron jobs, or integrate with CI/CD pipelines. -### What is this repository for? ### +## What is this repository for? -* Shell script that uses curl to send a message to slack -* Very simple -* By [Hansen IT Solutions](https://hansenit.solutions) +- **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) -### How do I get set up? ### +## Installation -* Summary of set up - * Install curl to your system. - * Copy the slackecho script to your binary path -* Configuration - * Update the SLACKURL with your own (todo: create a config file and a way to setup the file on first run) - * Update the 'defaults' within the script -* Dependencies - * curl -* How to run tests - * N/A +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 + ``` -### Contribution guidelines ### +2. **Copy script to binary path** + ```bash + sudo cp slackecho /usr/local/bin/ + sudo chmod +x /usr/local/bin/slackecho + ``` -###TODO### -* Writing tests -* Code review -* Other guidelines -* Configuration moved to a seperate file +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 -### Who do I talk to? ### +## Usage -* gary@hansenit.solutions \ No newline at end of file +### Command Signature + +```bash +slackecho [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) \ No newline at end of file