{"id":21475142,"url":"https://github.com/snapp-incubator/jira-MSTeams-proxy","last_synced_at":"2025-07-15T09:32:13.722Z","repository":{"id":180172937,"uuid":"664578028","full_name":"snapp-incubator/jira-MSTeams-proxy","owner":"snapp-incubator","description":"A proxy to forward Jira ticket changes to Microsoft Teams via webhooks","archived":false,"fork":false,"pushed_at":"2025-06-07T12:52:06.000Z","size":74,"stargazers_count":10,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-07T13:19:53.288Z","etag":null,"topics":["appdelivery","go","golang","jira","msteams","msteams-integration","msteamsmessage","snappcloud"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snapp-incubator.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,"zenodo":null}},"created_at":"2023-07-10T09:35:55.000Z","updated_at":"2025-06-07T12:52:10.000Z","dependencies_parsed_at":null,"dependency_job_id":"74b6e03f-369b-47b2-b96d-ae5452e86075","html_url":"https://github.com/snapp-incubator/jira-MSTeams-proxy","commit_stats":null,"previous_names":["snapp-incubator/jira-element-proxy","snapp-incubator/jira-msteams-proxy"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/snapp-incubator/jira-MSTeams-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapp-incubator%2Fjira-MSTeams-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapp-incubator%2Fjira-MSTeams-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapp-incubator%2Fjira-MSTeams-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapp-incubator%2Fjira-MSTeams-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snapp-incubator","download_url":"https://codeload.github.com/snapp-incubator/jira-MSTeams-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snapp-incubator%2Fjira-MSTeams-proxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265425320,"owners_count":23762900,"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":["appdelivery","go","golang","jira","msteams","msteams-integration","msteamsmessage","snappcloud"],"created_at":"2024-11-23T10:37:49.068Z","updated_at":"2025-07-15T09:32:13.714Z","avatar_url":"https://github.com/snapp-incubator.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Jira to Microsoft Teams Webhook Proxy\n\n[![Go](https://img.shields.io/badge/Go-1.18%2B-blue?logo=go)](https://golang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA lightweight, configurable webhook proxy written in Go that receives Jira issue notifications and forwards them as richly formatted, user-mention-enabled messages to specific Microsoft Teams channels.\n\nThis service acts as a middleman, translating raw Jira webhook data into structured and readable [Adaptive Cards](https://adaptivecards.io/) for Microsoft Teams, making it easier for teams to track Jira activity directly where they collaborate.\n\n## Features\n\n  * **Jira Webhook Consumer:** Receives and processes webhook events from Jira for issue creation, updates, and comments.\n  * **Dynamic Channel Routing:** Forwards notifications to different MS Teams channels based on a `/:team` parameter in the webhook URL (e.g., `/platform`, `/runtime`, `/network`).\n  * **Rich Teams Notifications:** Formats messages as Adaptive Cards, a significant improvement over plain text.\n  * **User @Mentions:** Automatically @mentions the Jira issue's \"Issuer\" (Creator) and \"Assignee\" in the Teams notification, ensuring they see the update.\n  * **Highly Configurable:** All target webhook URLs are managed via a simple `config.yml` file or can be overridden with environment variables.\n  * **Containerized:** Includes a `Dockerfile` for easy deployment and testing with Docker.\n  * **Health Check:** Provides a `/healthz` endpoint for Kubernetes readiness/liveness probes.\n\n## How It Works\n\nThe data flow is simple and effective:\n\n1.  **Jira Event:** An action occurs in Jira (e.g., an issue is updated).\n2.  **Webhook Trigger:** Jira sends an HTTP POST request with a detailed JSON payload to this proxy service. The URL provided to Jira includes a team-specific path (e.g., `http://your-proxy-service/runtime`).\n3.  **Proxy Service Processing:**\n      * The service receives the request and binds the JSON to its internal Go structs.\n      * It looks up the correct MS Teams webhook URL from `config.yml` based on the `/runtime` path parameter.\n      * It extracts key information (summary, type, issuer, assignee, issue URL).\n      * It constructs a detailed Adaptive Card JSON payload, including the @mention data for the relevant users.\n4.  **Notification Delivery:** The proxy sends the final Adaptive Card payload to the configured Microsoft Teams Incoming Webhook URL.\n5.  **Teams Renders Card:** Microsoft Teams receives the payload and renders a rich, interactive card with clickable mentions and buttons in the designated channel.\n\n## Getting Started\n\n### Prerequisites\n\n  * **Go:** Version 1.18 or higher.\n  * **Docker:** Recommended for running the application in a consistent environment.\n  * **Jira Instance:** With administrative permissions to create webhooks.\n  * **Microsoft Teams:** With permissions to add an \"Incoming Webhook\" connector to a channel.\n\n### 1. Configure Microsoft Teams\n\nFor each Teams channel you want to send notifications to, you must create a unique **Incoming Webhook URL**:\n\n1.  In Microsoft Teams, navigate to the target channel.\n2.  Click the three dots (•••) next to the channel name and select **Connectors**.\n3.  Search for **Incoming Webhook**, click **Add**, and then **Configure**.\n4.  Give the webhook a name (e.g., \"Jira Notifications\") and optionally upload an icon.\n5.  Click **Create**.\n6.  **Copy the generated Webhook URL.** This is a sensitive URL that you will add to your `config.yml`.\n7.  Repeat this process for each channel (e.g., one for the default route, one for the \"runtime\" team, etc.).\n\n### 2\\. Configure the Proxy Application (`config.yml`)\n\nIn the root of the project, create a `config.yml` file. This file tells the application where to send notifications.\n\n```yaml\n# config.yml\napi:\n  port: 8080 # The port on which the proxy service will listen.\n\n# Holds the webhook URLs for Microsoft Teams.\nmsteams:\n  # The default URL used if the webhook URL doesn't specify a team (e.g., http://your-proxy/)\n  # or if the specified team is not runtime, platform, or network.\n  url: \"YOUR_DEFAULT_MS_TEAMS_WEBHOOK_URL_HERE\"\n  \n  # URL for the \"runtime\" team (triggered by http://your-proxy/runtime).\n  runtime_url: \"YOUR_RUNTIME_TEAM_MS_TEAMS_WEBHOOK_URL_HERE\"\n\n  # URL for the \"platform\" team (triggered by http://your-proxy/platform).\n  platform_url: \"YOUR_PLATFORM_TEAM_MS_TEAMS_WEBHOOK_URL_HERE\"\n\n  # URL for the \"network\" team (triggered by http://your-proxy/network).\n  network_url: \"YOUR_NETWORK_TEAM_MS_TEAMS_WEBHOOK_URL_HERE\"\n```\n\nYou can also override these settings using environment variables with the `MYAPP_` prefix. For example:\n\n  * `MYAPP_API_PORT=9000`\n  * `MYAPP_MSTEAMS_URL=\"your-url-here\"`\n  * `MYAPP_MSTEAMS_RUNTIME_URL=\"your-runtime-url-here\"`\n\n### 3\\. Run the Application\n\n#### Using Docker (Recommended)\n\n1.  **Build the Docker image:**\n\n    ```bash\n    docker build -t jira-msteams-proxy .\n    ```\n\n2.  **Run the container:**\n    This command runs the proxy on port `8080` and mounts your local `config.yml` into the container's working directory (`/root/` in this example; adjust if your Dockerfile's `WORKDIR` is different).\n\n    ```bash\n    docker run --rm -p 8080:8080 \\\n      -v $(pwd)/config.yml:/root/config.yml \\\n      jira-msteams-proxy\n    ```\n\n#### Running Locally\n\n1.  **Install dependencies:**\n    ```bash\n    go mod tidy\n    ```\n2.  **Run the application:**\n    ```bash\n    go run ./cmd/webhook-proxy/ api\n    ```\n\n### 4\\. Configure Jira Webhook\n\n1.  Navigate to your Jira project settings: **Project Settings \\\u003e Automation**.\n2.  Click **Create rule**.\n3.  **Name:** Give it a clear name, e.g., \"MS Teams Notifications\".\n4.  **URL:** This is the URL to your running proxy service, including the team path.\n      * Add Component `Send web request`\n      * To send notifications for the \"platform\" team to their specific channel, at Webhook URL use:\n        `http://\u003cyour_proxy_service_host_or_ip\u003e:8080/comment/platform` and set `Issue data` as `Webhook body`.\n      * To send notifications to the default channel, use:\n        `http://\u003cyour_proxy_service_host_or_ip\u003e:8080/default` (or just `/`)\n\n## API Endpoints\n\n| Method | Path                | Description                                        |\n|--------|---------------------|----------------------------------------------------|\n| `POST` | `/:team`            | Handles issue created/updated events for a specific team. |\n| `POST` | `/`                 | Handles issue created/updated events for the default team. |\n| `POST` | `/comment/:team`    | Handles issue comment events for a specific team.  |\n| `POST` | `/comment`          | Handles issue comment events for the default team.   |\n| `GET`  | `/healthz`          | Health check endpoint. Returns HTTP 204 No Content. |\n\n## Testing\n\nYou can simulate a Jira webhook request using `curl`.\n\n1.  **Create a `sample_jira_payload.json` file** with a realistic payload (you can get one from the Jira REST API or a webhook catcher like `webhook.site`). Ensure it contains populated `creator` and `assignee` objects with valid `emailAddress`, `name`, and `displayName` fields for testing mentions.\n\n2.  **Run this `curl` command** to send the test payload to the \"runtime\" team endpoint:\n\n    ```bash\n    curl -X POST \\\n      -H \"Content-Type: application/json\" \\\n      -d @sample_jira_payload.json \\\n      http://localhost:8080/runtime\n    ```\n\n    This will trigger a notification in the MS Teams channel configured for `runtime_url` in your `config.yml`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnapp-incubator%2Fjira-MSTeams-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnapp-incubator%2Fjira-MSTeams-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnapp-incubator%2Fjira-MSTeams-proxy/lists"}