Merge pull request #58 from gotmax23/move_to_collection

Migrate `aur` module from legacy role to collection
pull/61/head
kewl 2021-09-03 18:00:51 +01:00 committed by GitHub
commit c64679b9ff
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 242 additions and 89 deletions

55
.github/workflows/galaxy.yml vendored Normal file
View File

@ -0,0 +1,55 @@
---
name: Build and Publish Collection to Ansible Galaxy
'on':
release:
types: [ published ]
workflow_dispatch:
defaults:
run:
working-directory: collections/ansible_collections/kewlfft/aur
jobs:
release:
runs-on: ubuntu-20.04
steps:
- name: Checkout git repo
uses: actions/checkout@v2
with:
path: collections/ansible_collections/kewlfft/aur
- name: Ensure that `version:` in `galaxy.yml` matches `GITHUB_REF`
id: version
run: |
[ "$(cat galaxy.yml | grep version: | awk '{print $2}')" = $(awk -F '/' '{print substr($3, 2)}' <<< ${GITHUB_REF}) ] || exit 1
echo ::set-output name=version::$(awk -F '/' '{print substr($3, 2)}' <<< ${GITHUB_REF})
- name: "Set up Python 3.9"
uses: actions/setup-python@v2
with:
python-version: "3.9"
- name: Generate cache keys
id: keys
run: |
echo ::set-output name=pip_cache_dir::$(pip cache dir)
# This ensures that the cache is invalidated after a week
echo ::set-output name=date::$(date +%Y_%g)
- name: Pip Cache
uses: actions/cache@v2
with:
path: ${{ steps.keys.outputs.pip_cache_dir }}
key: ansible-pip-${{ steps.keys.outputs.date }}
- name: Install pip packages
run: |
pip3 install -U pip
pip3 install wheel
pip3 install ansible-core
- name: Deploy collection
run: |
ansible-galaxy collection build
ansible-galaxy collection publish --api-key ${{ secrets.GALAXY_API_KEY }} "./kewlfft-aur-${{ steps.version.outputs.version }}.tar.gz"

2
.gitignore vendored Normal file
View File

@ -0,0 +1,2 @@
kewlfft-aur-*.tar.gz
*.swp

166
README.md
View File

