GitHub Actions — NotiLens Docs

Overview

What This Integration Does

Add NotiLens to any GitHub Actions workflow to receive instant push notifications when your builds, deployments, or scheduled jobs complete — no polling, no dashboards.

Works with any workflow: CI, CD, cron jobs, release pipelines, and more. Automatically includes GitHub context — repo, branch, commit, actor, and a direct link to the run.

Setup

1. Add Secrets to Your Repository

Get your token and secret from the NotiLens dashboard, then add them as GitHub secrets:

Go to your repository → Settings → Secrets and variables → Actions
Click New repository secret
Add NOTILENS_TOKEN — your topic token
Add NOTILENS_SECRET — your topic secret

Usage

2. Add the Action to Your Workflow

Basic

CI with Pass/Fail

Deployment

Scheduled Job

# .github/workflows/notify.yml
- uses: notilens/notify-action@v1
  with:
    token:   ${{ secrets.NOTILENS_TOKEN }}
    secret:  ${{ secrets.NOTILENS_SECRET }}
    agent:   my-ci
    event:   task.completed
    message: Build passed

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Notify start
        uses: notilens/notify-action@v1
        with:
          token:   ${{ secrets.NOTILENS_TOKEN }}
          secret:  ${{ secrets.NOTILENS_SECRET }}
          agent:   my-ci
          event:   task.started
          message: "Build started for ${{ github.repository }}"

      - name: Run tests
        run: npm test

      - name: Notify success
        if: success()
        uses: notilens/notify-action@v1
        with:
          token:   ${{ secrets.NOTILENS_TOKEN }}
          secret:  ${{ secrets.NOTILENS_SECRET }}
          agent:   my-ci
          event:   task.completed
          message: "Build passed — ${{ github.ref_name }}"

      - name: Notify failure
        if: failure()
        uses: notilens/notify-action@v1
        with:
          token:   ${{ secrets.NOTILENS_TOKEN }}
          secret:  ${{ secrets.NOTILENS_SECRET }}
          agent:   my-ci
          event:   task.failed
          message: "Build failed — ${{ github.ref_name }}"

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to production
        run: ./deploy.sh

      - name: Notify deploy success
        if: success()
        uses: notilens/notify-action@v1
        with:
          token:        ${{ secrets.NOTILENS_TOKEN }}
          secret:       ${{ secrets.NOTILENS_SECRET }}
          agent:        deploy
          event:        task.completed
          message:      "Deployed to production"
          tags:         deploy,production
          open_url:     https://myapp.com

      - name: Notify deploy failure
        if: failure()
        uses: notilens/notify-action@v1
        with:
          token:   ${{ secrets.NOTILENS_TOKEN }}
          secret:  ${{ secrets.NOTILENS_SECRET }}
          agent:   deploy
          event:   task.failed
          message: "Production deployment failed"

# .github/workflows/nightly.yml
name: Nightly Backup

on:
  schedule:
    - cron: '0 2 * * *'  # 2am UTC daily

jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - name: Run backup
        run: ./backup.sh

      - name: Notify complete
        if: success()
        uses: notilens/notify-action@v1
        with:
          token:   ${{ secrets.NOTILENS_TOKEN }}
          secret:  ${{ secrets.NOTILENS_SECRET }}
          agent:   cron-jobs
          event:   task.completed
          message: "Nightly backup completed"
          task_id: "backup_${{ github.run_id }}"
          tags:    backup,nightly

      - name: Notify failure
        if: failure()
        uses: notilens/notify-action@v1
        with:
          token:   ${{ secrets.NOTILENS_TOKEN }}
          secret:  ${{ secrets.NOTILENS_SECRET }}
          agent:   cron-jobs
          event:   task.failed
          message: "Nightly backup failed"
          task_id: "backup_${{ github.run_id }}"

Inputs

Action Inputs

Input	Required	Default	Description
`token`	Yes		NotiLens topic token from dashboard
`secret`	Yes		NotiLens topic secret from dashboard
`agent`	Yes		Agent name — identifies the sender
`event`	Yes		Event type (e.g. `task.completed`, `task.failed`)
`message`	No	event name	Notification message body
`task_id`	No	GitHub run ID	Task identifier — groups related notifications
`type`	No	auto	Override type: `info` `success` `warning` `urgent`
`tags`	No		Comma-separated tags (e.g. `deploy,production`)
`open_url`	No	workflow run URL	URL opened when notification is tapped
`image_url`	No		Image URL to display in the notification
`download_url`	No		Download URL to attach

Events Reference

Recommended Events for CI/CD

Event	Type	When to use
task.started	info	Job or workflow started
task.completed	success	Job succeeded, build passed, deploy done
task.failed	urgent	Job failed, tests failed, deploy failed
task.timeout	urgent	Job exceeded time limit
task.cancelled	warning	Job was manually cancelled
task.error	urgent	Non-fatal error during job
input.required	warning	Waiting for manual approval in workflow
emit	info	Any custom event

Auto-Context

Automatically Included GitHub Context

Every notification sent by the action automatically includes the following metadata — no configuration needed.

Field	Value
workflow	Workflow name (e.g. `CI`)
repository	Owner/repo (e.g. `acme/my-app`)
branch	Branch or tag name (e.g. `main`)
commit	Short commit SHA (e.g. `a1b2c3d`)
actor	Who triggered the run (e.g. `john`)
trigger	Event that triggered the run (e.g. `push`)
open_url	Direct link to the workflow run (auto-set if not provided)

Note

Non-Breaking by Design

The action never fails your workflow. If NotiLens is unreachable or credentials are incorrect, the action logs a warning and continues — your build result is not affected.