Expiry Tracker documentation

Expiry Tracker is an app for Jira and Jira Service Management Cloud. It keeps a list of things that expire (SSL certificates, domains, software licenses, contracts) and creates a Jira issue for the owner ahead of each expiry date.

Get started

Install the app from the Atlassian Marketplace (a Jira administrator does this).
Open the settings: Jira settings → Apps → Expiry Tracker (in the left sidebar), or the "Open settings" button on the app page. Choose the project and issue type for reminder issues and save. Click Send test issue to check that the app can create issues there.
Add items: open Apps → Expiry Tracker and click Add item.

Until a project and an issue type are saved, the app shows a warning and creates no issues.

Items

Type	What you enter	Where the date comes from
SSL certificate	Host name, optionally with a port (`host:8443`)	The SSL agent on your network (see below). You can also enter a date manually as a fallback.
Domain	Domain name	The domain registry, looked up when you save and once a day. Registries without machine-readable data (for example .de, .io, .eu) need a manual date; the item tells you.
License	Expiry date	You
Contract	Expiry or renewal date	You

Every item can have an owner (the reminder issue is assigned to them), a vendor, a cost with currency, and a note.

The list shows a status for each item:

Status	Meaning
OK	Further away than your largest reminder threshold
Expiring	Inside your largest threshold
Critical	Inside your smallest threshold, including the expiry day itself
Expired	The date has passed
Unknown	No date yet (lookup pending or failed; the reason is shown under the item name)

Reminder issues

Once a day the app checks every item. When an item reaches a threshold (by default 60, 30 and 7 days before expiry), it creates one issue:

summary such as [Expiry] SSL certificate portal.example.com expires in 30 days (2026-12-10);
description with the date, host, vendor, cost and note;
label expiry-tracker;
assigned to the item's owner. If Jira does not accept the owner, the issue is created unassigned.

Rules worth knowing:

One issue per item per day at most. If an item is added late and has already passed several thresholds, you get one issue for the most urgent one, not one for each.
An issue that could not be created is retried the next day.
When an item's date moves forward (it was renewed), reminders start again for the new date.
No extra issue is created on or after the expiry date.

Administrators can change the thresholds in the settings (up to five values between 1 and 365 days) and use Run check now to run the daily check immediately. The settings page shows the result of the last run.

SSL agent

Atlassian apps cannot open connections to your servers. Certificates are therefore checked by a small shell script that you run on a Linux machine in your network. It needs only sh, curl and openssl.

What it does, once a day: asks Expiry Tracker which hosts to check, reads each host's certificate expiry date, and sends the dates (or error messages) back. It works for hosts that are not reachable from the internet and for certificates from private CAs.

Set it up from the settings page: Create agent token, then follow the three commands shown there (save the settings, download the script from the app, run it and add it to cron).

If the agent has not reported for 48 hours, the app shows a warning and opens one Jira issue. A new token replaces the old one, so replace the token if it may have leaked.

CSV export

Export CSV on the app page shows all items as CSV text: copy it into a file. Columns: type, name, host, port, expiry date, days left, status, date source, vendor, cost, currency, owner account ID, note, last checked, last error.

Permissions

Anyone who can open the app page can view, add, edit and delete items and export the CSV.
Settings, the test issue, "Run check now" and the agent token are available to Jira administrators only.

The app asks Jira for these permissions: read and write Jira work (to list projects and issue types and to create issues), read users (to pick and show owners), and app storage.

Limits

500 items per Jira site.
One daily check; domain lookups that would make the check too long are continued the next day.
Without an active licence the app is read-only: your data stays visible and exportable, but nothing can be changed and no issues are created.

SSL agent reference

A small shell script that reads TLS certificate expiry dates on your network and reports them to Expiry Tracker for Jira. Atlassian apps cannot open connections to your servers, so this script does it from a machine you control. It also works for hosts that are not reachable from the internet.

One file, about 130 lines of POSIX sh. Read it before you run it.
Needs only sh, curl and openssl. No root, no daemon, no inbound ports.
Sends, per host: the certificate's "not after" date or an error message; plus the agent version and a name (by default this machine's host name). Nothing else.

Install

In Jira: Settings → Apps → Expiry Tracker → Create agent token. Copy the URL and the token (shown once).
On a Linux machine that can reach your hosts and the internet, save the settings and download the script. The script is served by the app itself, so you always get the version that matches your installation:

umask 077
cat > expiry-agent.env <<'EOF'
EXPIRY_TRACKER_URL='https://…'
EXPIRY_TRACKER_TOKEN='…'
EOF

. ./expiry-agent.env
curl -fsSL -H "Authorization: Bearer $EXPIRY_TRACKER_TOKEN" -o expiry-agent.sh "$EXPIRY_TRACKER_URL?download=agent"
chmod +x expiry-agent.sh

Test it:

./expiry-agent.sh expiry-agent.env

Expected output: one ok or FAILED line per host, then report accepted. The hosts are the SSL items you added in Jira.

Run it daily

cron:

( crontab -l 2>/dev/null; echo "17 3 * * * $PWD/expiry-agent.sh $PWD/expiry-agent.env" ) | crontab -

systemd (as root; adjust paths and user):

# /etc/systemd/system/expiry-agent.service
[Unit]
Description=Expiry Tracker SSL agent
[Service]
Type=oneshot
User=expiry
ExecStart=/opt/expiry-agent/expiry-agent.sh /opt/expiry-agent/expiry-agent.env

# /etc/systemd/system/expiry-agent.timer
[Unit]
Description=Run the Expiry Tracker SSL agent daily
[Timer]
OnCalendar=daily
RandomizedDelaySec=1h
Persistent=true
[Install]
WantedBy=timers.target

systemctl daemon-reload && systemctl enable --now expiry-agent.timer

If the agent does not report for 48 hours, Expiry Tracker opens a Jira issue.

Settings

Variable	Meaning	Default
`EXPIRY_TRACKER_URL`	Agent URL from the settings page	required
`EXPIRY_TRACKER_TOKEN`	Agent token from the settings page	required
`EXPIRY_TRACKER_TIMEOUT`	Seconds to wait per host	`10`
`EXPIRY_TRACKER_AGENT_ID`	Name shown in Jira	host name

Exit codes: 0 report accepted (even if some hosts failed), 1 could not talk to Expiry Tracker, 2 configuration problem.

Troubleshooting

HTTP 401: the token is wrong or was replaced. Create a new one in Jira.
HTTP 403: the app has no active licence on the Jira site.
HTTP 000: no connection to the URL (proxy, firewall, DNS).
A host shows FAILED: run openssl s_client -connect host:port -servername host </dev/null by hand to see why.

Security notes

Keep the env file readable only by the user that runs the agent (chmod 600).
Anyone with the token can read the list of SSL host names you track and submit certificate dates. Replace the token in Jira if it may have leaked.
The agent does not verify certificate chains: it reports the date of whatever certificate the host presents, which is what you want for expiry tracking, including private CAs.

License: MIT.