Self-Service Membership for GitHub Organizations

Managing membership requests for a GitHub organization can be a time-consuming task, especially for larger organizations. In this article, we will walk through a solution that leverages GitHub Actions to automate the process of adding new members to a GitHub organization. By using an issue template and a GitHub Actions workflow, we can streamline the membership request process and reduce manual work.

Spoiler

If you just want to know what it looks like, you can also take a look at our GitHub Lowlands community page and sign-up.
link: https://github.com/gi-low

Introduction

GitHub Actions is a powerful tool for automating various tasks within your repository, including CI/CD pipelines, issue management, and more. One of the less common but highly useful applications of GitHub Actions is automating the management of organization memberships. This can be particularly beneficial for organizations with a large number of members or frequent membership changes.

Why Automate Membership Requests?

Automating membership requests can save a significant amount of time for organization administrators. Instead of manually handling each membership request, the automation can process them as soon as they are submitted.

Automation ensures that every request is handled in a consistent manner. This reduces the risk of errors and ensures that all new members are added following the same criteria and process.

By using GitHub Actions and secrets, you can securely manage and automate processes without exposing sensitive information. This method ensures that only authorized requests are processed, maintaining the security of your organization.

As your organization grows, managing membership requests manually can become increasingly difficult. Automation allows you to scale your processes without a corresponding increase in administrative overhead.

Step 1: Create an Issue Template

First, we need to create an issue template that users can fill out to request membership. This template will include a specific title and format to ensure our GitHub Actions workflow can process it correctly.

1. Navigate to your repository on GitHub.
2. Click on Settings
3. Scroll down to the Issues section and click on Set up templates

4. Create a new template with the following content:

---
name: GitHub Membership Request
about: Request to join the organization
title: 'Request Membership'
labels: membership
assignees: ''
---

### GitHub Username
<!-- Please provide your GitHub username -->
@username

### Agreement
- [ ] I have read the organization's code of conduct
- [ ] I agree to follow the contribution guidelines
- [ ] I understand that membership comes with responsibilities

### Contact
<!-- How can we reach you (optional) -->
- Email: (optional)
- Discord: (optional)
- Bluesky: (optional)

Step 2: Generate a Personal Access Token (PAT)

To add users to the organization, we need a Personal Access Token (PAT) with the admin:org scope. Follow these steps to generate the token:

1. Go to GitHub Settings
2. Click on Generate new token (classic)
3. Provide a descriptive name for your token
4. Select the admin:org and repo scope (repo is required later)

1. Click Generate token
2. Copy the token and save it securely
   We will need it in the next step!

Step 3: Add the PAT as a Secret in Your Repository

Next, we need to add the PAT as a secret in our repository

1. Go to your repository on GitHub.
2. Click on Settings
3. Navigate to Secrets and variables and select Actions
4. Click on New repository secret
5. Name the secret ORG_ADMIN_TOKEN
6. Paste the PAT into the Value field
7. Click Add secret

Step 4: Create a GitHub Actions Workflow

Now, we will create a GitHub Actions workflow that automates the process of adding new members to the organization when an issue is created with the title Request Membership

Create a new file in your repository at .github/workflows/ with the name add-user-to-org.yml

Add the following content to the file:

name: Add User to Organization

on:
  issues:
    types: [opened]

jobs:
  add-user:
    runs-on: ubuntu-latest
    if: github.event.issue.title == 'Request Membership' # Ensure it matches the issue template title
    steps:
      - name: Check out the repository
        uses: actions/checkout@v2

      - name: Invite User to Organization
        env:
          ORG_ADMIN_TOKEN: ${{ secrets.ORG_ADMIN_TOKEN }}
        run: |
          ISSUE_BODY=$(jq -r '.issue.body' < $GITHUB_EVENT_PATH)
          USERNAME=$(echo "$ISSUE_BODY" | sed -n 's/^@\(.*\)/\1/p')
          
          if [[ -n "$USERNAME" && "$USERNAME" =~ ^[a-zA-Z0-9_-]+$ ]]; then
            echo "Sending invitation to $USERNAME..."
            
            curl -v -X PUT \
              -H "Authorization: token $ORG_ADMIN_TOKEN" \
              -H "Accept: application/vnd.github.v3+json" \
              https://api.github.com/orgs/GI-Low/memberships/$USERNAME
              
            ISSUE_NUMBER=$(jq -r '.issue.number' < $GITHUB_EVENT_PATH)
            
            curl -v -X PATCH \
              -H "Authorization: token $ORG_ADMIN_TOKEN" \
              -H "Accept: application/vnd.github.v3+json" \
              -d '{"state":"closed"}' \
              https://api.github.com/repos/GI-Low/Membership/issues/$ISSUE_NUMBER
          else
            echo "Invalid or no username found in the issue body."
            exit 1
          fi

Step 5: Verify the Workflow

After setting up the workflow, you can verify it by opening a new issue with the title Request Membership and following the template format. The workflow should automatically process the request and add the user to the organization.

Use Cases

Open Source Projects:

For open-source projects, automating membership requests can help in quickly adding contributors to the organization, thereby fostering collaboration.

Education and Training:

Educational institutions or training programs can use this automation to manage student access to repositories, ensuring a smooth onboarding process.

Enterprise Organizations:

Large enterprises with multiple teams and projects can benefit from this automation by reducing the administrative burden of managing access requests.

Conclusion

By following these steps, you can automate the process of handling membership requests for your GitHub organization. This solution leverages the power of GitHub Actions to streamline the workflow and reduce manual effort, making it easier to manage large organizations. Automating these processes not only saves time but also ensures consistency, security, and scalability.