UK Bin Collection Data (UKBCD)

The integration configuration is a multi-step process.

Step 1: Basic Setup

Provide the following initial details:

• name: A unique identifier for this configuration.
• council: Select your council from the dropdown (listed by its wiki name).
• manual_refresh_only (Optional): If enabled, the integration will not auto-update; you must trigger updates manually. Defaults to False.
• icon_color_mapping (Optional): A JSON string to customize bin icons and colors.

Step 2: Council-Specific Details

Fields in this step are dynamic and depend on your selected council. Common fields include:

• url: The data access URL (may be pre-filled).
• uprn: Unique Property Reference Number.
• postcode: Your address postcode.
• number: Your house number.
• usrn: Unique Street Reference Number.
• web_driver: Command for Selenium if required by the council.
• headless: Whether to run the browser in headless mode (default True).
• local_browser: Whether to use a local browser instance (default False).
• timeout: Request timeout in seconds (minimum 10, default 60).
• update_interval: Refresh frequency in hours (minimum 1, default 12).

To keep your calendar updated automatically, you can create a shell script that runs the collection and generation process, then schedule it using cron.

Example Script (update_bin_calendar.sh):

#!/bin/bash
# Set variables
COUNCIL="YourCouncilName"
COUNCIL_URL="https://your-council-website.gov.uk/bins"
POSTCODE="YOUR_POSTCODE"
HOUSE_NUMBER="YOUR_HOUSE_NUMBER"
OUTPUT_DIR="/var/www/html/calendars"
CALENDAR_NAME="Household Bins"

mkdir -p $OUTPUT_DIR

cd /path/to/UKBinCollectionData && \
python uk_bin_collection/uk_bin_collection/collect_data.py $COUNCIL "$COUNCIL_URL" \
  -p "$POSTCODE" -n "$HOUSE_NUMBER" | \
python bin_to_ics.py --name "$CALENDAR_NAME" --output "$OUTPUT_DIR/bins.ics" --alarms "1d,6h"

echo "Calendar last updated: $(date)" > "$OUTPUT_DIR/last_update.txt"

Scheduling: To run the script every Monday at 2 AM, add this to your crontab: 0 2 * * 1 /path/to/update_bin_calendar.sh

#!/bin/bash
# File: update_bin_calendar.sh

# Set variables
COUNCIL="YourCouncilName"
COUNCIL_URL="https://your-council-website.gov.uk/bins"
POSTCODE="YOUR_POSTCODE"
HOUSE_NUMBER="YOUR_HOUSE_NUMBER"
OUTPUT_DIR="/var/www/html/calendars"  # Web-accessible directory
CALENDAR_NAME="Household Bins"

# Ensure output directory exists
mkdir -p $OUTPUT_DIR

# Run the collector and generate the calendar
cd /path/to/UKBinCollectionData && \
python uk_bin_collection/uk_bin_collection/collect_data.py $COUNCIL "$COUNCIL_URL" \
  -p "$POSTCODE" -n "$HOUSE_NUMBER" | \
python bin_to_ics.py --name "$CALENDAR_NAME" --output "$OUTPUT_DIR/bins.ics" --alarms "1d,6h"

# Add timestamp to show last update time
echo "Calendar last updated: $(date)" > "$OUTPUT_DIR/last_update.txt"

To allow the release workflow to bypass branch protection rules and push commits/tags securely, you can set up a GitHub App. This is preferred over Personal Access Tokens because it provides fine-grained permissions, does not expire, and has a better audit trail.

Step 1: Create the GitHub App

1. Navigate to settings:
   • Personal account: https://github.com/settings/apps/new
   • Organization: https://github.com/organizations/YOUR_ORG/settings/apps/new
2. Basic Info:
   • GitHub App name: UKBinCollection Release Bot (or a unique variation like UKBinCollection-Release-Bot-YourUsername)
   • Homepage URL: https://github.com/robbrad/UKBinCollectionData
3. Webhook: Uncheck "Active" under "Webhook".
4. Permissions:
   • Contents: Read and write (Required for pushing commits and tags)
   • Metadata: Read-only (Default)
   • Pull requests: Read and write (Optional)
5. Installation Scope: Select "Only on this account".
6. Click "Create GitHub App".

Step 2: Install the App

1. In the app settings, click "Install App" in the left sidebar.
2. Click "Install" next to your account/organization.
3. Select "Only select repositories" and check UKBinCollectionData.
4. Click "Install".

Step 3: Generate and Retrieve Credentials

1. Generate Private Key: In the app settings, scroll to "Private keys" and click "Generate a private key". A .pem file will download.
2. App ID: Copy the numeric ID found at the top of the app settings page.
3. Private Key Content: Open the .pem file and copy the entire contents, including the headers:

   -----BEGIN RSA PRIVATE KEY-----
   [long string of characters]
   -----END RSA PRIVATE KEY-----

Step 4: Add Secrets to Repository

Navigate to your repository's Settings → Secrets and variables → Actions and add the following:

Step 5: Verify

Merge a PR with a conventional commit message to trigger the bump workflow and check the logs.