{"id":23130450,"url":"https://github.com/andreaso/hv4gha","last_synced_at":"2025-08-17T06:33:13.876Z","repository":{"id":184785734,"uuid":"672481514","full_name":"andreaso/hv4gha","owner":"andreaso","description":"Python library for using HashiCorp Vault alt. OpenBao to manage a GitHub App's private key.","archived":false,"fork":false,"pushed_at":"2025-04-25T18:12:08.000Z","size":201,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-15T01:58:07.519Z","etag":null,"topics":["github","openbao","python","vault"],"latest_commit_sha":null,"homepage":"","language":"Python","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/andreaso.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}},"created_at":"2023-07-30T08:28:26.000Z","updated_at":"2025-05-11T09:39:41.000Z","dependencies_parsed_at":"2023-07-30T08:51:31.115Z","dependency_job_id":"ff2029fd-df30-4cf4-ac70-9aabd9476eb1","html_url":"https://github.com/andreaso/hv4gha","commit_stats":null,"previous_names":["andreaso/hv4gha"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/andreaso/hv4gha","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaso%2Fhv4gha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaso%2Fhv4gha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaso%2Fhv4gha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaso%2Fhv4gha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/andreaso","download_url":"https://codeload.github.com/andreaso/hv4gha/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/andreaso%2Fhv4gha/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270721844,"owners_count":24634052,"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","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"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","openbao","python","vault"],"created_at":"2024-12-17T10:14:25.289Z","updated_at":"2025-08-17T06:33:13.861Z","avatar_url":"https://github.com/andreaso.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HashiCorp Vault for GitHub Apps\n\nPython library for using [HashiCorp Vault][1]'s [Transit Engine][2] to\nmanage a GitHub App's private RSA key. More precisely, the library\nprovides the following pieces of functionality.\n\n* Perform initial one-way import of the App's private key into Vault\n* Issue (short-lived) GitHub Access Token\n  * Have Vault sign a JWT using the App's private key\n  * Exchange that JWT for a GitHub Access Token\n\nConceptually Vault here fills the role of an HSM or a Cloud KMS.\n\nSee [Authenticating as a GitHub App installation (GitHub Docs)][3] for context.\n\nThe library is also tested against [OpenBao][6].\n\n## Installation\n\n```shell\npip install hv4gha\n```\n\n## Usage\n\nIn addition to the examples below see also the\n[hv4gha/entry.py](https://github.com/andreaso/hv4gha/blob/main/hv4gha/entry.py) docstrings.\n\n### Import App key\n\n```python\nfrom hv4gha import import_app_key\n\nwith open(\"/path/to/github-app.private-key.pem\", \"r\") as akh:\n    my_app_key = akh.read()\n\nresponse = import_app_key(\n    pem_key=my_app_key,\n    key_name=\"my-github-app\",\n    vault_addr=\"https://vault.example.com:8200\",\n    vault_token=\"...\",\n)\n\nkey_version = response[\"key_version\"]\n```\n\n### Issue Access Token\n\n```python\nfrom hv4gha import issue_access_token\n\nresponse = issue_access_token(\n    key_name=\"my-github-app\",\n    vault_addr=\"https://vault.example.com:8200\",\n    vault_token=\"...\",\n    app_client_id=\"Iv1.bc01362e9d72c72a\",\n    account=\"andreaso\",\n)\n\naccess_token = response[\"access_token\"]\ntoken_expiry = response[\"expires_at\"]\n```\n\n### Issue scoped Access Token\n\n```python\nfrom hv4gha import issue_access_token\n\nresponse = issue_access_token(\n    key_name=\"my-github-app\",\n    vault_addr=\"https://vault.example.com:8200\",\n    vault_token=\"...\",\n    app_client_id=\"Iv1.bc01362e9d72c72a\",\n    account=\"andreaso\",\n    permissions={\"contents\": \"read\"},\n    repositories=[\"world-domination\"],\n)\n\naccess_token = response[\"access_token\"]\ntoken_expiry = response[\"expires_at\"]\n```\n\n## Vault requirements\n\nSomewhat simplified, this is what's required Vault wise.\n\n### Transit secrets engine\n\nFirst of all, the [Transit Engine][2] needs to be enabled.\n\n```shell\nvault secrets enable transit\n```\n\nHere we are sticking to the default `transit/` mount point.\n\n### Import policy\n\n```HCL\npath \"transit/wrapping_key\" {\n  capabilities = [\"read\"]\n}\n\npath \"transit/keys/my-github-app\" {\n  capabilities = [\"read\"]\n}\n\npath \"transit/keys/my-github-app/import\" {\n  capabilities = [\"update\"]\n}\n\npath \"transit/keys/my-github-app/import_version\" {\n  capabilities = [\"update\"]\n}\n```\n\n### Issue policy\n\n```HCL\npath \"transit/sign/my-github-app\" {\n  capabilities = [\"update\"]\n}\n```\n\n### Vault Token\n\nFor obtaining the initial Vault Token, see the [hvac][4] Python\nlibrary and its [Auth Methods][5] documentation.\n\n\n[1]: https://www.vaultproject.io/\n[2]: https://developer.hashicorp.com/vault/docs/secrets/transit\n[3]: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation\n[4]: https://github.com/hvac/hvac\n[5]: https://hvac.readthedocs.io/en/stable/usage/auth_methods/\n[6]: https://openbao.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreaso%2Fhv4gha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandreaso%2Fhv4gha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandreaso%2Fhv4gha/lists"}