Deprecation notice: `github-action-build-collection` will be archived in February 2027

> **Deprecation notice**
>
> This action is deprecated and is planned to be archived in **February 2027**. Please migrate existing workflows before then.

### Why is this action being deprecated?

This action was useful when the main alternative for collection build and Galaxy import checks was a considerably slower Zuul workflow. The ecosystem has since moved on, and building an Ansible collection is now a small, well-supported CI/CD step that can be expressed directly in GitHub Actions.

Maintaining a dedicated action and bundled reusable workflow for this narrow operation is no longer worth the maintenance cost. Collection maintainers can also use broader collection testing tools such as [`antsibull-nox`](https://docs.ansible.com/projects/antsibull-nox/) or [`tox-ansible`](https://github.com/ansible/tox-ansible) when they need a complete test workflow rather than only a build step.

This decision and the 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 is deprecated. New users should not adopt it.
- **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

The action performs three relevant operations:

1. Sets up Python and installs ansible-core.
2. Optionally creates a Galaxy `requirements.yml` from dependencies in `galaxy.yml`.
3. Runs `ansible-galaxy collection build`.

These operations can be represented directly in a workflow.

### Basic collection build

For a collection at the repository root:

```yaml
name: Build collection

on:
push:
pull_request:

jobs:
build-collection:
runs-on: ubuntu-latest
permissions:
contents: read

steps:
- name: Check out code
uses: actions/checkout@v7

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

- name: Install ansible-core
run: python -m pip install ansible-core

- name: Build collection
run: ansible-galaxy collection build --output-path dist

- name: Upload collection artifact
uses: actions/upload-artifact@v7
with:
name: collection-build-${{ github.sha }}
path: dist/
```

Pin GitHub Actions to commit SHAs if that is the repository's CI policy. The Python and ansible-core versions should also be selected and pinned according to the collection's supported test matrix. The deprecated action currently defaults to Python `3.13` and the `stable-2.18` ansible-core branch; repositories that need equivalent behavior should choose a corresponding explicit ansible-core version or branch.

The build command creates an artifact named from the collection metadata:

```text
--.tar.gz
```

### Collections in a subdirectory

Set the working directory to the directory containing `galaxy.yml` and keep the output directory outside that source tree:

```yaml
- name: Build collection
working-directory: collections/ansible_collections/example/demo
run: ansible-galaxy collection build --output-path "$GITHUB_WORKSPACE/dist"
```

The deprecated action's `subdirectory` input serves the same purpose.

### Creating `requirements.yml`

The `collection-requirements-path` input in `action.yml` is optional. When supplied, the action reads the `dependencies` mapping from `galaxy.yml` and writes a Galaxy requirements file with one entry per dependency:

```yaml
collections:
- name: community.general
source: https://galaxy.ansible.com
version: '>=8.0.0'
```

The action writes `collections: []` when there are no dependencies. It sorts dependency names and preserves each dependency's version constraint. The following step reproduces that behavior and writes the file into the build artifact directory:

```yaml
- name: Create Galaxy requirements file
env:
COLLECTION_DIR: .
shell: python
run: |
import os
from pathlib import Path
import yaml

collection_dir = Path(os.environ['COLLECTION_DIR'])
galaxy_file = collection_dir / 'galaxy.yml'
requirements_file = Path('dist/requirements.yml')

with galaxy_file.open('rb') as stream:
galaxy = yaml.safe_load(stream) or {}

requirements = {'collections': []}
for name, version in sorted((galaxy.get('dependencies') or {}).items()):
requirements['collections'].append({
'name': name,
'source': 'https://galaxy.ansible.com',
'version': version,
})

requirements_file.parent.mkdir(parents=True, exist_ok=True)
with requirements_file.open('w', encoding='utf-8') as stream:
yaml.safe_dump(requirements, stream, sort_keys=False)
```

For a collection in a subdirectory, change `COLLECTION_DIR` to that directory, for example:

```yaml
env:
COLLECTION_DIR: collections/ansible_collections/example/demo
```

Because ansible-core brings the required YAML library into the environment, this step can run after the ansible-core installation step above. If the repository manages its Python dependencies separately, ensure `PyYAML` is installed before running the `requirements.yml` generator described above.

The generated file can then be uploaded with the collection artifact:

```yaml
- name: Upload collection and requirements
uses: actions/upload-artifact@v7
with:
name: collection-build-${{ github.sha }}
path: dist/
```

### Add an explicit collection version

The current action writes `version: 0.0.1` into `galaxy.yml` when no version is present. A direct `ansible-galaxy collection build` workflow should not rely on that implicit fallback. Add and maintain an explicit `version` in `galaxy.yml`, or generate the version as part of the repository's release process before the build step.

### Questions and migration reports

Please comment on this issue with:

- A link to the migration pull request or commit.
- 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.