> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relnx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Check outdated tools in CI

> Fail your CI build when a tracked tool is behind, or has unacknowledged security fixes or breaking changes — with the Relnx GitHub Action. Enterprise.

> The **`relnx/check-outdated`** GitHub Action compares the tool versions your
> repo pins against Relnx's release data and **fails the build** when something
> is behind — or, more importantly, when a newer version contains **security
> fixes** or **breaking changes** you haven't picked up yet. Every run also
> posts a summary table to the workflow.

This turns "we forgot to upgrade" into a CI check, the same way you'd catch a
failing test.

## What you'll need

| Requirement                  | Notes                                                                                  |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| **Enterprise plan**          | The action authenticates with a Relnx API key, which is an Enterprise feature.         |
| **A Relnx API key**          | Created at the organization level (see step 1).                                        |
| **A way to list your tools** | Either a Helm `Chart.lock` in the repo, or an explicit list you write in the workflow. |

## Step 1 — Create a Relnx API key

1. In Relnx, go to **Org → Settings → API Keys**.
2. Click **Generate key**, give it a name (e.g. *CI — platform repo*), and
   **copy it immediately** — it's shown only once.

API keys belong to the **organization**, so any owner/admin can create or
revoke them, and they keep working if the person who made them leaves.

## Step 2 — Add the key as a GitHub secret

In the GitHub repo: **Settings → Secrets and variables → Actions → New
repository secret**.

* **Name**: `RELNX_API_KEY`
* **Value**: the key you copied

## Step 3 — Add the workflow

Create `.github/workflows/relnx-check.yml`. Pick whichever way of listing tools
fits your repo:

```yaml theme={null}
name: Dependency freshness
on:
  pull_request:
  schedule:
    - cron: '0 6 * * 1' # every Monday at 06:00 UTC
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Option A — read a Helm Chart.lock (dependencies detected automatically)
      - uses: relnx/check-outdated@v1
        with:
          api-key: ${{ secrets.RELNX_API_KEY }}
          chart-lock: ./charts/platform/Chart.lock
          fail-on: security

      # Option B — list tools explicitly, one "slug@version" per line
      - uses: relnx/check-outdated@v1
        with:
          api-key: ${{ secrets.RELNX_API_KEY }}
          tools: |
            argo-cd@2.10.0
            cert-manager@1.14.0
          fail-on: breaking
```

You can combine `chart-lock` and `tools` in one step — results are de-duplicated
by slug.

## Inputs

| Input        | Required | Default    | Description                                                           |
| ------------ | -------- | ---------- | --------------------------------------------------------------------- |
| `api-key`    | ✅        | —          | Your Relnx API key. Always pass it from a secret.                     |
| `tools`      | —        | —          | One `slug@version` per line.                                          |
| `chart-lock` | —        | —          | Path to a Helm `Chart.lock`; its dependencies are read automatically. |
| `fail-on`    | —        | `security` | When to fail the job — see below.                                     |
| `api-url`    | —        | Relnx API  | Override only for self-hosted/testing.                                |

### Choosing `fail-on`

| Value                  | The build fails when…                                 | Good for                                     |
| ---------------------- | ----------------------------------------------------- | -------------------------------------------- |
| `security` *(default)* | any tool has a **security fix** in a newer version    | most teams — block on the stuff that matters |
| `breaking`             | any tool has a **breaking change** in a newer version | gating upgrades that need migration work     |
| `outdated`             | any tool is **behind** at all                         | strict "stay current" policies               |
| `none`                 | never fails — only reports                            | dashboards / scheduled visibility            |

### Finding a tool's slug

The slug is the last part of the tool's Relnx URL: `relnx.io/tools/`**`argo-cd`**.
Tools that Relnx doesn't track are listed under **"Not tracked"** in the summary
and never fail the build.

## What a run looks like

The action writes a table to the **GitHub Step Summary**:

| Tool         | Current  | Latest   | Behind       | 🔒 Security | ⚠️ Breaking |
| ------------ | -------- | -------- | ------------ | ----------- | ----------- |
| ArgoCD       | `2.10.0` | `2.13.3` | 5 behind     | 3           | 1           |
| cert-manager | `1.14.0` | `1.14.0` | ✅ up to date | 0           | 0           |

It also sets step **outputs** you can use later in the job:

```yaml theme={null}
      - uses: relnx/check-outdated@v1
        id: relnx
        with:
          api-key: ${{ secrets.RELNX_API_KEY }}
          chart-lock: ./Chart.lock
          fail-on: none           # report only, decide downstream
      - if: steps.relnx.outputs.security != '0'
        run: echo "::warning::${{ steps.relnx.outputs.security }} tool(s) have security fixes available"
```

Outputs: `outdated`, `security`, `breaking` (counts).

## Troubleshooting

| You see                            | Cause                                                 | Fix                                                                                  |
| ---------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `401 ... invalid API key`          | The key is wrong, revoked, or the secret is empty     | Re-check the `RELNX_API_KEY` secret; regenerate the key in Org → Settings → API Keys |
| `403 ... requires a plan upgrade`  | The org's plan no longer includes API access          | The owner's plan must be **Enterprise**                                              |
| `no tools to check`                | Neither `tools` nor a valid `chart-lock` was provided | Set one of them; check the `chart-lock` path                                         |
| A tool shows under **Not tracked** | Relnx doesn't track that tool (or the slug is wrong)  | Check the slug, or [bring your own tool](./bring-your-own-tool)                      |

## Notes

* The action sends only your **tool slugs and versions** (plus the API key for
  auth). No source code leaves your runner.
* `helmfile.yaml` / Helm `values.yaml` auto-detection is on the roadmap; until
  then, use the explicit `tools` input for those.

## Related

* [Create Jira / Linear tickets from a release](./create-tickets) — turn a
  flagged upgrade into a tracked ticket.
* [Upgrade tools via pull request](./upgrade-tools-via-pr) — let Relnx open the
  actual upgrade PR.
* [Compare two tool versions](./compare-versions) — see exactly what changed.