| name | update-snow-release |
| description | Add or drop ServiceNow release support in servicenow.itsm (integration CI matrix, README compatibility table, changelog fragment). Use when the user asks to support a new SNOW release, drop an EOL release, update the test matrix, or mentions release codenames (e.g. Australia, Xanadu, Zurich). |
Update ServiceNow release support
This collection does not branch module code on SNOW release names. Support is expressed through CI, README, and changelogs. See also AGENTS.md → Integration CI.
Scope
In scope: .github/workflows/integration_source.yml, README.md compatibility table, changelogs/fragments/, maintainer notes in AGENTS.md if conventions change.
Out of scope (unless integration tests fail): plugins/, tests/, module doc URLs with old bundle names (bundle/tokyo-...), hand-editing CHANGELOG.rst or changelogs/changelog.yaml (generated at release).
Decision: upgrade in place vs new PDI
| Scenario | Workflow change | GitHub secrets |
|---|
| Upgrade existing newest PDI (usual) | Change servicenow-version label only; keep SN_*_<instance_id> | Do not create or rename secrets — instances upgrade in place |
| Add a new PDI to the matrix | Add matrix entry + full include block | Create eight secrets once in the protected-snow environment: SN_HOST_<id>, SN_USERNAME_<id>, SN_PASSWORD_<id>, SN_CLIENT_ID_<id>, SN_CLIENT_SECRET_<id>, SN_API_KEY_<id>, SN_CLIENT_CERTIFICATE_<id>, SN_CLIENT_KEY_<id> |
Instance ID = numeric suffix from the PDI hostname (e.g. dev7056 → 7056).
Workflow checklist
Copy and track progress:
- [ ] Confirm new release codename and which PDI instance is upgraded
- [ ] Update integration_source.yml matrix
- [ ] Update README.md compatibility table
- [ ] Add changelogs/fragments/<issue>-<topic>.yaml
- [ ] Remind maintainer: GitHub secrets / instance upgrade (if not done)
- [ ] Open PR using .github/pull_request_template.md
1. Integration CI — .github/workflows/integration_source.yml
Only file with release-specific configuration. Matrix keeps three SNOW versions (newest + two older).
Upgrade in place (replace oldest / dropped release on newest instance):
servicenow-version:
- "<new_release>"
- "yokohama"
- "zurich"
include:
- servicenow-version: "<new_release>"
sn_host_secret: SN_HOST_<instance_id>
sn_username_secret: SN_USERNAME_<instance_id>
Do not name secrets by release codename (e.g. SN_HOST_YOKOHAMA) — always use the PDI instance ID suffix.
Leave workflow comments above servicenow-version intact (they document the instance-ID convention).
Current matrix → instance mapping (update this table when the matrix changes):
servicenow-version | PDI instance | Secret suffix |
|---|
australia | dev7056 | _7056 |
yokohama | dev7054 | _7054 |
zurich | dev7055 | _7055 |
2. README — compatibility table
In README.md (Supported ServiceNow versions):
- Add new release at the top:
| <NewRelease> | <next_collection_version>+ | TBA |
- Retire dropped release: set EOL quarter and bound collection range (e.g.
2.7.0 - 2.14.0 | Q2 2026), following Washington/Vancouver/Xanadu rows.
- Next collection version = bump after current
galaxy.yml version (e.g. 2.14.0 → document 2.15.0+).
3. Changelog fragment — required
Create changelogs/fragments/<descriptive-name>.yaml:
---
minor_changes:
- add support for SNOW <NEW_RELEASE> release
- tests - Drop testing of <OLD_RELEASE>, as it is no longer supported by the collection
Adjust wording if only adding (no drop) or only dropping. Per AGENTS.md, behavior/support changes need a fragment.
4. Discover other references
rg -i '<old_release>|<new_release>' --glob '!CHANGELOG*' --glob '!changelogs/changelog.yaml'
Expect hits only in workflow, README, changelogs, and historical docs — not in plugins/ or tests/.
5. Pull request
Use .github/pull_request_template.md:
- ISSUE TYPE: Feature Pull Request (release support)
- COMPONENT NAME:
integration CI / collection compatibility
- ADDITIONAL INFORMATION: List maintainer GitHub secret actions and which matrix leg uses which instance ID
Prefer ci: commit prefix. Example: ci: add Australia release support and drop Xanadu from test matrix
Draft PR against ansible-collections/servicenow.itsm main from the contributor fork.
The user should be able to confirm the new version is valid via the CI running in their PR.
Reference: Australia / Xanadu (2026)
| Item | Value |
|---|
| Added | australia on instance 7056 (SN_*_7056) |
| Dropped from CI | xanadu (same instance, upgraded in place) |
| README | Australia 2.15.0+; Xanadu 2.7.0 - 2.14.0, EOL Q2 2026 |
| Secret naming | All matrix legs use instance ID suffixes (SN_*_7054, SN_*_7055, SN_*_7056), not release codenames |
Prior art: upstream PR adding Zurich (dropped Washington from matrix); commit adding Xanadu to matrix; migration from SN_*_YOKOHAMA / SN_*_ZURICH to instance IDs.
