add GitHub Actions workflow for Bash syntax checking and enhance README with usage examples

2026-01-10 22:55:56 +11:00
parent 26a15aa3bc
commit 6023a0f3b4
2 changed files with 199 additions and 26 deletions
--- a/.gitea/workflows/syntax-check.yml
+++ 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
--- 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
   
-### Contribution guidelines ###
+   # macOS
+   brew install curl
   
-###TODO###
-* Writing tests
-* Code review
-* Other guidelines
-* Configuration moved to a seperate file
+   # CentOS/RHEL
+   sudo yum install curl
+   ```

-### Who do I talk to? ###
+2. **Copy script to binary path**
+   ```bash
+   sudo cp slackecho /usr/local/bin/
+   sudo chmod +x /usr/local/bin/slackecho
+   ```

-* gary@hansenit.solutions
+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)