{"id":21452282,"url":"https://github.com/packit/tokman","last_synced_at":"2025-07-14T22:31:01.841Z","repository":{"id":37268506,"uuid":"286668370","full_name":"packit/tokman","owner":"packit","description":"A token manager for GitHub Applications","archived":false,"fork":false,"pushed_at":"2024-08-26T22:54:11.000Z","size":123,"stargazers_count":0,"open_issues_count":3,"forks_count":8,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-08-27T01:42:50.741Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/packit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2020-08-11T06:50:29.000Z","updated_at":"2024-07-05T08:38:33.000Z","dependencies_parsed_at":"2023-01-28T04:31:03.439Z","dependency_job_id":"3d3dbc15-1d8a-4956-9753-03f7d9ec0355","html_url":"https://github.com/packit/tokman","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packit%2Ftokman","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packit%2Ftokman/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packit%2Ftokman/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/packit%2Ftokman/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/packit","download_url":"https://codeload.github.com/packit/tokman/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226001602,"owners_count":17558007,"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":[],"created_at":"2024-11-23T04:28:39.302Z","updated_at":"2024-11-23T04:28:40.036Z","avatar_url":"https://github.com/packit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tokman\n\nA token manager for GitHub Applications.\n\n## The problem\n\nWhen Packit Service is accessing repositories on behalf of our users, it\nauthenticates with an access token retrieved using the GitHub App ID and the\nGitHub App Private Key.\n\nTokens expire after 60 minutes or when a new token is retrieved for the same\nrepository.\n\nThe later creates a race condition when multiple Packit Service workers are\nperforming tasks on the same repository: as soon as a worker retrieves a new\ntoken, the tokens held by the other workers for the same repository become\ninvalid, and any operation they might attempt with these tokens will result in\na `401 Bad Credentials` error.\n\n`tokman` aims to solve the issue above, by factoring out the token retrieval\nin a single, internal service, running alongside Packit Service. When workers\nneed a token to access a repository, they call the `tokman` API to retrieve\nit. `tokman` handles requesting the tokens and renewing them when (or some\ntime before) they expire.\n\n`tokman`'s only guarantee about the tokens provided is that they are valid at\nthe time of the retrieval.\n\nTokens might expire though or become invalid (b/c `tokman` itself was\nrestarted).\n\nUsers of the API are responsible requesting a new token if a previous token\nproves to be invalid.\n\n## API\n\n```\nGET \u003ctokman_url\u003e/api/\u003cnamespace\u003e/\u003crepository\u003e\n\n200 OK\n\n{\n    \"namespace\": \"\u003cnamespace\u003e\",\n    \"repository\": \"\u003crepository\u003e\",\n    \"access_token\": \"\u003c...\u003e\"\n}\n\n400 BAD REQUEST\n\n{\n    \"error\": \"Failed to retrieve a token: App is not installed on \u003cnamespace\u003e/\u003crepository\u003e\"\n}\n```\n\n## Development\n\n`make build` builds the image.\n\n`make rebuild` builds the image ignoring any cache and making sure\nthe latest base image is pulled.\n\n`make build-test-image` builds the image.\n\n`make rebuild-test-image` builds the image ignoring any cache and making sure\nthe latest base image is pulled.\n\n`make check-in-container` runs tests in a container.\n`make check` runs the same tests locally.\n\nBefore running the app locally, make sure you create `config.py` by making a\ncopy of `config.py.example`. Update the value of `GITHUB_APP_ID` with the\nID of the GitHub App you want to use. Copy to corresponding private key in the\ncurrent directory as `private-key.pem` or indicate the directory where it's\nstored by setting `SECRETS_DIR`.\n\nStart the application container with `make run`.\n\nThe number of worker threads started by gunicorn can be controlled by setting\n`WORKERS`.\n\nThe logging level used can be configured by setting `LOG_LEVEL` to \"info\",\n\"warning\", \"debug\".\n\nFor development purposes you can also use `flask run` to run the application.\nBefore doing so:\n\n- Set up `config.py` and `private-key.pem` as described above.\n- Create and activate a Python virtual environment (with `mkvirtualenv tokman`, for example).\n- Install the app and the dependencies in the environment: `pip install -e .`\n- Set up the database:\n\n```\n$ DB_URI=sqlite:////tmp/access_tokens.db alembic upgrade head\n```\n\n- Run flask with a command similar to this:\n\n```\n$ TOKMAN_CONFIG=$PWD/config.py flask --app tokman run --debug\n```\n\n[link]: https://docs.github.com/en/developers/apps/authenticating-with-github-apps#authenticating-as-a-github-app\n[installation tokens]: https://docs.github.com/en/rest/reference/apps#create-an-installation-access-token-for-an-app\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpackit%2Ftokman","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpackit%2Ftokman","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpackit%2Ftokman/lists"}