alunduil / alunduil/projects-v2-sync
The sync authenticates as a GitHub App when given app credentials
- 主要言語
- TypeScript
- スター
- 0
- フォーク
- 0
- 平均マージ
- 53分
- マージ済み PR(30日)
- 1
説明
## Summary
Let a consumer authenticate with a GitHub App — app id, private key, and
installation — instead of a personal access token.
## Motivation
The action takes one `token` input, and the only documented way to fill it
is a classic PAT. From
`docs/how-to/create-github-project-sync-token.md` in
alunduil/alunduil-infrastructure, that token carries `project` + `repo` +
`read:org`, expires in a year, and has a written rotation procedure.
That is a poor fit for anyone but its owner. The token is tied to a
person, outlives any single run, and carries `repo` across every source
the board reads. An App installation token is minted per run, expires in
an hour, belongs to an organisation rather than an individual, and can be
scoped to the permissions the sync actually uses.
## The cheaper half may already exist
In a workflow, no change to this action is needed.
[`actions/create-github-app-token`](https://github.com/actions/create-github-app-token)
is first-party and current (v3.2.0), and mints exactly this:
```yaml
- uses: actions/create-github-app-token@v3
id: app-token
with:
client-id: ${{ vars.SYNC_APP_CLIENT_ID }}
private-key: ${{ secrets.SYNC_APP_PRIVATE_KEY }}
permission-organization-projects: write
- uses: alunduil/projects-v2-sync@v1
with:
spec: github/projects/inbox.json
token: ${{ steps.app-token.outputs.token }}
```
So the first question is whether this issue is documentation or code. The
case for native inputs is #7: outside Actions there is no step to compose
with, and a CLI user would have to mint an installation token by hand.
## The constraint to settle first
App installation tokens are fine-grained tokens, and the token doc above
says plainly:
> A fine-grained token can't write a user-owned Projects v2 board.
`create-github-app-token` offers `permission-organization-projects` and
`permission-repository-projects`, with no user-projects equivalent, which
points the same way. If that holds, App auth covers org-owned boards only,
and the board this was built for — `owner: alunduil`, "Inbox" — still
needs a classic PAT.
That does not sink the issue; it scopes it. But it should be confirmed
against a real App installation before any input surface is designed,
because the answer decides whether App auth is an alternative to the PAT
or only an option for org-owned boards.
## Scope
- Confirm whether an App installation token can write a user-owned
Projects v2 board, and record the answer.
- Decide between documenting the `create-github-app-token` composition and
accepting app credentials directly. If both, the composition is the
smaller change and can land first.
- If native inputs: accept the app id (or client id), private key, and
installation, mint an installation token, and validate that exactly one
of the PAT and app-credential paths is supplied.
- Name the minimum permission set the sync needs, rather than inheriting
the classic PAT's `project` + `repo` + `read:org`.
- Document both paths in the README, including which board ownerships each
supports.
## Acceptance criteria
- [ ] The README documents authenticating as a GitHub App, with the
permissions required.
- [ ] The supported board ownerships for App auth are stated, with
evidence rather than inference.
- [ ] A sync runs end to end against an App installation.
- [ ] Supplying neither credential, or both, fails with a message naming
the problem.
- [ ] The PAT path keeps working unchanged.
## Additional context
- Related to #7: a CLI has no step to compose `create-github-app-token`
with, which is the main argument for native inputs over documentation.
- Related to #3, which introduces the API calls this authenticates.
- Consumer wiring is alunduil/alunduil-infrastructure#90.
コントリビューションガイド
このリポジトリのコントリビューションガイドは索引されていません
調査の方向性
Read docs/how-to/create-github-project-sync-token.md and the README, then verify App installation permissions against a real user-owned and organization-owned Projects v2 board. Decide whether documentation of actions/create-github-app-token is sufficient or native inputs are required. Done means the supported ownerships and permissions are evidenced, App authentication works end to end, credential validation is covered, and the PAT path remains unchanged.
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- github, github-actions, typescript
- 領域
- authentication, devops
- issue の種類
- 機能追加
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 活発
- 明瞭さ
- 説明が足りない
- 初心者へのやさしさ
- 35/100