{"id":22998236,"url":"https://github.com/uswitch/hermod","last_synced_at":"2025-08-14T00:31:55.177Z","repository":{"id":42526037,"uuid":"377086742","full_name":"uswitch/hermod","owner":"uswitch","description":"The Messenger of the Gods","archived":false,"fork":false,"pushed_at":"2024-07-08T14:57:52.000Z","size":237,"stargazers_count":11,"open_issues_count":3,"forks_count":0,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-07-08T18:45:33.906Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uswitch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-15T08:13:23.000Z","updated_at":"2024-07-08T14:57:49.000Z","dependencies_parsed_at":"2024-06-21T15:31:32.625Z","dependency_job_id":"621c380e-ddcb-477e-b929-7a32b7b76b37","html_url":"https://github.com/uswitch/hermod","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fhermod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fhermod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fhermod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uswitch%2Fhermod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uswitch","download_url":"https://codeload.github.com/uswitch/hermod/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229786999,"owners_count":18124014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-15T06:12:16.496Z","updated_at":"2024-12-15T06:12:17.068Z","avatar_url":"https://github.com/uswitch.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"Hermod\n======\n## About\n\n[Hermod](https://en.wikipedia.org/wiki/Herm%C3%B3%C3%B0r) takes its name from the Norse messenger of the gods.  \nIt tracks deployments as they roll out and posts useful status updates into Slack.  \nIt does this by watching the kubernetes api for namespaces and deployments with the correct annotations. When a new deployment rollout begins and completes updates are posted to the Slack API.  \nAny errors during the deployment rollout are captured and included in the Slack message (see example below). This can be very useful to help quickly debug a failing deployment.\n\nHermod will notify when a new deployment starts rolling out:  \n![Deployment started notification](images/deploy-start.png?raw=true \"Deployment started\")  \n\nWhen a deployment successfully rolls out:  \n![Deployment succeeded notification](images/deploy-end-success.png?raw=true \"Deployment succeeded\")  \n\nWhen a deployment fails to roll out:  \n![Deployment failed notification](images/deploy-end-fail.png?raw=true \"Deployment failed\")  \n\n## Prerequisite\n- Read about Slack API documentation [here](https://api.slack.com/#read_the_docs) \u0026 [here](https://api.slack.com/start) and create a Slack App for Hermod in your organisation.\n\n## To deploy Hermod\n\n1. Deploy Hermod to your kubernetes cluster  \n    See [example](./example) directory for sample kubernetes manifests.  \n2. Install Hermod app in your Slack directory [here](https://slack.com/apps).\n3. Add Hermod to any channels in which you want to receive updates from Hermod.\n4. Create resources for hermod to track.\n\n## Resource annotations\n\n### Namespace annotations\n\n| annotation | example | description | notes |\n|---|---|---|---|\n| `hermod.uswitch.com/slack` | \"hermod-updates\" | Configures which Slack channel to post updates to | Required for each namespace that hermod should monitor. Different namespaces can send updates to different Slack channels |\n| `hermod.uswitch.com/alert` | \"failure\" | Only notify on deployment rollout failure | Optional |\n\n### Deployment annotations\n\n| annotation | example | description |\n|---|---|---|\n| `hermod.uswitch.com/gitsha` | 2dafeb708437f6e537d19556d461e30aa96d4244 | Optional. Commit SHA of code deployment. The name of this annotation is configurable, see [here](#options). |\n| `hermod.uswitch.com/gitrepo` | https://github.com/my-org/my-app | Optional. Git Repo Url of code deployment. The name of this annotation is configurable, see [here](#options). |\n\n## Add resources for Hermod to track\n\n1. Annotate or create a namespace for hermod to monitor:\n```\napiVersion: v1\nkind: Namespace\nmetadata:\n  name: hermod-test-ns\n  annotations:\n    # The presence of this annotation enables hermod for the namespace and configures where to post updates in Slack\n    hermod.uswitch.com/slack: \u003cslack-channel-to-receive-notifications\u003e \n    # Optional, notify only on deployment failure\n    hermod.uswitch.com/alert: failure \n```\n2. Add a new deployment in that namespace for hermod to monitor:\n```\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  annotations:\n    # commit SHA of this deployment, used in slack messages, optional\n    hermod.uswitch.com/gitsha: c48655970ce3485815638ff8e430d9c69588bed2 \n    # link to git repo, used in slack messages, optional\n    hermod.uswitch.com/gitrepo: https://github.com/my-org/my-app\n  labels:\n    app: nginx\n  name: nginx-deployment\n  namespace: hermod-test-ns\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      app: nginx\n  template:\n    metadata:\n      labels:\n        app: nginx\n    spec:\n      containers:\n      - image: nginx\n        name: nginx\n```\n\n## To build:\n```\nmake\n```  \nExecutable binaries will be created in the `bin/` directory.\n\n## To run:\n```\nSLACK_TOKEN=XXXX make run\n```\n\n## Options\n\n| flag  | default | description |\n|---|---|---|\n| --kubeconfig  | \"\" | Path to kubeconfig file (leave blank when running in k8s pod)  |\n| --level | info | log level  |\n| --repo-url-annotation  | hermod.uswitch.com/gitrepo | Annotation you will add to tracked deployments. This indicates the respository location and is used when publishing messages to slack. |\n| --commit-sha-annotation  | hermod.uswitch.com/gitsha | Annotation you will add to tracked deployments. This indicates the commit SHA deployed and is used when publishing messages to slack. |\n| --git-annotation-warning | false | option to enable warning level logs if previous annotations are missing |\n\n## Environment Variables\n\n| name  | default | required | description |\n|---|---|---|---|\n| SLACK_TOKEN | \"\" | y | API token for Slack |\n| SENTRY_ENDPOINT | \"\" | n | [Sentry DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/) |\n| CLUSTER_NAME | \"\" | n | Name of your kubernetes cluster, used in Slack messages |\n\n## Monitoring\n\n### Prometheus\nHermod exposes some prometheus metrics on port `2112` at `/metrics`.\n\n| name  | description  | type |\n|---|---|---|\n| hermod_deployment_processed_total | The total number of deployments processed | Counter |\n| hermod_deployment_success_total | The total number of successful deployments processed | Counter |\n| hermod_deployment_failed_total | The total number of failed deployments processed | Counter |\n\n### Sentry\nHermod can also publish some error events to [Sentry](https://sentry.io).  \nThis is optional but can be enabled by configuring the `SENTRY_ENDPOINT` environment variable and setting it to your [Sentry DSN](https://docs.sentry.io/product/sentry-basics/dsn-explainer/).  \n\n## To make an update to Hermod\n1. Create a Pull request against this project's `main` branch.\n2. When your changes are reviewed and merged we will tag and release a new version for you.\n3. A new docker image will be automatically created with the given tag.\n4. Update your kubernetes deployment to use the new image.\n\n## Support\n\nIf you come across issues please raise an issue against the GitHub project. Include as much detail as you can (including relevant logs, hermod version, kubernetes version, etc) so we have the best chance of understanding what went wrong.\n\n## Contributing\n\nContributions are always welcome. Please feel free to raise a pull request and we will review as soon as we can.\n\n## More like this\nCheck our other open source projects here:\nhttps://www.rvu.co.uk/open-source\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fhermod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuswitch%2Fhermod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuswitch%2Fhermod/lists"}