Jetpack Connection Triage CLI Command

Goal

The goal of this command is to surface, triage, and clean up our broken Jetpack connections.

Why?

• When we create staging sites and testing sites, or migrate an existing site to a new host, we often get new Jetpack IDs. 
• The old orphaned IDs clutter up our account and Network Admin, and every bulk command we run in our CLI still tries to access these disconnected sites. 
• We can surface which staging sites are merely broken and need fixed by cleaning up the ones that are disconnected.

Cadence

We have a job that runs on the first day of each month to open a dev request to remind us to review broken Jetpack sites and clean up their connections: https://github.com/a8cteam51/team51-dev-requests/blob/trunk/.github/workflows/jetpack-connection-triage.yml

CLI Command

Use this command to identify and analyze sites with Jetpack connection problems. It will check connection status and generate a CSV report with details about problematic connections.

You can either provide a CSV of specific sites to check, or run it without arguments to check all connected Jetpack sites.

  Examples:

    Check all Jetpack sites:

      $ team51 jetpack:connection-triage

    Check specific sites from a CSV:

      $ team51 jetpack:connection-triage /path/to/sites.csv

  CSV Format:

  The input CSV should have 2 columns:

  - Column 1: Blog ID (numeric WordPress.com blog ID)

  - Column 2: Site URL (full URL including protocol)

  Generated Report:

  The command generates a CSV report with the following columns:

  - Site ID: The WordPress.com blog ID

  - Site URL: The site's URL

  - Status: HTTP status code from connection check

  - New Blog ID: If site has a new connection, the new blog ID

  - Notes: Detailed findings and recommended actions

What do to with the results

You will get a CSV that looks like this:

███████████████

What to do

• If the notes say “Jetpack is probably disconnected”, log in and reconnect Jetpack to the a8cteam51 account.
  • ███████████████
  • ███████████████

• If the site has a 500 error and the notes say “Check site”, the site is probably broken and you should check the logs for fatals, resolve them, and check the Jetpack connection again. 
• If the notes say “Site is probably deactivated”, double check that the site no longer exists, then disconnect Jetpack in Network Admin.
  • Go to: ███████████████
  • Search for the site
  • Click Disconnect

███████████████

• If the notes say “Site has a new Jetpack connection”:
  • If the URL is a production site, stop what you are doing and have a discussion with the team in Slack so we don’t inadvertently break something or lost stats.
  • If the URL is a staging website, go to ███████████████
  • Search for the URL
  • Find the listing with the OLD blog ID (listed in the spreadsheet) and disconnect it. 
• If the notes say “Site either moved hosts or has a new JP connection.”, check DARC, Network Admin, and the site. It could be a redirect, it could be a site that has moved, it could be a fresh connection. Evaluate manually and decide whether to disconnect Jetpack, reconnect Jetpack, fix an identity crisis, add a bypass for Jetpack connections for a redirect, or something else.
• If the notes are blank and the status is in the 400 range, manual digging is required. The site could be private, broken, behind Cloudflare, etc.

Helpful tools

• Jetpack debugger
• ███████████████
• ███████████████