Git Product home page Git Product logo

ansible-matrix-collection's Introduction

Ansible Collection - eraga.matrix

Collection of modules to manage Matrix Homeserver instance. Only tested with Synapse but may (partially) work with the other Matrix Homeserver implementations.

Modules

Name Check mode Description and features

eraga.matrix.user

yes

Manage Matrix users with Ansible (via synapse admin api):

  • ✓ register user (password can’t be set though),

  • ✓ update profile,

  • ✓ deactivate.

eraga.matrix.room

yes

Manage Matrix rooms with Ansible:

  • ✓ create;

  • ✓ update;

  • ✓ delete (via synapse admin api);

  • ✓ invite room members;

  • ✓ kick room members;

  • ✓ update room avatar.

  • ❏ ability to reference room by the id instead of alias.

  • ✓ add room to list of communities

eraga.matrix.community

yes

Manage Matrix communities with Ansible:

  • ✓ create;

  • ✓ update;

  • ✓ delete;

  • ✓ kick/invite members.

  • ✓ update avatar.

eraga.matrix.send

no

Send messages to Matrix rooms with Ansible:

  • ✓ unencrypted messages:

    • ✓ markdown text;

    • ❏ images;

    • ❏ file attachments;

  • ❏ encrypted messages.

Installing this collection

You can install the eraga.matrix collection with the Ansible Galaxy CLI:

ansible-galaxy install git+https://github.com/eraga/ansible-matrix-collection.git,v1.0.0-rc2

You can also include it in a requirements.yml file and install it with ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: https://github.com/eraga/ansible-matrix-collection.git
    type: git
    version: v1.0.0-rc2

Usage

Module dependencies

All dependencies are gathered in role eraga.matrix.module_dependencies for convenience.

---
- hosts: localhost
  roles:
    - eraga.matrix.module_dependencies

Send a message to Matrix room with eraga.matrix.send

---
- name: Send a message to the room
  connection: local
  hosts: localhost
  gather_facts: false
  vars:
    matrix_uri: "https://matrix.example.net"
    matrix_token: "redacted"
    matrix_user: "ansible"
  roles:
    - eraga.matrix.module_dependencies
  tasks:
    - name: Set some fact
      set_fact:
        variables: "__variables__"

    - name: Send text to room
      eraga.matrix.send:
        matrix_uri: "{{matrix_uri}}"
        matrix_user: "{{matrix_token}}"
        matrix_token: "{{matrix_user}}"
        matrix_domain: example.net
        room: ansible_example_room_1
        text: |
          ## Test message

          It *supports* mardown and jinja {{variables}} (of course)

Manage users and rooms with eraga.matrix.user and eraga.matrix.room

---
- name: Sync users and project rooms from JetBrains Hub instance to Matrix Synapse
  connection: local
  hosts: localhost
  gather_facts: false
  vars:
    hub_uri: "https://hub.example.net/hub"
    hub_token: "redacted"

    matrix_uri: "https://matrix.example.net"
    matrix_token: "redacted"
    matrix_user: "ansible"

    all_users: []
  roles:
    - eraga.matrix.module_dependencies
  tasks:
    - name: Get Hub projects with fields and query
      eraga.jb_hub.projects:
        hub_uri: "{{hub_uri}}"
        hub_token: "{{hub_token}}"
        query: "not is: global"
        fields: "name,key,team(users(login,banned,avatar,name))"
      register: projects_result

    - name: Aggregate all unbanned users
      set_fact:
        all_users: "{{ project.team.users  | rejectattr('banned', 'true') | eraga.jb_hub.user2dict | union(all_users) }}"
      with_items: "{{projects_result.projects}}"
      loop_control:
        loop_var: project
        label: "{{ project.key }}"

    - name: Ensure user {{user.login}} exists in Matrix and has synced profile
      eraga.matrix.user:
        matrix_uri: "{{matrix_uri}}"
        matrix_user: "{{matrix_user}}"
        matrix_token: "{{matrix_token}}"
        matrix_domain: example.net
        login: "{{user.login}}"
        avatar: "{{user.avatar_url | default(omit) }}"
        displayname: "{{user.name | default(omit) }}"
      with_items: "{{all_users}}"
      loop_control:
        loop_var: user
        label: "{{ user.login }}"

    - name: Room for Hub Project exists and room members are synced
      eraga.matrix.room:
        matrix_uri: "{{matrix_uri}}"
        matrix_user: "{{matrix_user}}"
        matrix_token: "{{matrix_token}}"
        matrix_domain: example.net
        alias: "{{ project.key | lower }}_general"
        name: "{{ project.name }}"
        topic: This is room managed by ansible, yay!
        federate: no
        visibility: private
        preset: private_chat
        encrypt: yes
        room_members: "{{ project.team.users | rejectattr('banned', 'true') | map(attribute='login') | eraga.matrix.list2members(0) }}"
        power_level_override:
          events_default: 0
          state_default: 90
          ban: 90
          kick: 50
          redact: 50
          invite: 10
      with_items: "{{projects_result.projects}}"
      loop_control:
        loop_var: project
        label: "{{ project.key }}"

Manage communities with eraga.matrix.community

Create community
---
- name: Create community and room
  connection: local
  hosts: localhost
  gather_facts: false
  vars:
    hub_uri: "https://hub.example.net/hub"
    hub_token: "redacted"

    matrix_uri: "https://matrix.example.net"
    matrix_token: "redacted"
    matrix_user: "ansible"

    all_users: []
  roles:
    - eraga.matrix.module_dependencies
  tasks:
    - name: Community exists at matrix server with avatar from link
      eraga.matrix.community:
        matrix_uri: "{{uri}}"
        matrix_user: "{{user}}"
        matrix_token: "{{token}}"
        matrix_domain: example.com
        localpart: ansible_test_comm
        name: Test Community
        avatar: "http://example.com/path/to/ansible.svg"
        description: This community is managed by Ansible
        long_description: |
          # ¡Hola!
          Long description that supports markdown.
        members:
          - macarena
          - @astarta:example.com
        rooms:
          - "!BCkWAqXKUSyROyodqx:eraga.net"
        state: present
#      check_mode: yes
      register: community
    - name: Unencrypted room exists in community
      eraga.matrix.room:
        matrix_uri: "{{uri}}"
        matrix_user: "{{user}}"
        matrix_token: "{{token}}"
        matrix_domain: example.com
        alias: ansible_example_room_1
        name: Ansible Example
        topic: This room is managed by ansible
        communities:
          - ansible_test_comm
        room_members:
          margaret: 50
      register: room
Delete community
---
- name: Remove community
  connection: local
  hosts: localhost
  gather_facts: false
  vars:
    hub_uri: "https://hub.example.net/hub"
    hub_token: "redacted"

    matrix_uri: "https://matrix.example.net"
    matrix_token: "redacted"
    matrix_user: "ansible"

    all_users: []
  roles:
    - eraga.matrix.module_dependencies
  tasks:
    - name: Community does not exist at server
      eraga.matrix.community:
        matrix_uri: "{{uri}}"
        matrix_user: "{{user}}"
        matrix_token: "{{token}}"
        matrix_domain: example.com
        localpart: ansible_test_comm
        state: absent
#      check_mode: yes
      register: community

ansible-matrix-collection's People

Contributors

tntclaus avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.