Manage GitHub Organization Access via Infrastructure as Code

[sebastian-sommerfeld-io]

As the owner of the sommerfeld.io GitHub organization and maintainer of its repositories, I want to manage user access to the organization and all its repositories as infrastructure-as-code, so that access control is consistent, auditable, and automated.

• I want to use Ansible to automate the process of granting, revoking, and adjusting access levels (e.g., read, write, admin) for users. The Ansible playbook should:
  • Add users to the organization.
  • Assign specific access levels to users for different repositories.
  • Revoke user access when necessary.
  • Ensure that access is always in line with the defined state, preventing manual changes from drifting away from the codified setup.

Acceptance Criteria

• [ ] main branch is protected - changes are only possible through a PR
• [ ] Repository access and organization access is managed through Ansible
  • Add a playbook to this repo where all access-related settings, and users who should be able to access, are configured
  • Add a demo user to test granting and revoking access
  • For branches: run ansible lint
  • For main: run ansible playbook and update settings

Optional

• [ ] Add MkDocs to this repository - ❔ Do I really want to do this? If so, create a dedicated issue and reference here

Alternative

• If Ansible does not work, check the GitHub CLI. Managing access through the CLI might also be an option

[sebastian-sommerfeld-io]

⚠️ ⚠️ ⚠️ This information comes from ChatGPT - I am not sure if this is really correct ⚠️ ⚠️ ⚠️

---

To implement access management for your GitHub organization using Ansible, you can leverage the community.general.github_user and community.general.github_team modules, which integrate with the GitHub API to manage users and teams. Here's a step-by-step guide to create a solution for managing user access:

1. Set up GitHub Personal Access Token

You need a GitHub personal access token (PAT) with the necessary scopes to manage the organization and repository access:

• admin:org
• repo

2. Install Required Collections

Ensure that you have the community.general collection installed, which contains the GitHub modules:

ansible-galaxy collection install community.general

3. Define Your Playbook

Your playbook should handle:

• Adding users to the organization.
• Managing repository access levels.
• Revoking access.

Here’s an example Ansible playbook for managing access:

Example: github_access.yml

---
- name: Manage GitHub organization access
  hosts: localhost
  gather_facts: false
  vars:
    github_token: "{{ lookup('env', 'GITHUB_TOKEN') }}"  # Secure your token using environment variables
    github_organization: "sommerfeld-io"
    users:
      - { login: "user1", access_level: "admin", repos: ["repo1", "repo2"] }
      - { login: "user2", access_level: "write", repos: ["repo1"] }
      - { login: "user3", access_level: "read", repos: ["repo2"] }

  tasks:
    - name: Ensure users are part of the organization
      community.general.github_membership:
        organization: "{{ github_organization }}"
        login: "{{ item.login }}"
        role: "{{ item.access_level }}"
        state: present
        token: "{{ github_token }}"
      loop: "{{ users }}"

    - name: Manage repository access for users
      community.general.github_collaborator:
        organization: "{{ github_organization }}"
        repository: "{{ repo }}"
        username: "{{ item.login }}"
        permission: "{{ item.access_level }}"
        state: present
        token: "{{ github_token }}"
      loop: "{{ users }}"
      loop_control:
        loop_var: item
      vars:
        repo: "{{ item.repos }}"

    - name: Revoke access from users
      community.general.github_membership:
        organization: "{{ github_organization }}"
        login: "{{ item.login }}"
        state: absent
        token: "{{ github_token }}"
      loop:
        - { login: "user_to_remove" }  # Add users to remove here

4. Environment Variables

Store your GitHub token securely by setting it as an environment variable. This avoids storing sensitive information directly in your playbook:

export GITHUB_TOKEN=your_github_personal_access_token

5. Playbook Breakdown

• Adding users to the organization: The community.general.github_membership module adds or updates users' roles (admin/member).
• Granting repository access: The community.general.github_collaborator module sets specific access levels (read/write/admin) to the repositories.
• Revoking access: The same community.general.github_membership module can remove users from the organization.

6. Running the Playbook

To apply your access controls:

ansible-playbook github_access.yml

7. Automating Audits

Ansible keeps logs of actions taken, so you can review them to verify that user access is being managed according to the defined playbook. Additionally, GitHub’s own audit logs can help you trace any access changes.

By running this playbook regularly (perhaps via a CI pipeline), you can ensure that access levels remain consistent and aligned with the desired state defined in your Ansible code.