From 9a0f62e018cd169b1fcec06774173e2e7e7384ce Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Thu, 5 Feb 2026 11:25:14 +0000 Subject: [PATCH 1/3] github: add needs-more-info automation workflow Add GitHub Actions automation that helps manage issues requiring additional information from reporters: - Post an instruction comment when 'needs-more-info' label is added, requesting environment details, debug logs from multiple nodes, configuration files, and proper formatting - Automatically remove the label when anyone comments - Close the issue after 3 days if no response is provided - Exempt needs-more-info labeled issues from the stale bot The instruction comment includes guidance on: - Required environment and debug information - Collecting logs from both connecting and connected-to nodes - Proper redaction rules (replace consistently, never remove IPs) - Formatting requirements for attachments and Markdown - Encouragement to discuss on Discord before filing issues --- .github/label-response/needs-more-info.md | 80 +++++++++++++++++++ .github/workflows/needs-more-info-comment.yml | 28 +++++++ .github/workflows/needs-more-info-timer.yml | 31 +++++++ .github/workflows/stale.yml | 2 +- 4 files changed, 140 insertions(+), 1 deletion(-) create mode 100644 .github/label-response/needs-more-info.md create mode 100644 .github/workflows/needs-more-info-comment.yml create mode 100644 .github/workflows/needs-more-info-timer.yml diff --git a/.github/label-response/needs-more-info.md b/.github/label-response/needs-more-info.md new file mode 100644 index 00000000..6550a502 --- /dev/null +++ b/.github/label-response/needs-more-info.md @@ -0,0 +1,80 @@ +Thank you for taking the time to report this issue. + +To help us investigate and resolve this, we need more information. Please provide the following: + +> [!TIP] +> Many issues turn out to be configuration errors rather than bugs. We encourage you to discuss your problem in our [Discord community](https://discord.gg/c84AZQhmpx) **before** opening an issue. The community can often help identify misconfigurations quickly, saving everyone time. + +## Required Information + +### Environment Details + +- **Headscale version**: (run `headscale version`) +- **Tailscale client version**: (run `tailscale version`) +- **Operating System**: (e.g., Ubuntu 24.04, macOS 14, Windows 11) +- **Deployment method**: (binary, Docker, Kubernetes, etc.) +- **Reverse proxy**: (if applicable: nginx, Traefik, Caddy, etc. - include configuration) + +### Debug Information + +Please follow our [Debugging and Troubleshooting Guide](https://headscale.net/stable/ref/debug/) and provide: + +1. **Client netmap dump** (from affected Tailscale client): + + ```bash + tailscale debug netmap > netmap.json + ``` + +2. **Client status dump** (from affected Tailscale client): + + ```bash + tailscale status --json > status.json + ``` + +3. **Tailscale client logs** (if experiencing client issues): + + ```bash + tailscale debug daemon-logs + ``` + + > [!IMPORTANT] + > We need logs from **multiple nodes** to understand the full picture: + > + > - The node(s) initiating connections + > - The node(s) being connected to + > + > Without logs from both sides, we cannot diagnose connectivity issues. + +4. **Headscale server logs** with `log.level: trace` enabled + +5. **Headscale configuration** (with sensitive values redacted - see rules below) + +6. **ACL/Policy configuration** (if using ACLs) + +7. **Proxy/Docker configuration** (if applicable - nginx.conf, docker-compose.yml, Traefik config, etc.) + +## Formatting Requirements + +- **Attach long files** - Do not paste large logs or configurations inline. Use GitHub file attachments or GitHub Gists. +- **Use proper Markdown** - Format code blocks, logs, and configurations with appropriate syntax highlighting. +- **Structure your response** - Use the headings above to organize your information clearly. + +## Redaction Rules + +> [!CAUTION] +> **Replace, do not remove.** Removing information makes debugging impossible. + +When redacting sensitive information: + +- ✅ **Replace consistently** - If you change `alice@company.com` to `user1@example.com`, use `user1@example.com` everywhere (logs, config, policy, etc.) +- ✅ **Use meaningful placeholders** - `user1@example.com`, `bob@example.com`, `my-secret-key` are acceptable +- ❌ **Never remove information** - Gaps in data prevent us from correlating events across logs +- ❌ **Never redact IP addresses** - We need the actual IPs to trace network paths and identify issues + +**If redaction rules are not followed, we will be unable to debug the issue and will have to close it.** + +--- + +**Note:** This issue will be automatically closed in 3 days if no additional information is provided. Once you reply with the requested information, the `needs-more-info` label will be removed automatically. + +If you need help gathering this information, please visit our [Discord community](https://discord.gg/c84AZQhmpx). diff --git a/.github/workflows/needs-more-info-comment.yml b/.github/workflows/needs-more-info-comment.yml new file mode 100644 index 00000000..306e49ef --- /dev/null +++ b/.github/workflows/needs-more-info-comment.yml @@ -0,0 +1,28 @@ +name: Needs More Info - Post Comment + +on: + issues: + types: [labeled] + +jobs: + post-comment: + if: >- + github.event.label.name == 'needs-more-info' && + github.repository == 'juanfont/headscale' + runs-on: ubuntu-latest + permissions: + issues: write + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + sparse-checkout: .github/label-response/needs-more-info.md + sparse-checkout-cone-mode: false + + - name: Post instruction comment + run: gh issue comment "$NUMBER" --body-file .github/label-response/needs-more-info.md + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_REPO: ${{ github.repository }} + NUMBER: ${{ github.event.issue.number }} diff --git a/.github/workflows/needs-more-info-timer.yml b/.github/workflows/needs-more-info-timer.yml new file mode 100644 index 00000000..4ea723ab --- /dev/null +++ b/.github/workflows/needs-more-info-timer.yml @@ -0,0 +1,31 @@ +name: Needs More Info - Timer + +on: + schedule: + - cron: "0 0 * * *" # Daily at midnight UTC + issue_comment: + types: [created] + issues: + types: [labeled] + workflow_dispatch: + +jobs: + manage-needs-more-info: + if: github.repository == 'juanfont/headscale' + runs-on: ubuntu-latest + permissions: + issues: write + steps: + - name: Manage needs-more-info issues + uses: tiangolo/issue-manager@2fb3484ec9279485df8659e8ec73de262431737d # v0.6.0 + with: + token: ${{ secrets.GITHUB_TOKEN }} + config: > + { + "needs-more-info": { + "delay": "P3D", + "message": "This issue has been automatically closed because no additional information was provided within 3 days.\n\nIf you now have the requested information, please feel free to reopen this issue and provide the details. We're happy to help once we have enough context to investigate.\n\nThank you for your understanding.", + "remove_label_on_comment": true, + "remove_label_on_close": true + } + } diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index 0915ec2c..12afde93 100644 --- a/.github/workflows/stale.yml +++ b/.github/workflows/stale.yml @@ -23,5 +23,5 @@ jobs: since being marked as stale." days-before-pr-stale: -1 days-before-pr-close: -1 - exempt-issue-labels: "no-stale-bot" + exempt-issue-labels: "no-stale-bot,needs-more-info" repo-token: ${{ secrets.GITHUB_TOKEN }} From c7287e219ecb0cc1bde85b18daf1bc7771e7e247 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Thu, 5 Feb 2026 11:32:08 +0000 Subject: [PATCH 2/3] github: add support-request automation workflow Add workflow that automatically closes issues labeled as support-request with a message directing users to Discord for configuration and support questions. The workflow: - Triggers when support-request label is added - Posts a comment explaining this tracker is for bugs/features - Links to documentation and Discord - Closes the issue as "not planned" --- .github/label-response/support-request.md | 15 ++++++++++++ .github/workflows/support-request.yml | 30 +++++++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 .github/label-response/support-request.md create mode 100644 .github/workflows/support-request.yml diff --git a/.github/label-response/support-request.md b/.github/label-response/support-request.md new file mode 100644 index 00000000..cdd93b30 --- /dev/null +++ b/.github/label-response/support-request.md @@ -0,0 +1,15 @@ +Thank you for reaching out. + +This issue tracker is used for **bug reports and feature requests** only. Your question appears to be a support or configuration question rather than a bug report. + +For help with setup, configuration, or general questions, please visit our [Discord community](https://discord.gg/c84AZQhmpx) where the community and maintainers can assist you in real-time. + +**Before posting in Discord, please check:** + +- [Documentation](https://headscale.net/) +- [FAQ](https://headscale.net/stable/faq/) +- [Debugging and Troubleshooting Guide](https://headscale.net/stable/ref/debug/) + +If after troubleshooting you determine this is actually a bug, please open a new issue with the required debug information from the troubleshooting guide. + +This issue has been automatically closed. diff --git a/.github/workflows/support-request.yml b/.github/workflows/support-request.yml new file mode 100644 index 00000000..1e6af893 --- /dev/null +++ b/.github/workflows/support-request.yml @@ -0,0 +1,30 @@ +name: Support Request - Close Issue + +on: + issues: + types: [labeled] + +jobs: + close-support-request: + if: >- + github.event.label.name == 'support-request' && + github.repository == 'juanfont/headscale' + runs-on: ubuntu-latest + permissions: + issues: write + contents: read + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + sparse-checkout: .github/label-response/support-request.md + sparse-checkout-cone-mode: false + + - name: Post comment and close issue + run: | + gh issue comment "$NUMBER" --body-file .github/label-response/support-request.md + gh issue close "$NUMBER" --reason "not planned" + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + GH_REPO: ${{ github.repository }} + NUMBER: ${{ github.event.issue.number }} From 7d504c619e129ea352963959ccca8caac7a660c9 Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Thu, 5 Feb 2026 11:35:04 +0000 Subject: [PATCH 3/3] github: update issue template contact links Reorder contact links to show Discord first, then documentation. Update Discord invite link and docs URL to current values. --- .github/ISSUE_TEMPLATE/config.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 37a8cb80..68ed883d 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -3,9 +3,9 @@ blank_issues_enabled: false # Contact links contact_links: - - name: "headscale usage documentation" - url: "https://github.com/juanfont/headscale/blob/main/docs" - about: "Find documentation about how to configure and run headscale." - name: "headscale Discord community" - url: "https://discord.gg/xGj2TuqyxY" + url: "https://discord.gg/c84AZQhmpx" about: "Please ask and answer questions about usage of headscale here." + - name: "headscale usage documentation" + url: "https://headscale.net/" + about: "Find documentation about how to configure and run headscale."