{"id":17350595,"url":"https://github.com/isometry/ghait","last_synced_at":"2025-08-01T23:32:09.417Z","repository":{"id":257825822,"uuid":"872122403","full_name":"isometry/ghait","owner":"isometry","description":"Easy GitHub App Installation Tokens","archived":false,"fork":false,"pushed_at":"2024-12-02T20:06:50.000Z","size":88,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-02T21:23:04.092Z","etag":null,"topics":["cli","github","github-app-token","go-module"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/isometry.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}},"created_at":"2024-10-13T20:42:11.000Z","updated_at":"2024-12-02T20:05:32.000Z","dependencies_parsed_at":"2024-11-09T16:27:16.127Z","dependency_job_id":"ccd564a3-17f8-4c8e-8ba1-e13e6c800833","html_url":"https://github.com/isometry/ghait","commit_stats":{"total_commits":7,"total_committers":2,"mean_commits":3.5,"dds":0.2857142857142857,"last_synced_commit":"ca51432530239e7a667cb9d3a09e7b3ace83ecdc"},"previous_names":["isometry/ghat"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fghait","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fghait/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fghait/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fghait/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isometry","download_url":"https://codeload.github.com/isometry/ghait/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228415919,"owners_count":17916240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["cli","github","github-app-token","go-module"],"created_at":"2024-10-15T17:07:31.918Z","updated_at":"2025-08-01T23:32:09.165Z","avatar_url":"https://github.com/isometry.png","language":"Go","readme":"# ghait\n\n`ghait` is a reusable Go module and CLI tool designed to simplify generation of ephemeral GitHub App Installation Tokens.\nIt directly supports multiple Key Management Service (KMS) providers, including AWS, GCP, and Vault, to securely sign requests.\n\n## Features\n\n- Easily generate ephemeral GitHub App Installation Tokens\n- Support for multiple KMS providers: Stdin, File, AWS, GCP, Vault\n- Support for restricting repositories and permissions per token\n- Fully configurable via environment variables and command-line flags\n\n## Installation\n\nTo install the CLI tool, use the following command:\n\n```sh\ngo install github.com/isometry/ghait/cmd/ghait@latest\n```\n\n### Homebrew\n\n```sh\nbrew install isometry/tap/ghait\n```\n\n## Usage\n\n### CLI Interface\n\nThe `ghait` CLI tool can be used to generate ephemeral GitHub App Installation Tokens, each valid for 1-hour. Below is a brief description of the available flags:\n\n```shell\nUsage:\n  ghait [flags]\n\nFlags:\n  -a, --app-id int                  App ID (required)\n  -i, --installation-id int         Installation ID (required)\n  -k, --key string                  Private key or identifier (required)\n  -P, --provider string             KMS provider (supported: [stdin,file,aws,gcp,vault]) (default \"file\")\n  -r, --repository strings          Repository names to grant access to (default all)\n  -p, --permission stringToString   Restricted permissions to grant (default all)\n  -h, --help                        help for ghait\n  -v, --version                     version for ghait\n```\n\n### Example\n\nTo generate a GitHub App installation token using the CLI, run:\n\n```sh\nexport GHAIT_APP_ID=12345\nexport GHAIT_INSTALLATION_ID=67890\nghait -k private.pem\nghait --key private.pem --repo test-repo --permissions contents=read\nghait --provider aws --key alias/github\nghait --provider vault --key transit/sign/github --repo test-repo --permission contents=read,metadata=read\n```\n\n## Providers\n\nVarious KMS providers are implemented, each conforming to the `Signer` interface of [`bradleyfalzon/ghinstallation/v2`](https://github.com/bradleyfalzon/ghinstallation).\n\n### File\n\nThe `file` provider expects `key` to be the path to a file holding your GitHub App private key, or alternatively the full contents of the key itself.\n\nDisable inclusion with the `no_file` build tag.\n\n### AWS\n\nThe `aws` provider offloads JWT token signing to AWS KMS. `key` takes the form of a KMS key reference.\nUsage relies on standard AWS configuration and credentials being available to the app.\n\nDisable inclusion with the `no_aws` build tag.\n\n### GCP\n\nThe `gcp` provider offloads JWT token signing to GCP KMS. `key` takes the form of a KMS key reference.\nUsage relies on standard GCP configuration and credentials being available to the app.\n\nDisable inclusion with the `no_gcp` build tag.\n\n### Vault\n\nThe `vault` provider offloads JWT token signing to GCP KMS. `key` takes the form of a transit secrets engine signing path `\u003cmountpoint\u003e/sign/\u003cname\u003e`, for example `transit/sign/github`.\nUsage relies on standard Vault configuration and credentials being available to the app.\n\nDisable inclusion with the `no_vault` build tag.\n\n## Environment Variables\n\nYou can also configure the CLI using environment variables:\n\n- `GHAIT_APP_ID`: GitHub App ID\n- `GHAIT_INSTALLATION_ID`: GitHub App Installation ID\n- `GHAIT_KEY`: Private key or identifier\n- `GHAIT_PROVIDER`: KMS provider (supported: file, aws, gcp, vault)\n- `GHAIT_REPOSITORY`: Repositories to grant access to (space-delimited)\n- `GHAIT_PERMISSION`: Restricted permissions to grant (JSON map)\n\n## Programmatic Usage\n\nTo use this module programmatically, you can create a new instance of ghait and generate a token as shown below:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n\n    \"github.com/isometry/ghait\"\n    \"github.com/google/go-github/v73/github\"\n)\n\nfunc main() {\n    ctx := context.Background()\n    config := ghait.NewConfig(12345, 67890, \"aws\", \"alias/github\")\n\n    factory, err := ghait.NewGHAIT(ctx, config)\n    if err != nil {\n        log.Fatalf(\"failed to create ghait instance: %v\", err)\n    }\n\n    installationToken, err := factory.NewToken(ctx)\n    if err != nil {\n        log.Fatalf(\"failed to create installation token: %v\", err)\n    }\n\n    fmt.Println(installationToken.GetToken())\n}\n```\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the Apache License 2.0.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisometry%2Fghait","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisometry%2Fghait","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisometry%2Fghait/lists"}