Deprecation notice: `github-action-test-galaxy-import` will be archived in February 2027

> **Deprecation notice**
>
> This GitHub Action and its bundled reusable workflow are deprecated and are planned to be archived in **February 2027**. Please migrate existing workflows before then.

### What is being deprecated?

This repository provides:

- The `github-action-test-galaxy-import` composite action.
- The bundled `.github/workflows/test-galaxy-import.yml` reusable workflow.

The current composite action requires an `artifact-path` and optionally accepts `collection-requirements-path` and `importer-config-path`. Its current defaults are Python `3.13` and the `stable-2.18` ansible-core branch.

### Why is this being deprecated?

These actions were useful when the main alternative for collection build and Galaxy import checks was a considerably slower Zuul workflow. Most collections have since moved to other testing approaches, and maintaining a dedicated action and shared workflow for this narrow operation is no longer worth the maintenance cost.

The action also combines several operations that collection test tooling can manage as part of a broader, reproducible test environment:

1. Installs `ansible-core`.
2. Installs `galaxy-importer`.
3. Optionally installs collection dependencies from a requirements file with `ansible-galaxy collection install --pre`.
4. Runs `python -m galaxy_importer.main` against the collection artifact.
5. Emits GitHub warnings for importer output lines beginning with `ERROR:`.

The bundled reusable workflow additionally builds the collection artifact before running the importer. Collection maintainers can replace this narrow workflow with a complete, locally reproducible collection test setup using [`antsibull-nox`](https://docs.ansible.com/projects/antsibull-nox/) or [`tox-ansible`](https://ansible.readthedocs.io/projects/tox-ansible/).

The decision and migration discussion are documented in the [Ansible forum thread](https://forum.ansible.com/t/deprecate-build-collection-and-test-import-to-galaxy-github-actions-and-shared-workflows/46184).

### Timeline

- **Now:** The action and bundled workflow are deprecated. New users should not adopt them.
- **Before February 2027:** Existing users should migrate their workflows.
- **February 2027:** This repository and its bundled reusable workflow are planned to be archived.

## Migration guidance

Choose the migration that best fits the collection's existing test infrastructure.

### Option 1: use `antsibull-nox`

`antsibull-nox` can run the collection build and Galaxy importer check as a named nox session. Add the following to `antsibull-nox.toml`:

```toml
version = 1

[sessions]

[sessions.build_import_check]
run_galaxy_importer = true
```

Add a `noxfile.py` that loads this configuration. The following is the same pattern used by `community.vmware`:

```python
# The following metadata allows Python runners and nox to install the required
# dependencies for running this Python script:
#
# /// script
# dependencies = ["nox>=2025.02.09", "antsibull-nox"]
# ///

import sys

import nox

try:
import antsibull_nox
except ImportError:
print("You need to install antsibull-nox in the same Python environment as nox.")
sys.exit(1)

antsibull_nox.load_antsibull_nox_toml()

if __name__ == "__main__":
nox.main()
```

Then add a workflow to run nox:

```yaml
---
name: nox
'on':
push:
branches:
- main
- stable-*
pull_request:

permissions:
contents: read

jobs:
nox:
runs-on: ubuntu-latest
name: Run nox
steps:
- name: Check out collection
uses: actions/checkout@v7
with:
persist-credentials: false

- name: Run nox
uses: ansible-community/antsibull-nox@efe6769cb9fa52e98fd6b3a4711dbd588e5512ce
```

Change the `main` and `stable-*` branch filters in this example as needed for the collection's branch layout.

Pin the GitHub Actions used by the workflow according to the collection's CI policy. The SHA above is the one currently used by `community.vmware`; update it to the approved version when adopting the workflow.

The `build_import_check` session builds the collection and runs the Galaxy importer locally in the nox environment, so the check can be run both in CI and during local development:

```bash
uv run nox -s build_import_check
```

Depending on the collection's existing nox setup, maintainers may run the session with the repository's normal nox command instead.

#### `community.vmware` reference implementation

`community.vmware` removed the old shared workflow in [PR #2563](https://github.com/ansible-collections/community.vmware/pull/2563), which merged on August 19, 2026. The resulting implementation provides a concrete migration example:

- [`antsibull-nox.toml`](https://github.com/ansible-collections/community.vmware/blob/main/antsibull-nox.toml)
- [`noxfile.py`](https://github.com/ansible-collections/community.vmware/blob/main/noxfile.py)
- [`.github/workflows/nox.yml`](https://github.com/ansible-collections/community.vmware/blob/main/.github/workflows/nox.yml)
- [Migration PR #2563](https://github.com/ansible-collections/community.vmware/pull/2563)

The original migration was tracked in [`community.vmware` issue #2561](https://github.com/ansible-collections/community.vmware/issues/2561).

### Option 2: use `tox-ansible`

[`tox-ansible`](https://github.com/ansible/tox-ansible) integrates collection testing with tox-managed environments and supports a dedicated `galaxy` environment that builds the collection and runs `galaxy-importer`.

Install `tox-ansible` and add its configuration to the collection's `pyproject.toml`:

```toml
[tool.tox]
requires = ["tox>=4.2"]

[tool.tox-ansible]
```

List the generated environments and run the Galaxy environment:

```bash
uv run tox list --ansible
uv run tox -e galaxy --ansible
```

This approach is useful when the collection already uses tox-ansible for sanity, unit, integration, or Molecule testing, because the Galaxy importer check becomes another reproducible tox environment rather than a separate GitHub only workflow.

### Existing custom importer workflows

Collections with specialised Galaxy importer configuration or custom artifact/dependency handling can keep those steps in a normal GitHub Actions job. The direct equivalent of this action is:

```yaml
- name: Set up Python
uses: actions/setup-python@v7
with:
python-version: '3.13'

- name: Install ansible-core and Galaxy importer
run: |
python -m pip install ansible-core galaxy-importer

- name: Install collection dependencies
if: ${{ hashFiles('requirements.yml') != '' }}
run: ansible-galaxy collection install --pre --requirements-file requirements.yml

- name: Run Galaxy importer
run: python -m galaxy_importer.main dist/example-demo-1.0.0.tar.gz
```

If an importer configuration file is required, preserve the equivalent environment variable used by the action:

```yaml
- name: Run Galaxy importer with custom configuration
env:
GALAXY_IMPORTER_CONFIG: importer-config.cfg
run: python -m galaxy_importer.main dist/example-demo-1.0.0.tar.gz
```

### Questions and migration reports

Please comment on this issue with:

- A link to the migration pull request or commit.
- Which replacement tooling was selected.
- Any problems encountered while replacing this action.
- Any collection-specific requirements that are not covered by the examples above.

Thank you to everyone who used and maintained this action.