gcp-notifier 0.1.8

Read Google Secret Manager values and send Email / Google Chat alerts from GCP projects and notebooks, with automatic project detection.

GCP Notifier

Read Google Secret Manager values and send Email / Google Chat alerts from GCP projects and notebooks (Jupyter, Colab, Vertex AI Workbench). The project is auto-detected from the ambient credentials, so get_secret("MY_SECRET") is usually all you need. It wraps the official google-cloud-secret-manager SDK; its value is the project auto-detection and the one-line call.

Synchronous Usage

Import and use in your Python code:

from gcp_notifier import notify, notify_on_failure

# Send a notification (choose channels: "email", "gchat", or both)
notify(
  subject="Alert Subject",
  body="Alert body text",
  channels=["email", "gchat"]  # or ["email"] or ["gchat"]
)

# Use as tenacity retry_error_callback
from tenacity import retry, stop_after_attempt

@retry(stop=stop_after_attempt(3), retry_error_callback=notify_on_failure)
def always_fails():
  # This function will always fail, triggering notify_on_failure after retries
  raise ValueError("This is a test error for notification.")

always_fails()

Async Usage

You can send notifications asynchronously using the async API.

Async notify example

import asyncio  # only if running a script, otherwise, do not import
from gcp_notifier import async_notify

async def main():
  await async_notify(
    subject="Async Alert",
    body="This is an async alert!",
    channels=["email", "gchat"]
  )

asyncio.run(main()) # if running a script
await main()        # if using a notebook

---

Async tenacity error callback example

import asyncio  # only if running a script, otherwise, do not import
from gcp_notifier import async_notify_on_failure
from tenacity import retry, stop_after_attempt

@retry(stop=stop_after_attempt(3), retry_error_callback=async_notify_on_failure)
async def always_fails_async():
  raise ValueError("This is a test error for async notification.")

asyncio.run(always_fails_async())   # if running a script
await always_fails_async()          # if using a notebook

Retrieving Secrets

The same Secret Manager access the library uses internally is exposed as a public helper. project_id defaults to the project detected from the ambient credentials (google.auth.default()), so in most cases you only pass the secret ID.

from gcp_notifier import get_secret

# Uses the auto-detected project
api_key = get_secret("MY_API_KEY")

# Or target a specific project / version explicitly
db_password = get_secret(
    "DB_PASSWORD",
    project_id="my-other-project",
    version_id="3",
)

Raises ValueError if secret_id is empty, or if no project_id is provided and none can be detected from the environment.

Secrets in Notebooks

get_secret is designed to work from notebooks. Importing the package does not fetch any notification secrets, so it stays quiet even when only secret access is needed. You only need credentials the project can be detected from.

In Google Colab, authenticate the interactive user first:

from google.colab import auth
auth.authenticate_user()

from gcp_notifier import get_secret

api_key = get_secret("MY_API_KEY")

On Vertex AI Workbench, or local Jupyter using Application Default Credentials, the credentials are already present (run gcloud auth application-default login once locally), so no auth call is needed:

from gcp_notifier import get_secret

api_key = get_secret("MY_API_KEY")

The account behind those credentials needs the Secret Manager Secret Accessor role on the project (see Quick Start below).

Installation

Install from PyPI (recommended):

pip install gcp-notifier

For async features (async_notify, async_notify_on_failure), install with the optional async dependencies:

pip install 'gcp-notifier[async]'

This will install the package plus the required async libraries (aiosmtplib, httpx).

Quick Start

1. Install the package (see Installation above).

2. The account (personal or service) running this code must have the 'Secret Manager Secret Accessor' role in your GCP project.

3. The required secrets must be in the same GCP project where your Python script or notebook is running.

4. Add your required secrets to Google Secret Manager in your GCP project:

   • GCHAT_WEBHOOK_URL (for Google Chat)
   • EMAIL_SENDER (sender email address for Email)
   • EMAIL_PASSWORD (password or app password for sender)
   • EMAIL_RECIPIENTS (comma-separated list of recipient email addresses)

5. Import and use notify in your code as shown below.

Building and Publishing

This project uses a modern Python packaging workflow with pyproject.toml.

To build the package:

python -m pip install --upgrade build
python -m build

To check and upload to PyPI:

python -m pip install --upgrade twine
twine check dist/*
twine upload dist/*

See the Python Packaging User Guide for more details.

Changelog

See CHANGELOG.md for the release history.

License

MIT