alunduil / alunduil/projects-v2-sync

The sync authenticates as a GitHub App when given app credentials

オープン
#8 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
enhancement
主要言語
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

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。