releases-notifier

README

releases-notifier

Receive Slack notifications if a new release of your favorite software is available on GitHub or any provider using Forgejo, Gitea or Gitlab.

Features

• Supports Forgejo, Gitea, Gitlab and GitHub.
• Slack messages can be customized.
• Helm chart is provided for easier installation.
• Multi-arch container images for amd64/arm64.

This project is a fork of justwatchcom/github-releases-notifier, but was since then changed quite significantly. Apart from the features above, this fork...

• removes dotenv support
• changes the logger to logrus and improves logging
• loads repositories from a text file instead of using -r CLI flags
• improves CLI parsing
• implements batching for GitHub API requests

Install

Download one of the precompiled releases, use the ready-made container image codeberg.org/xrstf/releases-notifier or install from source:

$ go install go.xrstf.de/releases-notifier

Usage

Usage of releases-notifier:
      --dry-run                 do not send Slack notifications
  -i, --interval duration       duration between checking each repository for new releases (default 1h0m0s)
      --no-warmup               do not prewarm the releases cache, i.e. immediately report any found releases
  -r, --repositories string     path to a text file containing one repository per line
      --slack-icon string       the emoji to use in Slack (without the surrounding colons) (only for non-app based webhooks) (default "git")
      --slack-messages string   path to a file with possible Slack message templates
      --slack-username string   the name to use on Slack (only for non-app based webhooks) (default "Releases Notifier")
  -v, --verbose                 enable more verbose logging
  -V, --version                 show version info and exit immediately

Configuring repositories to watch

Repositories are configured in a simple text file, with one repository per line. Lines follow a simple format:

• domain/owner/name is the most basic form and means https://domain/owner/name.
• provider:domain/owner/name can be used to tell the releases-notifier which API scheme to use. provider can be one of github, gitea, forgejo or gitlab. Note that some well-known Gitea/Forgejo/Gitlab instances are built-in already.

Comments can be included by starting a line with #.

github.com/xrstf/releases-notifier
github.com/kubernetes/kubernetes
github.com/helm/helm

# codeberg.org is one of the built-in domains.
codeberg.org/xrstf/releases-notifier

# for unknown domains, explicitly configure the API scheme
gitea:example.com/helm/helm

By default only stable releases will be reported, but if you add prerelease to a line, the notifier will report on prereleases as well:

github.com/kubernetes/kubernetes prerelease

Use the --repositories flag to point the notifier to your file.

Authentication

releases-notifier reads all authentication information from environment variables. There are two names it tests to find a token for a given domain/provider combination:

• first, <PROVIDER_UPPERCASE>_TOKEN_<domain_lowercase> (e.g. FORGEJO_TOKEN_codeberg.org)
• if no such env variable exists, it checks <PROVIDER_UPPERCASE>_TOKEN, for example GITHUB_TOKEN.

This allows you to go easy if you have a single domain for a provider (usually the case with GitHub), but also be able to configure multiple Gitea instances, for example.

Customizing Slack Messages

Using the --slack-messages flag, you can load a text file with your own Slack message templates in it. The file must contain one Go template per line (empty lines are allowed and automatically skipped).

Each template can make use of the following data:

type templateData struct {
	Repo    Repository
	Release Release

	// shortcuts
	Title string
	Link  string
}

type Repository struct {
	Provider  GitProvider
	Domain    string
	Name      string
	Owner     string
	Preleases bool
}

type Release struct {
	Repository   Repository
	Name         string
	URL          url.URL
	PublishedAt  time.Time
	IsDraft      bool
	IsPrerelease bool
	Body         string
}

The default template if no custom Slack messages are given is:

<{{.Link}}|{{.Title}}> has been released.

Deploying

1. Get a URL to send WebHooks to your Slack from https://api.slack.com/incoming-webhooks.
2. Create a repos.txt text file with your repositories in it, according to the documented steps above.
3. For each domain and/or provider, acquire an authentication token. See above for the necessary environment variables.

Docker

docker run \
  --rm \
  -e "SLACK_HOOK=https://hooks.slack.com/..." \
  # for each provider/domain, add your envs here
  -e "GITHUB_TOKEN=XXX" \
  -e "FORGEJO_TOKEN_codeberg.org=YYY" \
  -v "$(realpath .):/work" \
  -w "/work" \
  codeberg.org/xrstf/releases-notifier \
    --interval 5m \
    --repositories repos.txt \
    --dry-run

Kubernetes (Helm)

First add the chart repo:

helm repo add releases-notifier https://xrstf.codeberg.page/releases-notifier

Then create a values.yaml and follow the example configuration in there. Note that the Chart is configured a bit differently than releases-notifier itself, but you'll get the hang of it.

Once your values file is ready, install the chart like so:

helm upgrade \
  --install \
  --namespace releases-notifier \
  --create-namespace \
  --values values.yaml \
  releases-notifier releases-notifier/releases-notifier

License

MIT