{"id":50897840,"url":"https://github.com/Finatext/orgu","last_synced_at":"2026-07-22T07:01:15.522Z","repository":{"id":246016816,"uuid":"819850060","full_name":"Finatext/orgu","owner":"Finatext","description":"orgu is a tool for implementing organization-wide workflows on GitHub","archived":false,"fork":false,"pushed_at":"2026-07-14T03:09:25.000Z","size":661,"stargazers_count":24,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-14T05:08:09.329Z","etag":null,"topics":["github","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Finatext.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-06-25T10:05:12.000Z","updated_at":"2026-07-14T03:07:46.000Z","dependencies_parsed_at":"2024-06-28T12:28:17.814Z","dependency_job_id":"57def4e1-db27-428a-a696-5b691d03bed2","html_url":"https://github.com/Finatext/orgu","commit_stats":null,"previous_names":["finatext/orgu"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/Finatext/orgu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Finatext%2Forgu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Finatext%2Forgu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Finatext%2Forgu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Finatext%2Forgu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Finatext","download_url":"https://codeload.github.com/Finatext/orgu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Finatext%2Forgu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35751644,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-22T02:00:06.236Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["github","rust"],"created_at":"2026-06-16T01:31:30.082Z","updated_at":"2026-07-22T07:01:15.514Z","avatar_url":"https://github.com/Finatext.png","language":"Rust","funding_links":[],"categories":["github"],"sub_categories":[],"readme":"# orgu\n**orgu** is a tool for implementing organization-wide workflows on GitHub. It is pronounced *[ˈoɾɡu]*. [Blog post (ja)](https://techblog.finatext.com/orgu-e3a3ad0219a8).\n\n## Why Choose orgu?\n\n- Bridges the gap between GitHub's Team and Enterprise plans\n- Enhances cost efficiency\n\nGitHub and GitHub Actions are powerful tools. However, there's a significant disparity between GitHub Team and Enterprise plans. Users often seek organization-wide workflows, which are implemented as [GitHub's ruleset workflows](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging), but this feature requires an Enterprise plan. orgu addresses this by enabling users to host their own organization-wide workflows.\n\norgu offers a more cost-effective solution compared to GitHub Actions, particularly in terms of unit cost and billing period. GitHub Actions bill on a \"per minute\" basis, and since organization-wide workflows tend to run frequently, cost efficiency is crucial.\n\nOrganization-wide workflows in GitHub are CI jobs that operate across all or selected repositories within an organization, based on repository attributes. These workflows are triggered by events such as pull requests or check suite events. Although reusable workflows can be employed, they still require the distribution of workflow files to each repository individually. In contrast, organization-wide workflows eliminate the need for such distribution, allowing specific CI jobs to be executed at the organization level without the need to configure each repository separately. This enables a more streamlined and efficient management of continuous integration tasks across multiple projects.\n\n## Architecture\n![Architecture diagram](docs/images/architecture.png)\n\n![orgu-runner sequence diagram](docs/images/runner-sequence.png)\n\norgu consists of two components:\n\n- orgu-front\n- orgu-runner\n\norgu-front captures events related to Check Suites or Pull Requests via webhooks linked to a specific GitHub App. Upon receiving the webhook event, orgu-front filters the event, constructs a `CheckRequest` object, and forwards it to an event queue for further action.\n\norgu-runner operates an event loop that retrieves events from this queue, triggering specified jobs based on each event. It reports the start, success, or failure of jobs via the GitHub Checks API. Additionally, orgu-runner manages repository checkouts and generates temporary GitHub tokens, enabling jobs to interact with the GitHub API or checkout other repositories as needed. Feedback on job outcomes is provided by the jobs themselves, allowing the use of specialized tools like [reviewdog](https://github.com/reviewdog/reviewdog) for reporting job results or [Opsgenie](https://www.atlassian.com/software/opsgenie) for alerts.\n\nTo execute organization-wide jobs, a unique container image must be created for each runner. This image should contain the orgu binary, all necessary job dependencies, and the job's execution script. Launching the orgu binary in \"runner\" mode within this container starts the orgu-runner's event loop.\n\nSee `example/Dockerfile` for more details on the orgu-runner container image.\n\n### Default Platform\nBy default, orgu uses AWS Lambda functions and Amazon EventBridge Event Bus for event queuing.\n\n### Filtering Events\nIn platforms like AWS Lambda, where billing occurs per invocation, users may want to minimize orgu-runner activations. By default, orgu filters `CheckRequest` elements generated from webhook events using [event patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) in the EventBridge Event Bus. To help develop these event bus patterns, orgu includes commands like `orgu pattern generate` and `orgu pattern test`.\n\n### Custom Properties Support\nGitHub repositories feature [Custom Properties](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization), allowing for the assignment of attributes. orgu supports these Custom Properties for filtering and referencing within jobs.\n\nFor filtering, orgu incorporates custom properties into `CheckRequest.repository.custom_properties`.\n\nIn runner jobs, orgu conveys custom properties as environment variables. For instance, the custom property `team=t-platform` translates to the `CUSTOM_PROP_TEAM=t-ferris` environment variable.\n\n## Installation\nHomebrew:\n\n```\nbrew tap Finatext/orgu https://github.com/Finatext/orgu.git\nbrew install orgu\n```\n\nDownload from GitHub release:\n\nhttps://github.com/Finatext/orgu/releases\n\nCargo install:\n\n```\ncargo install --git https://github.com/Finatext/orgu.git\n```\n\nBuild locally:\n\n```\ncargo install --path .\n```\n\n## Getting started\norgu can be run locally for development or testing. First, install the orgu binary by following the instructions in the \"Installation\" section.\n\nNote: A GitHub organization is required to complete this tutorial.\n\n### Forwarding Webhooks to Your Local Machine\nTo forward GitHub webhooks to a local machine, use a service like https://smee.io/. Generate a Webhook URL on the service, then execute the forwarding command below:\n\n```\n# orgu-front uses `/github/events` path\n$ smee -u https://smee.io/\u003cID\u003e -P /github/events\n```\n\n### Creating a GitHub App\nFollow these steps to create a GitHub App:\n\n1. **Create the App**: Follow the instructions in the GitHub documentation to create a GitHub App. Ensure it is set up to use webhooks. The \"Webhook URL\" should be the URL you created earlier.\n2. **Set Permissions**: Refer to the \"GitHub App Config\" section in this documentation for the necessary permissions.\n3. **Generate a Webhook Secret**: Use the following command to generate a random string for the \"Webhook secret\":\n\n    ```sh\n    $ ruby -r securerandom -e 'puts SecureRandom.hex(32)'\n    ```\n\n4. **Install the App**: Once the GitHub App is created, install it within your organization. For testing purposes, it is recommended to limit the repositories the app can access.\n\nRefer to the following GitHub documentation for more details:\n\n- [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)\n- [Choosing Permissions for a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app)\n- [Using Webhooks with GitHub Apps](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps)\n- [Installing Your Own GitHub App](https://docs.github.com/en/apps/using-github-apps/installing-your-own-github-app)\n\n### Creating a Local Environment File\nTo configure your environment, you can use any tool that allows setting environment variables. A dotenv-like tool is recommended for this purpose. Follow these steps:\n\n1. **Install dotenv Tool**: Install a dotenv-like tool, such as `denv` or `dotenvx`:\n\n    ```sh\n    # Using denv\n    $ gem install denv\n\n    # Using dotenvx\n    $ brew install dotenvx/brew/dotenvx\n    ```\n\n2. **Download the Private Key**: Download the private key from the settings page of the GitHub App you created earlier. Note that the private key consists of multiple lines. Remove line breaks for the next steps.\n\n3. **Create a .env File**: Create a `.env` file and add the following environment variables. Replace the placeholders with actual values:\n\n    ```sh\n    $ cat \u003c\u003cEOS \u003e .env\n    GITHUB_APP_ID=\u003ccopy from GitHub App page\u003e\n    GITHUB_INSTALLATION_ID=\u003ccopy from GitHub App installation page\u003e\n    GITHUB_WEBHOOK_SECRET=\u003cwebhook secret value\u003e\n    GITHUB_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----your single line private key here-----END RSA PRIVATE KEY-----\n    EOS\n    ```\n\n4. **Check Environment Variables**: Verify the environment variables using the following command:\n\n    ```sh\n    $ denv -- env\n    ```\n\nFor more information on managing private keys for GitHub Apps, refer to the GitHub documentation:\n\n- [Managing Private Keys for GitHub Apps](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps)\n\n\n### Run orgu-front\nExecute `orgu front server` command with configured environment variables:\n\n```\n$ denv -- orgu front server\n```\n\n### Run orgu-runner\nExecute `orgu runner server` command with configured environment variables:\n\n```\n$ denv -- orgu runner server --job-name=test -- ls\n```\n\n### Test orgu with PR\nCreate a test pull request in the configured repository. GitHub will send a webhook event to a forwarding service such as Smee, which then forwards the request to your local orgu-front server. In local development mode, the orgu-front server sends the `CheckRequest` payload directly to the local orgu-runner using an HTTP POST request. The orgu-runner executes the `ls` command in the checked-out repository, and the output of the `ls` command can be viewed in the orgu-runner's log entries.\n\nAlso the \"Checks\" tab in the pull request will have job execution logs.\n\nIf something went wrong:\n\n- Check webhook forwarding service server and client logs\n- Check webhook status in the \"Recent Deliveries\" page of GitHub App\n  - `https://github.com/organizations/\u003corg\u003e/settings/apps/\u003capp name\u003e/advanced`\n- Check the GitHUb App has necessary permissions\n  - See the \"GitHub App Config\" section of this document\n\n### Further steps\nReplace `ls` with a linter command and use reviewdog to provide feedback on the results.\n\n## GitHub App Config\nWhile it's possible to share a single GitHub App between orgu-front and orgu-runner, it's recommended to use separate GitHub Apps for orgu-front and each orgu-runner job.\n\n### orgu-front\nRepository permissions:\n\n- R/W: Checks\n- R: Contents, Custom properties, Metadata, Pull requests\n\nWebhook event subscription:\n\n- Pull request\n\nNote: Necessary `check_suite` and `check_run` events are automatically sent to the Webhook endpoint without subscription.\n\n### orgu-runner\nThis is baseline and should be modify based on atual use cases.\n\nRepository permissions:\n\n- R/W: Checks\n- R: Contents, Custom properties, Metadata, Pull requests\n\nWebhook event subscription:\n\nNone, but set the same URL as orgu-front to enable the re-run checks feature.\nWhen a user clicks the \"re-run\" button in the Checks UI, GitHub sends `check_suite.rerequested` or `check_run.rerequested` events to the URL.\n\nFor more details, see [docs/re-run.md](docs/re-run.md).\n\n## Running orgu without AWS Lambda\n### orgu-front server\nWithout AWS Lambda, orgu-front runs as a standalone HTTP server. It uses `POST /github/events` for incoming GitHub Webhook events. Deploy the orgu-front server in an environment such as Kubernetes and route GitHub Webhook events to this endpoint.\n\n### Event queue relay\nWhen running in an AWS Lambda environment, orgu-front uses Amazon EventBridge Event Bus as its event queue service. This setup can be made flexible by building a relay server that sends events to a queue-like service, which then fans out the events. Additionally, a custom queue receiver is required to trigger orgu-runner.\n\n```\n\"orgu-front server\" --HTTP POST--\u003e\n  \"custom local HTTP relay server\" --\u003e \"custom queue\" --\u003e\n  \"custom queue receiver\" --HTTP POST--\u003e \"orgu-runner server\"\n```\n\nFor example, you can build a local relay service that sends events to Amazon Simple Notification Service (SNS), which then fans out the events to Amazon Simple Queue Service (SQS). A custom SQS receiver retrieves messages from SQS and sends them to the orgu-runner server.\n\norgu-front server sends to local orgu-runner server by default. This lacks \"event fan-out\" parts but one can get insight from that.\n\nTo make orgu-front uses custom event queue relay server, use `--event-queue-relay-endpoint` option. For more detail, see `orgu front server --help`.\n\nSee `CheckRequest` struct for event structure between orgu-front server and orgu-runner server.\n\n### orgu-runner server\nWithout Amazon EventBridge Event Bus and AWS Lambda, orgu-runner operates as an HTTP server and processes received events. In server mode, orgu-runner uses `POST /run` to receive events.\n\n## Operation\n### Configuration\nSee `--help`. All operational configurations should be configurable via environment variables.\n\n### Computing resources\nEssentially, orgu-front requires fewer computing resources. In contrast, the resource consumption of orgu-runner significantly increases depending on its associated CI job. If the job involves CPU-intensive tasks, the container or pod must be allocated substantial computing resources.\n\n### Job failures\norgu's approach to handling job failures is outlined as follows:\n\n- **Job Execution Failure**: If a job is executed but fails, this does not cause orgu-runner to fail, as the responsibility lies with the user. orgu communicates the failure via the GitHub Checks API, notifying developers of the issue.\n- **Job Execution Error**: Failure to execute a job results in an orgu-runner failure, typically due to misconfiguration. Most computing platforms can issue alerts for such failures. orgu also attempts to report these failures via the GitHub Checks API.\n- **Job Timeout**: A job that executes successfully but exceeds its time limit does not cause orgu-runner to fail. This situation is reported through the GitHub Checks API.\n- **Repository Checkout Timeout**: If the checkout of the target repository times out before job execution, it does not result in an orgu-runner failure. This event is also reported via the GitHub Checks API.\n\n### Log level\nServer: Use `RUST_LOG` environment to change default log level.\n\nTo see trace logs from orgu:\n\n```\nRUST_LOG=info,orgu=trace\n```\n\nTo see debug logs from all targets:\n\n```\nRUST_LOG=debug\n```\n\nCLI uses: Use `-v` or `-vv` flag.\n\n### Backtrace\nUse `RUST_BACKTRACE=1` to see backtrace.\n\n## Development\n### Release\n1. Update version of `Cargo.toml` and re-generate lock file\n1. Git commit-push then create a PR and merge\n1. Create a git tag with `git tag \"$(cargo metadata --no-deps --format-version 1 | jq -r '\"v\" + .packages[0].version')\"`\n1. Push the git tag and wait the CI creates a GitHub Release and upload artifacts\n1. Run `GITHUB_REF=\"refs/tags/$(cargo metadata --no-deps --format-version 1 | jq -r '\"v\" + .packages[0].version')\" TARGET=orgu .github/scripts/update_formula` to update Homebrew formula file\n1. Create a PR and merge\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFinatext%2Forgu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFinatext%2Forgu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFinatext%2Forgu/lists"}