{"id":20567792,"url":"https://github.com/isometry/github-token-manager","last_synced_at":"2025-08-06T10:15:00.655Z","repository":{"id":228355111,"uuid":"773528438","full_name":"isometry/github-token-manager","owner":"isometry","description":"Kubernetes operator to manage fine-grained, ephemeral Access Tokens generated from GitHub App credentials","archived":false,"fork":false,"pushed_at":"2025-04-12T06:19:05.000Z","size":363,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T07:25:18.323Z","etag":null,"topics":["access-tokens","github","github-app","gitops","kubernetes","operator"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","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-03-17T22:28:08.000Z","updated_at":"2025-04-12T06:19:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"a22f7359-2d7f-4665-bd43-46c3b3fcc226","html_url":"https://github.com/isometry/github-token-manager","commit_stats":null,"previous_names":["isometry/ghtoken-manager","isometry/github-token-manager"],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fgithub-token-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fgithub-token-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fgithub-token-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fgithub-token-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isometry","download_url":"https://codeload.github.com/isometry/github-token-manager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248533165,"owners_count":21120051,"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":["access-tokens","github","github-app","gitops","kubernetes","operator"],"created_at":"2024-11-16T04:48:32.497Z","updated_at":"2025-08-06T10:15:00.637Z","avatar_url":"https://github.com/isometry.png","language":"Go","readme":"[![CodeQL](https://github.com/isometry/github-token-manager/actions/workflows/codeql.yaml/badge.svg)](https://github.com/isometry/github-token-manager/actions/workflows/codeql.yaml)\n[![E2E](https://github.com/isometry/github-token-manager/actions/workflows/e2e.yaml/badge.svg)](https://github.com/isometry/github-token-manager/actions/workflows/e2e.yaml)\n[![Publish](https://github.com/isometry/github-token-manager/actions/workflows/publish.yaml/badge.svg)](https://github.com/isometry/github-token-manager/actions/workflows/publish.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/isometry/github-token-manager)](https://goreportcard.com/report/github.com/isometry/github-token-manager)\n\n# github-token-manager\n\nKubernetes operator to manage fine-grained, ephemeral Access Tokens generated from GitHub App credentials.\n\n## Description\n\nA number of Kubernetes operators, including [FluxCD](https://fluxcd.io/) and [upbound/provider-terraform](https://github.com/upbound/provider-terraform), often need to authenticate with the GitHub API, particularly when private repositories are used. This may be to clone a private repository, pull from a private GHCR repository, or to send a commit or deployment status. Common practice is to use Personal Access Tokens (PATs), but their use is far from optimal: PATs tending to be long-lived, poorly scoped, and tied to an individual, as GitHub has no official support for service accounts.\n\nThis operator functions similarly to cert-manager, but instead of managing certificates, it manages GitHub App Installation Access Tokens. It takes custom-scoped `Token` (namespaced) and `ClusterToken` requests and transforms them into `Secrets`. These `Secrets` contain regularly refreshed GitHub App Installation Access Token credentials. These credentials are ready for use with GitHub clients that rely on HTTP Basic Auth, providing a more secure and automated solution for token management.\n\n## Getting Started\n\n### Prerequisites\n\n* A Kubernetes cluster (v1.21+)\n* A [GitHub App](https://docs.github.com/en/apps/creating-github-apps) with permissions and repository assignments sufficient to meet the needs of all anticipated GitHub API interactions. Typically: `metadata: read`, `contents: read`, `statuses: write`.\n  * Specifically: App ID, App Installation ID and a Private Key are required.\n\n### Installation\n\nA Helm Chart is provided your for convenience: [deploy/charts/github-token-manager/](deploy/charts/github-token-manager/)\n\nAlternatively, a baseline Kustomization is provided under [config/default/](config/default/)\n\n### Configuration\n\nThe operator itself requires configuration via `ConfigMap/gtm-config` in its deployment namespace. This contains the GitHub App ID, Installation ID and Private Key provider details. In addition to embedding the private key file within the secret, AWS Key Management Service (KMS), Google Cloud Key Management, and HashiCorp Vault's Transit Secrets Engine are also supported for secure external handling of keying material.\n\n#### Example `gtm-config` with embedded Private Key\n\n```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: gtm-config\n  namespace: github-token-manager\nstringData:\n  gtm.yaml: |\n    app_id: 1234\n    installation_id: 4567890\n    provider: file\n    key: /config/private.key\n  private.key: |\n    -----BEGIN RSA PRIVATE KEY-----\n    ...elided...\n    -----END RSA PRIVATE KEY-----\n```\n\n#### Example `gtm-config` with AWS KMS\n\n```yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: gtm-config\n  namespace: github-token-manager\nstringData:\n  gtm.yaml: |\n    app_id: 1234\n    installation_id: 45678890\n    provider: aws\n    key: alias/github-token-manager\n```\n\n### `Token` and `ClusterToken`\n\nOnce the operator is installed and configured, any number of namespaced `Token` and non-namespaced `ClusterToken` may be created, resulting in matching `Secret` resoures being created, containing either `token` or `username` and `password` fields, depending on configuration.\n\nThe namespaced `Token` resource manages a `Secret` in the same namespace containing a fine-grained [installation access token](https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app) for the configured GitHub App, appropriate for delegated management by the namespace owner.\n\nThe non-namespaced `ClusterToken` resource does the same thing, but supports abstracted management where only the managed `Secret` is bound to the configured target namespace via `.spec.secret.namespace`.\n\n```yaml\napiVersion: github.as-code.io/v1\nkind: ClusterToken # or Token\nmetadata:\n  name: foo\nspec:\n  installationID: 321  # (optional) override GitHub App Installation ID configured for the operator\n  permissions: {}      # (optional) map of token permissions, default: all permissions assigned to the GitHub App\n  refreshInterval: 45m # (optional) token refresh interval, default 30m\n  retryInterval: 1m    # (optional) token retry interval on ephemeral failure; default: 5m\n  repositories: []     # (optional) name-based override of repositories accessible with managed token\n  repositoryIDs: []    # (optional) ID-based override of reposotiories accessible with managed token\n  secret:              # (optional) override default `Secret` configuration\n    annotations: {}    # (optional) map of annotations for managed `Secret`\n    basicAuth: true    # (optional) create `Secret` with `username` and `password` rather than `token`\n    labels: {}         # (optional) map of labels for managed `Secret`\n    name: bar          # (optional) override name for managed `Secret` (default: .metadata.name)\n    namespace: default # (required, ClusterToken-only) set the target namespace for managed `Secret`\n```\n\n#### Examples\n\nManage a `Secret/github-token` containing HTTP Basic Auth `username` and `password` fields appropriate for use with a Flux' `GitRepository` [Secret Reference](https://fluxcd.io/flux/components/source/gitrepositories/#secret-reference):\n\n```yaml\napiVersion: github.as-code.io/v1\nkind: Token\nmetadata:\n  name: github-token\n  namespace: flux-system\nspec:\n  permissions:\n    metadata: read\n    contents: read\n  refreshInterval: 45m\n  secret:\n    basicAuth: true\n```\n\nManage a `Secret/github-status` containing a plain `token` field appropriate for use with a Flux' `Provider` [GitHub Commit Status Updates](https://fluxcd.io/flux/components/notification/providers/#github):\n\n```yaml\napiVersion: github.as-code.io/v1\nkind: Token\nmetadata:\n  name: github-status\n  namespace: flux-system\nspec:\n  permissions:\n    metadata: read\n    statuses: write\n  refreshInterval: 45m\n```\n\nManage `Secret/github` in the `default` namespace containing a plain `token` field, inheriting all permissions assigned to the configured GitHub App:\n\n```yaml\napiVersion: github.as-code.io/v1\nkind: ClusterToken\nmetadata:\n  name: default-github\nspec:\n  secret:\n    name: github\n    namespace: default\n```\n\n## Contributing\n\nAll contributions from the community are welcome.\n\n**NOTE:** Run `make help` for more information on all potential `make` targets\n\nMore information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)\n\n### To Deploy on the cluster\n\n\n#### Build and push your image to the location specified by `IMG`:\n\n```sh\nmake ko-build IMG=\u003csome-registry\u003e/github-token-manager:tag\n```\n\n**NOTE:** This image ought to be published in the personal registry you specified.\nAnd it is required to have access to pull the image from the working environment.\nMake sure you have the proper permission to the registry if the above commands don’t work.\n\n#### Install the CRDs into the cluster:\n\n```sh\nmake install\n```\n\n#### Deploy the Manager to the cluster with the image specified by `IMG`:\n\n```sh\nmake deploy IMG=\u003csome-registry\u003e/github-token-manager:tag\n```\n\n\u003e **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin\nprivileges or be logged in as admin.\n\n### To Uninstall\n\n#### Delete the instances (CRs) from the cluster\n\n```sh\nkubectl delete -k config/samples/\n```\n\n#### Delete the APIs(CRDs) from the cluster\n\n```sh\nmake uninstall\n```\n\n#### UnDeploy the controller from the cluster\n\n```sh\nmake undeploy\n```\n\n## License\n\nCopyright 2024 Robin Breathe.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisometry%2Fgithub-token-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisometry%2Fgithub-token-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisometry%2Fgithub-token-manager/lists"}