Fjord Notify

Push CI events to your phone. Send a rich notification to the Fjord mobile relay (status, message, deep-link buttons) from any workflow step, with a Forgejo comment fallback when the relay isn't configured or is unreachable. No github.com.

Part of the Fjord Actions bundle. This is the shared transport the other phone-in-the-loop actions (the approval gate, app-distribution pushes) reuse.

There is no GitHub equivalent: GitHub has no first-party mobile push you can self-host. The closest thing is wiring up a third-party Slack/Telegram action.

Usage

jobs:
  deploy:
    runs-on: [self-hosted, Linux]
    steps:
      - run: ./deploy.sh

      - name: notify on failure
        if: failure()
        uses: https://rasterhub.com/fjord/fjord-notify-action@v1
        with:
          status: failure
          title: 'Prod deploy failed'
          message: 'core image build broke on ${{ github.sha }}'
          buttons: |
            View run=${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
            Re-run=${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        env:
          FJORD_RELAY_URL: ${{ vars.FJORD_RELAY_URL }}
          FJORD_RELAY_TOKEN: ${{ secrets.FJORD_RELAY_TOKEN }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}   # for the comment fallback

With no relay configured it posts a Forgejo comment instead, so it's useful even before the relay exists.

Inputs

Input	Default	Description
status	info	success / failure / warning / info / cancelled.
title	repo + status	Notification title.
message		Body (markdown in the comment fallback).
run-url	this run	Link to open.
buttons		Deep-link buttons, one per line as Label=https://url.
target		Relay-defined route (channel / user / team).
relay-url	FJORD_RELAY_URL env	Relay endpoint. Unset -> comment only.
relay-token	FJORD_RELAY_TOKEN env	Bearer token for the relay.
comment-fallback	true	Comment on the PR/commit when the relay is unset or fails.
pr-number	from context	PR to comment on for the fallback.
fail-on-error	false	Fail the step if nothing was delivered.
token	GITHUB_TOKEN env	Forgejo token for the comment fallback.
api_url / repository	derived	Forgejo API base / repo.

Outputs

Output	Description
delivered	relay / comment / relay+comment / none.

Best-effort by default: a delivery failure logs a warning but does not fail your job (set fail-on-error: true to change that).

Relay contract

If you point relay-url at your Fjord relay, the action sends:

POST <relay-url>
Authorization: Bearer <relay-token>
Content-Type: application/json

{
  "event": "ci-notification",
  "repository": "owner/name",
  "run_id": 555,
  "run_url": "https://forge.example/owner/name/actions/runs/555",
  "status": "failure",
  "title": "Prod deploy failed",
  "message": "core image build broke",
  "buttons": [{ "label": "View run", "url": "https://..." }],
  "target": "ops",
  "actor": "ci-bot",
  "commit": { "sha": "cafebabe", "ref": "refs/heads/main" }
}

The relay authenticates the bearer token, maps repository/target to device subscriptions, and pushes to the Fjord app. Any 2xx is success; the relay stamps its own receipt timestamp. Implement that endpoint however you like, the action only needs the contract above.

License

MIT, see LICENSE.