diff --git a/README.md b/README.md index 4cafe3b..4898e6f 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,124 @@ -# github-org-member-manage-action +# GitHub Org Member Manage Action -## Objective +This GitHub Action allows you to manage your GitHub organization's memberships in a declarative way using a YAML file. This file becomes the single source of truth for your organization's members, making it easy to manage and version control your member list. -Mange GitHub org memberships in a declarative way (.yaml). -YAML will be the single source of truth for the org memberships. +## Features + +- **Declarative Membership Management:** Define your organization's members and their roles (admin or member) in a simple YAML file. +- **Synchronization:** The action automatically synchronizes the members of your organization to match the state defined in your YAML file. +- **Dry Run Mode:** Preview the changes that would be made without actually applying them. +- **Bootstrap Your Configuration:** `write` mode helps you to create a `members.yaml` from the current state of your GitHub org members. + +## Usage + +To use this action in your workflow, you need to add a step that uses `codingpot/github-org-member-manage-action`. + +### Example Workflow + +Here is an example workflow that runs on a schedule and synchronizes the organization's members: + +```yaml +name: Manage Org Members + +on: + schedule: + - cron: '0 0 * * *' # Run daily at midnight + workflow_dispatch: + +jobs: + manage-members: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Manage GitHub Org Members + uses: "codingpot/github-org-member-manage-action@v1" + with: + gh_token: ${{ secrets.GH_TOKEN }} + members_filepath: 'members.yaml' + mode: 'sync' +``` + +### `members.yaml` format + +The `members.yaml` file defines the members of your organization. Here is an example: ```yaml # members.yaml -org_name: codingpot +org_name: your-org-name admins: - - kkweon - - kkweon2 + - admin-user-1 + - admin-user-2 members: - - deepdiver1 - - deepdiver2 + - member-user-1 + - member-user-2 ``` -## How to use +## Action Inputs -```yaml -steps: - - uses: "codingpot/github-org-member-manage-action@v1" - with: - gh_token: ${{ secrets.GH_TOKEN }} # (required) Needs admin:org permission - members_filepath: members.yaml # (optional) - dry_run: false # (optional) - mode: sync # (optional) write or sync +| Input | Description | Default | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | +| `gh_token` | A GitHub token with `admin:org` scope. This is required to manage organization memberships. It is recommended to use a secret to store the token. | **Required** | +| `members_filepath` | The file path to the YAML file containing the list of members. This file will be the single source of truth for the organization's memberships. | `members.yaml` | +| `dry_run` | If set to `true`, the action will only print the changes that would be made, without actually applying them. This is useful for testing and debugging. | `false` | +| `mode` | The mode of operation for the action. There are two modes available: `sync` and `write`. | `sync` | + +## Development + +This section guides you through setting up your development environment and testing the action locally. + +### Prerequisites + +- [Java](httpshttps://www.java.com/en/download/) +- [Gradle](https://gradle.org/install/) + +### Local Testing + +1. Create a `members.yaml` file in the root of the project with the `org_name` of the organization you want to manage. + + ```yaml + # members.yaml + org_name: your-org-name + ``` + +2. Run the action in `write` mode to fetch the current members of the organization and populate the `members.yaml` file. You will need to provide a GitHub token with `admin:org` scope as an environment variable. + + ```shell + INPUT_GH_TOKEN= \ + INPUT_MODE=write \ + INPUT_MEMBERS_FILEPATH=$PWD/members.yaml \ + ./gradlew run + ``` + +3. After the `members.yaml` file is populated, you can run the action in `sync` mode to test the synchronization logic. It's recommended to run with `INPUT_DRY_RUN=true` first to preview the changes. + + ```shell + INPUT_GH_TOKEN= \ + INPUT_MODE=sync \ + INPUT_DRY_RUN=true \ + INPUT_MEMBERS_FILEPATH=$PWD/members.yaml \ + ./gradlew run + ``` + +### Unit Tests + +To run the unit tests, use the following command: + +```bash +./gradlew test ``` + +## Contributing + +Contributions are welcome! Please follow these guidelines when contributing: + +- **Code Quality:** Write clean, maintainable, and well-documented code. +- **Conventional Commits:** Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for all commit messages. +- **Pull Requests:** Create a pull request with a clear description of your changes. + +--- + +*This README was updated by an AI assistant.* diff --git a/action.yaml b/action.yaml index 88e3b2e..3e5721c 100644 --- a/action.yaml +++ b/action.yaml @@ -4,25 +4,31 @@ branding: icon: 'at-sign' color: 'green' -# Inputs are provided as ENVIRONMENT VARIABLES WITH INPUT_ prefix (e.g., INPUT_MEMBERS_FILEPATH). # See https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs. inputs: gh_token: - description: GitHub Token with admin:org access + description: > + A GitHub token with `admin:org` scope. + This is required to manage organization memberships. + It is recommended to use a secret to store the token. required: true - default: "" members_filepath: - description: Filepath to members.yaml. - required: true + description: > + The file path to the YAML file containing the list of members. + This file will be the single source of truth for the organization's memberships. + required: false default: members.yaml dry_run: - description: Does not update any memberships but just fetch only + description: > + If set to `true`, the action will only print the changes that would be made, + without actually applying them. This is useful for testing and debugging. required: false + default: "false" mode: description: > - There are 2 modes (sync|write). - "sync" mode will try to update memberships. - "write" mode will just fetch data and write YAML in `members_filepath`. + The mode of operation for the action. There are two modes available: `sync` and `write`. + - `sync`: This mode synchronizes the organization's memberships with the state defined in the `members_filepath` file. It will add, remove, and update members as needed to match the YAML file. + - `write`: This mode fetches the current organization memberships and writes them to the `members_filepath` file. This is useful for initializing the a new `members.yaml` file. required: false default: sync