Github Org Inviter

CLI tool written in Elixir to automate GitHub organization access management. You can manage users, teams, and parse issue-based invites using AI. The tool can be used on it's own or with Github Actions when issues are created.

Diagrams

Diagrams below provides a high-level view of how different components in the system interact to automate GitHub organization management, highlighting the flow and actions across components.

1. User opens an issue.
2. GitHub Action is triggered.
3. Issue text is passed to the CLI tool.
4. The tool sends the issue content to Gemini for parsing.
5. Gemini returns a structured JSON object.
6. The tool creates an invite with optional team assignment, or removes a user from organization.

Elixir modules:

​ Features

• Invite or remove users in a GitHub organization via username or email.
• Optionally assign invited users to one or multiple teams.
• Create, delete, and list GitHub teams.
• Parse GitHub issue text using AI (issuebot) to automatically generate invite or removal actions.

Notes

• The system requires a GitHub organization; issuebot command will first check if one is provided.
• The system determines the required action (invite or remove) from the issue text. If the request isn’t access-related, the CLI exits automatically.
• Email invites don’t appear in GitHub’s “Organizations” tab; they can only be seen via the invitee’s email.
• Inviting by email is discouraged since GitHub emails aren’t always publicly linked to usernames, which can leave fields like username or email blank in PRs (for source control).
• Users can only be removed from GitHub organizations by username.

Quick Start

• You can either download the latest release available or run the application yourself.

  # Install dependencies
  mix deps.get
  
  # Compile the project
  mix compile
  
  # Setup env vars
  GITHUB_TOKEN=""
  GEMINI_API_KEY=""
  ORG_INVITER_PR_REPO="org_inviter" # For PRs
  ORG_INVITER_PR_BRANCH="user-invites" # For PRs
  ORG_INVITER_PR_FILE="users.json"  # For PRs
  
  # Run the CLI
  mix run -- <command>

  • If you want to disable PRs, just comment Github.UserPr.main(request) at issues.ex file (both invite and remove defs). PRs are only triggered when using issuebot command.
• You can generate the docs with: mix docs.
• Commands available:

  # Invite/remove users
  invite <username|email> <org> <team1,team2>   # Invite user (optionally to teams)
  remove <username> <org>                       # Remove user
  
  # Parse issue text (AI-driven)
  issuebot "<issue text>"
  
  # Manage teams
  teams create <org> <team>                     # Create a team
  teams delete <org> <team>                     # Delete a team
  teams list <org>                              # List all teams
  teams user add <org> <team> <username>        # Add user to a team
  teams user remove <org> <team> <username>     # Remove user from a team

Current Issues

• User additions and removals from the source PR’s JSON file are inconsistent.
  • If user was invited using email and username is nil, it'll be harder to remove with PRs (needs workaround).

References

• https://docs.github.com/en/rest/orgs
• https://docs.github.com/en/rest/pulls
• https://brewingelixir.com/cli-apps-in-elixir-part-2
• https://github.com/ikabbash/self-learning-archive/blob/main/Elixir/README.md

Packages

• Jason: JSON parser.
• Finch: HTTP client built on top of Mint.
• Burrito: Packages Elixir app into an executable binary embedding the Erlang runtime.
• Ecto: Defines LLM schema for Instructor.
• Instructor: Used for chat completion to integrate with Gemini.
• ex_doc: For creating documentation.