https://github.com/plumber-cd/github-apps-trampoline
A cross-platform no-dependency GIT_ASKPASS trampoline for GitHub Apps, written in Go
https://github.com/plumber-cd/github-apps-trampoline
askpass github github-app github-apps trampoline
Last synced: 2 months ago
JSON representation
A cross-platform no-dependency GIT_ASKPASS trampoline for GitHub Apps, written in Go
- Host: GitHub
- URL: https://github.com/plumber-cd/github-apps-trampoline
- Owner: plumber-cd
- License: apache-2.0
- Created: 2021-09-18T02:15:39.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-26T23:43:41.000Z (9 months ago)
- Last Synced: 2024-08-27T02:13:02.481Z (9 months ago)
- Topics: askpass, github, github-app, github-apps, trampoline
- Language: Go
- Homepage:
- Size: 167 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# github-apps-trampoline
A cross-platform no-dependency GIT_ASKPASS trampoline for GitHub Apps, written in Go.
## Purpose
This is inspired by https://github.com/desktop/askpass-trampoline project.
If you already know what [GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps) is - you probably also know common challenges to work with them, namely - it's a bit of work to convert app credentials into a username+token pair that could be used by a regular Git clients such as Git CLI and various Git SDKs.
If you also know about [Git AskPass Credentials Helpers](https://git-scm.com/docs/gitcredentials) - your already know that there is actually an easy solution to these challenges. You can do something like `git config --global credential.helper "/usr/bin/my-helper"` and that way you can easily delegate to external program the process to generate JWT and request a temporary token with it. With a slight problem - you have to create that external program.
Yeah, that was a bit of a bummer. Almighty GitHub did not provide us with and "official" one, but oh well - that is not a rocket science and we can do it ourselves. This project is exactly that - an open source community-maintained configurable helper that can use your SSH Private Key to generate JWT and then request a temporary token with it. You don't have to create it - just configure it and make your Git client to use it.
It can also be used as a standalone CLI app so it can be embedded into workflows as a little helper to request temp credentials.
If you happen to write your workflows in Go - you could also use packages from this repository as dependencies to build your own.
## Installation
TBD
## Usage
TBD
```bash
# To use as a helper, configure your Git Client as follows
git config --global credential.useHttpPath true
git config --global credential.helper "/path/to/github-apps-trampoline -c /path/to/config.json"
# Configurable via JSON as AskPass Helper
# Using full JSON config will always supersede any CLI arguments
cat << EOF > config.json
{
"github\\.com/foo/bar": {
"key": "private.key",
"app": 1,
"permissions": {"contents": "write"},
"current_repo": true
},
"github\\.com/foo/.*": {
"key": "private.key",
"app": 1,
"permissions": {"contents": "read"}
},
".*": {
"key": "private.key",
"app": 1,
"installation_id": "",
"installation": "",
"repository_ids": "",
"repositories": "",
"permissions": {"contents": "read"}
}
}
EOF
github-apps-trampoline -c config.json
GITHUB_APPS_TRAMPOLINE="$(cat config.json)" github-apps-trampoline
GITHUB_APPS_TRAMPOLINE_CONFIG="config.json" github-apps-trampoline
# Somewhat configurable via CLI as AskPass Helper
# This will generate config.json in-memory with a single key
# Some of these examples are not secure to use:
# missing --permissions will assume all permissions from the app scope
# missing --repository-ids, --repositories and --current-repo will assume access to all repositories in the current installation
github-apps-trampoline --key private.key --app 1 --filter 'github\.com/foo/bar' --current-repo=true --permissions '{"contents": "write"}'
github-apps-trampoline --key private.key --app 1 --filter 'github\.com/foo/.*' --permissions '{"contents": "read"}'
github-apps-trampoline --key private.key --app 1 # using no --filter is the same as using --filter '.*'
github-apps-trampoline --key private.key --app 1 --permissions '{"contents": "read"}'
github-apps-trampoline --key private.key --app 1 --repository-ids 'XXX,YYY'
github-apps-trampoline --key private.key --app 1 --repositories 'bar,baz'
github-apps-trampoline --key private.key --app 1 --installation-id 'XXX'
github-apps-trampoline --key private.key --app 1 --installation 'github.com/foo'
# As a standalone CLI
# It will spit out JSON in STDOUT
# It will not read STDIN and will not use config.json - it will only use the CLI input
github-apps-trampoline --cli --key private.key --app 1 --installation 'github.com/foo' --repositories 'bar,baz' --permissions '{"contents": "read"}'
```
Enabling verbose mode will print credentials in STDERR - use with caution.