@ -1,7 +1,57 @@
# Ansible AUR helper
# Ansible Collection - kewlfft.aur
## Description
This collection includes an Ansible module to manage packages from the AUR.
## Installation
### Install the `kewlfft.aur` collection from Ansible Galaxy
To install this collection from Ansible Galaxy run the following command:
```shell
ansible-galaxy collection install kewlfft.aur
```
Alternatively, you can include the collection in a `requirements.yml` file and then run `ansible-galaxy collection install -r requirements.yml`. Here is an example `requirements.yml` file:
```yaml
collections:
- name: kewlfft.aur
```
### Install the `kewlfft.aur` collection from the AUR
The `kewlfft.aur` collection is also available in the AUR as the `ansible-collection-kewlfft-aur` package.
### Install the `kewlfft.aur` collection locally for development
If you want to test changes to the source code, run the following commands from the root of this git repository to locally build and install the collection:
```shell
ansible-galaxy collection build --force
ansible-galaxy collection install --force "./kewlfft-aur-$(cat galaxy.yml | grep version: | awk '{print $2}').tar.gz"
```
### Install the `aur` module as a local custom module
Alternatively, you may manually install the `aur` module itself as a [local custom module](https://docs.ansible.com/ansible/latest/dev_guide/developing_locally.html) instead of installing the module through the `kewlfft.aur` Ansible collection. However, it is recommended to use `kewlfft.aur` collection unless you have a good reason not to. Here are the commands to install the `aur` module as a local custom module:
```shell
# Create the user custom module directory
mkdir ~/.ansible/plugins/modules
# Install the aur module into the user custom module directory
curl -o ~/.ansible/plugins/modules/aur.py https://raw.githubusercontent.com/kewlfft/ansible-aur/master/plugins/modules/aur.py
```
## kewlfft.aur.aur Module
Ansible module to use some Arch User Repository (AUR) helpers as well as makepkg.
The following helpers are supported and automatically selected, if present, in the order listed below:
- [yay](https://github.com/Jguer/yay)
- [paru](https://github.com/Morganamilo/paru)
- [pacaur](https://github.com/E5ten/pacaur)
@ -10,11 +60,13 @@ The following helpers are supported and automatically selected, if present, in t
- [aurman](https://github.com/polygamma/aurman) (discontinued)
*makepkg* will be used if no helper was found or if it is explicitly specified:
- [makepkg](https://wiki.archlinux.org/index.php/makepkg)
## Options
### Options
| Parameter | Choices/**Default** | Comments |
|--- |--- |---|
| -------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| name | | Name or list of names of the package(s) to install or upgrade. |
| state | **present**, latest | Desired state of the package, 'present' skips operations if the package is already installed. |
| upgrade | yes, **no** | Whether or not to upgrade whole system. |
@ -25,98 +77,88 @@ The following helpers are supported and automatically selected, if present, in t
| skip_pgp_check | yes, **no** | Only valid with makepkg. Skip PGP signatures verification of source file, useful when installing packages without GnuPG properly configured. |
| ignore_arch | yes, **no** | Only valid with makepkg. Ignore a missing or incomplete arch field, useful when the PKGBUILD does not have the arch=('yourarch') field. |
### Note
#### Note
* Either *name* or *upgrade* is required, both cannot be used together.
* In the *use*=*auto* mode, makepkg is used as a fallback if no known helper is found.
## Installing
### AUR package
The [ansible-aur-git](https://aur.archlinux.org/packages/ansible-aur-git) package is available in the AUR.
### Usage
Note: The module is installed in `/usr/share/ansible/plugins/modules` which is one of the default module library paths.
#### Notes
### Manual installation
Just clone the *ansible-aur* repository into your user custom-module directory:
```
git clone https://github.com/kewlfft/ansible-aur.git ~/.ansible/plugins/modules/aur
```
### Ansible Galaxy
*ansible-aur* is available in Galaxy which is a hub for sharing Ansible content. To download it, use:
```
ansible-galaxy install kewlfft.aur
```
Note: If this module is installed from Ansible Galaxy, you will need to list it explicitly in your playbook:
```
# playbook.yml
- hosts: localhost
roles:
- kewlfft.aur
tasks:
- aur: name=package_name
```
or in your role:
```
# meta/main.yml
dependencies:
- kewlfft.aur
```
```
# tasks/main.yml
- aur: name=package_name
```
## Usage
### Notes
* The scope of this module is installation and update from the AUR; for package removal or for updates from the repositories, it is recommended to use the official *pacman* module.
* The *--needed* parameter of the helper is systematically used, it means if a package is up-to-date, it is not built and reinstalled.
### Create the "aur_builder" user
#### Create the "aur_builder" user
While Ansible expects to SSH as root, makepkg or AUR helpers do not allow executing operations as root, they fail with "you cannot perform this operation as root". It is therefore recommended to create a user, which is non-root but has no need for password with pacman in sudoers, let's call it *aur_builder*.
This user can be created in an Ansible task with the following actions:
```
- user:
```yaml
- name: Create the `aur_builder` user
ansible.builtin.user:
name: aur_builder
create_home: no
create_home: yes
group: wheel
- lineinfile:
- name: Allow the `aur_builder` user to run `sudo pacman` without a password
ansible.builtin.lineinfile:
path: /etc/sudoers.d/11-install-aur_builder
line: 'aur_builder ALL=(ALL) NOPASSWD: /usr/bin/pacman'
create: yes
validate: 'visudo -cf %s'
```
### Examples
#### Fully Qualified Collection Names (FQCNs)
In order to use an Ansible module that is distributed in a collection, you must use its FQCN (Fully Qualified Collection Name). A Fuly Qualified Collection Name is "the full definition of a module, plugin, or role hosted within a collection, in the form `namespace.collection.content_name`" ([Source](https://github.com/ansible-collections/overview#terminology)). In this case, the `aur` module resides in the `aur` collection which is under the `kewlfft` namespace, so its FQCN is `kewlfft.aur.aur`.
Please note that this does not apply if you installed the `aur` module as a local custom module. Do to the nature of local custom modules, you can simply use the module's short name: `aur`.
#### Examples
Use it in a task, as in the following examples:
```
# Install trizen using makepkg, skip if it is already installed
- aur: name=trizen use=makepkg state=present
```yaml
# This task uses the module's short name instead of its FQCN.
# Use the short name if you installed the module as a local custom module.
# Otherwise, if you installed the module through the `kewlfft.aur` collection,
this task will fail.
- name: Install trizen using makepkg if it isn't installed already
aur:
name: trizen
use: makepkg
state: present
become: yes
become_user: aur_builder
# Install package_name using the first known helper found
- aur: name=package_name
# This task uses the `aur` module's FQCN (Fully Qualified Collection Name).
- name: Install trizen using makepkg if it isn't installed already
kewlfft.aur.aur:
name: trizen
use: makepkg
state: present
become: yes
become_user: aur_builder
# Install package_name_1 and package_name_2 using yay
- aur:
- name: Install package_name_1 and package_name_2 using yay
kewlfft.aur.aur:
use: yay
name:
- package_name_1
- package_name_2
# Upgrade the system using yay, only act on AUR packages.
# Note: Dependency resolving will still include repository packages.
- aur: upgrade=yes use=yay aur_only=yes
# Note: Dependency resolution will still include repository packages.
- name: Upgrade the system using yay, only act on AUR packages.
kewlfft.aur.aur:
upgrade: yes
use: yay
aur_only: yes
# Install gnome-shell-extension-caffeine-git using pikaur and a local PKGBUILD.
# Skip if it is already installed
- aur:
- name: Install gnome-shell-extension-caffeine-git using pikaur and a local PKGBUILD.
kewlfft.aur.aur:
name: gnome-shell-extension-caffeine-git
use: pikaur
local_pkgbuild: {{ role_path }}/files/gnome-shell-extension-caffeine-git

69
galaxy.yml Normal file
View File

@ -0,0 +1,69 @@
### REQUIRED
# The namespace of the collection. This can be a company/brand/organization or product namespace under which all
# content lives. May only contain alphanumeric lowercase characters and underscores. Namespaces cannot start with
# underscores or numbers and cannot contain consecutive underscores
namespace: kewlfft
# The name of the collection. Has the same character restrictions as 'namespace'
name: aur
# The version of the collection. Must be compatible with semantic versioning
version: 1.0.0
# The path to the Markdown (.md) readme file. This path is relative to the root of the collection
readme: README.md
# A list of the collection's content authors. Can be just the name or in the format 'Full Name <email> (url)
# @nicks:irc/im.site#channel'
authors:
- kewl fft <kewl@alto.eu.org>
### OPTIONAL but strongly recommended
# A short summary description of the collection
description: This collection includes an Ansible module to manage packages from the AUR.
# Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only
# accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file'
license:
- GPL-3.0-or-later
# The path to the license file for the collection. This path is relative to the root of the collection. This key is
# mutually exclusive with 'license'
license_file: ''
# A list of tags you want to associate with the collection for indexing/searching. A tag name has the same character
# requirements as 'namespace' and 'name'
tags:
- aur
- arch_user_repository
- arch
- archlinux
- arch_linux
- packaging
- software
# Collections that this collection requires to be installed for it to be usable. The key of the dict is the
# collection label 'namespace.name'. The value is a version range
# L(specifiers,https://python-semanticversion.readthedocs.io/en/latest/#requirement-specification). Multiple version
# range specifiers can be set and are separated by ','
dependencies: {}
# The URL of the originating SCM repository
repository: https://github.com/kewlfft/ansible-aur
# The URL to any online docs
documentation: https://github.com/kewlfft/ansible-aur/blob/master/README.md
# The URL to the homepage of the collection/project
homepage: https://github.com/kewlfft/ansible-aur
# The URL to the collection issue tracker
issues: https://github.com/kewlfft/ansible-aur/issues
# A list of file glob-like patterns used to filter any files or directories that should not be included in the build
# artifact. A pattern is matched from the relative path of the file or directory of the collection directory. This
# uses 'fnmatch' to match the files or directories. Some directories and files like 'galaxy.yml', '*.pyc', '*.retry',
# and '.git' are always filtered
build_ignore: []

View File

@ -1,17 +0,0 @@
galaxy_info:
author: kewlfft
role_name: aur
description: Ansible module to use some Arch User Repository (AUR) helpers as well as makepkg.
license: GPL-3.0-or-later
min_ansible_version: 2.0
# https://galaxy.ansible.com/api/v1/platforms/
platforms:
- name: ArchLinux
versions:
- any
galaxy_tags:
- aur
dependencies: []

2
meta/runtime.yml Normal file
View File

@ -0,0 +1,2 @@
---
requires_ansible: '>=2.9.10'