From 42f3e53e02bcec88680576c70a0a6aed7de56725 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 16 Jul 2025 12:45:07 +0000 Subject: [PATCH 1/3] docs: update documentation for github-org-member-manage-action --- README.md | 109 +++++++++++++++++++++++++++++++++++++++++++--------- action.yaml | 24 +++++++----- 2 files changed, 106 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 4cafe3b..f472d50 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,104 @@ -# 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, building, and testing the action locally. + +### Prerequisites + +- [Docker](https.docker.com/get-started) +- [Gradle](https://gradle.org/install/) + +### Building + +To build the Docker image for the action, run the following command: + +```bash +docker build -t github-org-member-manage-action . ``` + +### Testing + +To run the 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 From deb53d38af3859c0a4d81e9043f591ab81d925ec Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 16 Jul 2025 12:59:24 +0000 Subject: [PATCH 2/3] docs: update documentation for github-org-member-manage-action --- README.md | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f472d50..91cee04 100644 --- a/README.md +++ b/README.md @@ -68,24 +68,37 @@ members: ## Development -This section guides you through setting up your development environment, building, and testing the action locally. +This section guides you through setting up your development environment and testing the action locally. ### Prerequisites -- [Docker](https.docker.com/get-started) +- [Java](httpshttps://www.java.com/en/download/) - [Gradle](https://gradle.org/install/) -### Building +### Local Testing -To build the Docker image for the action, run the following command: +1. Create a `members.yaml` file in the root of the project with the `org_name` of the organization you want to manage. -```bash -docker build -t github-org-member-manage-action . -``` + ```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 + ``` -### Testing +### Unit Tests -To run the tests, use the following command: +To run the unit tests, use the following command: ```bash ./gradlew test From bf893eee03cc9e5eabec3b832be475d0b653787b Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 16 Jul 2025 13:03:48 +0000 Subject: [PATCH 3/3] docs: update documentation for github-org-member-manage-action --- README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 91cee04..4898e6f 100644 --- a/README.md +++ b/README.md @@ -87,13 +87,20 @@ This section guides you through setting up your development environment and test 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 + 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 + INPUT_GH_TOKEN= \ + INPUT_MODE=sync \ + INPUT_DRY_RUN=true \ + INPUT_MEMBERS_FILEPATH=$PWD/members.yaml \ + ./gradlew run ``` ### Unit Tests