mirror of
https://github.com/ZTatman/myst.git
synced 2026-11-22 12:57:58 +00:00
docs: rename Forgejo bot configuration
This commit is contained in:
parent
aa71b2b622
commit
3948b6763e
5 changed files with 25 additions and 26 deletions
|
|
@ -84,7 +84,7 @@ MYST_PUBLIC_URL="https://share.example.com"
|
||||||
MYST_ADMIN_URL="https://admin.example.com"
|
MYST_ADMIN_URL="https://admin.example.com"
|
||||||
DATABASE_URL="postgresql://myst:secret@localhost:5432/myst"
|
DATABASE_URL="postgresql://myst:secret@localhost:5432/myst"
|
||||||
FORGEJO_BASE_URL="https://git.example.com"
|
FORGEJO_BASE_URL="https://git.example.com"
|
||||||
FORGEJO_SERVICE_ACCOUNT_USERNAME="myst-bot"
|
FORGEJO_BOT_USERNAME="myst-bot"
|
||||||
FORGEJO_PAT="fgp_xxxxxxxxxxxxxxxxxxxx"
|
FORGEJO_PAT="fgp_xxxxxxxxxxxxxxxxxxxx"
|
||||||
GRANT_TOKEN_SECRET="your-secret-here"
|
GRANT_TOKEN_SECRET="your-secret-here"
|
||||||
```
|
```
|
||||||
|
|
|
||||||
|
|
@ -47,11 +47,11 @@ Phase 1 does not deliver:
|
||||||
|
|
||||||
## Security Baseline
|
## Security Baseline
|
||||||
|
|
||||||
- service account access is restricted to approved repos
|
- dedicated Forgejo user access is restricted to approved repos
|
||||||
- Myst grant checks are enforced on every Forgejo read
|
- Myst grant checks are enforced on every Forgejo read
|
||||||
- grants store `repo_id` and pinned `commit_sha`
|
- grants store `repo_id` and pinned `commit_sha`
|
||||||
- viewer requests never choose repo or ref directly
|
- viewer requests never choose repo or ref directly
|
||||||
- operators create the Forgejo service account and PAT themselves
|
- operators create the dedicated Forgejo user and PAT themselves
|
||||||
- Myst stores only its own app config and metadata in its own database
|
- Myst stores only its own app config and metadata in its own database
|
||||||
- admin access is protected upstream with Tailscale, VPN, Cloudflare Access, reverse-proxy auth, or equivalent operator-managed controls
|
- admin access is protected upstream with Tailscale, VPN, Cloudflare Access, reverse-proxy auth, or equivalent operator-managed controls
|
||||||
- Myst does not ship built-in admin auth in Phase 1
|
- Myst does not ship built-in admin auth in Phase 1
|
||||||
|
|
@ -66,8 +66,8 @@ Myst uses two authentication mechanisms:
|
||||||
- Users use their existing Forgejo accounts — no separate Myst login
|
- Users use their existing Forgejo accounts — no separate Myst login
|
||||||
- All Forgejo users with an account are trusted Myst users
|
- All Forgejo users with an account are trusted Myst users
|
||||||
|
|
||||||
**Data Access (Service Account PAT)**
|
**Data Access (Dedicated Forgejo User PAT)**
|
||||||
- Myst uses an operator-created service account PAT to call the Forgejo API
|
- Myst uses an operator-created PAT for a dedicated Forgejo user to call the Forgejo API
|
||||||
- PAT is used to verify repo ownership and fetch code for viewers
|
- PAT is used to verify repo ownership and fetch code for viewers
|
||||||
- PAT is never used for user identity (that's handled by sessions)
|
- PAT is never used for user identity (that's handled by sessions)
|
||||||
|
|
||||||
|
|
@ -76,9 +76,9 @@ Myst uses two authentication mechanisms:
|
||||||
- PAT allows Myst to verify repo ownership (can zach@me.com create view links for this repo?)
|
- PAT allows Myst to verify repo ownership (can zach@me.com create view links for this repo?)
|
||||||
- PAT allows Myst to fetch code content for the viewer (get the pinned commit's files)
|
- PAT allows Myst to fetch code content for the viewer (get the pinned commit's files)
|
||||||
|
|
||||||
## Forgejo Service Account Baseline
|
## Dedicated Forgejo User Baseline
|
||||||
|
|
||||||
- the Forgejo service account is a normal Forgejo user account dedicated to Myst, such as `myst-bot`
|
- the dedicated Forgejo user is a normal Forgejo user account dedicated to Myst, such as `myst-bot`
|
||||||
- the operator creates this user in Forgejo and grants repo access explicitly
|
- the operator creates this user in Forgejo and grants repo access explicitly
|
||||||
- the operator creates the PAT for this user through the Forgejo UI or admin CLI
|
- the operator creates the PAT for this user through the Forgejo UI or admin CLI
|
||||||
- recommended PAT scopes are `read:user` and `read:repository`
|
- recommended PAT scopes are `read:user` and `read:repository`
|
||||||
|
|
@ -112,7 +112,7 @@ Myst supports two types of view links:
|
||||||
|
|
||||||
Only repo owners can create view links for their repos.
|
Only repo owners can create view links for their repos.
|
||||||
|
|
||||||
- Myst verifies ownership via the Forgejo API using the service account PAT
|
- Myst verifies ownership via the Forgejo API using the dedicated Forgejo user PAT
|
||||||
- Collaborators or read-access users cannot create view links
|
- Collaborators or read-access users cannot create view links
|
||||||
- Site admins are treated as regular users for this purpose (details to be finalized)
|
- Site admins are treated as regular users for this purpose (details to be finalized)
|
||||||
|
|
||||||
|
|
@ -124,8 +124,8 @@ Only repo owners can create view links for their repos.
|
||||||
- private admin URL, for example `https://admin.example.com` or `https://myst-admin.tailnet.ts.net`
|
- private admin URL, for example `https://admin.example.com` or `https://myst-admin.tailnet.ts.net`
|
||||||
- Forgejo base URL, for example `https://git.example.com`
|
- Forgejo base URL, for example `https://git.example.com`
|
||||||
- Myst Postgres URL, for example `postgresql://myst:password@db.example.com:5432/myst`
|
- Myst Postgres URL, for example `postgresql://myst:password@db.example.com:5432/myst`
|
||||||
- Forgejo service account username, for example `myst-bot`
|
- Forgejo bot username, for example `myst-bot`
|
||||||
- Forgejo PAT for that service account
|
- Forgejo PAT for that dedicated Forgejo user
|
||||||
- grant token secret, with secure auto-generation as the default
|
- grant token secret, with secure auto-generation as the default
|
||||||
|
|
||||||
`myst init` should generate all Myst-owned deployment config needed for Phase 1:
|
`myst init` should generate all Myst-owned deployment config needed for Phase 1:
|
||||||
|
|
@ -139,7 +139,7 @@ Only repo owners can create view links for their repos.
|
||||||
- it should be run in the directory where Myst will be deployed, usually on the target VPS or server workspace
|
- it should be run in the directory where Myst will be deployed, usually on the target VPS or server workspace
|
||||||
- the admin URL must be protected upstream because Myst does not provide admin auth in Phase 1
|
- the admin URL must be protected upstream because Myst does not provide admin auth in Phase 1
|
||||||
- the database URL must point to Myst's own Postgres database, not Forgejo's tables
|
- the database URL must point to Myst's own Postgres database, not Forgejo's tables
|
||||||
- the PAT should be created for the dedicated service account user
|
- the PAT should be created for the dedicated Forgejo user
|
||||||
- the operator can consult Forgejo docs for token creation and scopes if needed
|
- the operator can consult Forgejo docs for token creation and scopes if needed
|
||||||
- bare hostnames such as `share.example.com` are accepted and should default to `https://`
|
- bare hostnames such as `share.example.com` are accepted and should default to `https://`
|
||||||
|
|
||||||
|
|
@ -148,7 +148,7 @@ Only repo owners can create view links for their repos.
|
||||||
- Forgejo is already deployed and operator-managed
|
- Forgejo is already deployed and operator-managed
|
||||||
- Myst is deployed independently as its own app
|
- Myst is deployed independently as its own app
|
||||||
- Myst uses its own Postgres database on the same DB server as Forgejo (separate database, not shared tables)
|
- Myst uses its own Postgres database on the same DB server as Forgejo (separate database, not shared tables)
|
||||||
- Myst reaches Forgejo via API using a least-privilege service account token
|
- Myst reaches Forgejo via API using a least-privilege PAT for the dedicated Forgejo user
|
||||||
- the CLI validates configuration and connectivity rather than provisioning infrastructure
|
- the CLI validates configuration and connectivity rather than provisioning infrastructure
|
||||||
- the Myst admin surface must be protected by VPN, Tailscale, Cloudflare Access, or reverse-proxy auth in front of the app
|
- the Myst admin surface must be protected by VPN, Tailscale, Cloudflare Access, or reverse-proxy auth in front of the app
|
||||||
|
|
||||||
|
|
@ -191,8 +191,8 @@ Minimum v1 data model:
|
||||||
`myst forgejo bootstrap` should verify, not provision:
|
`myst forgejo bootstrap` should verify, not provision:
|
||||||
|
|
||||||
- Forgejo base URL reachability
|
- Forgejo base URL reachability
|
||||||
- service account token validity
|
- dedicated Forgejo user token validity
|
||||||
- authenticated user matches the configured service account username
|
- authenticated user matches the configured Forgejo bot username
|
||||||
- minimum token scopes are sufficient for Myst's read-only API usage
|
- minimum token scopes are sufficient for Myst's read-only API usage
|
||||||
- Myst can resolve repo metadata, pinned commits, and tree/file reads for the repos it is expected to serve
|
- Myst can resolve repo metadata, pinned commits, and tree/file reads for the repos it is expected to serve
|
||||||
- Myst can verify repo ownership for the operator's user account
|
- Myst can verify repo ownership for the operator's user account
|
||||||
|
|
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
{
|
{
|
||||||
"adminUrl": "https://admin.example.com",
|
"adminUrl": "https://admin.example.com",
|
||||||
"forgejoBaseUrl": "https://git.example.com",
|
"forgejoBaseUrl": "https://git.example.com",
|
||||||
"forgejoServiceAccountUsername": "myst-bot",
|
"forgejoBotUsername": "myst-bot",
|
||||||
"publicUrl": "https://share.example.com"
|
"publicUrl": "https://share.example.com"
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -172,20 +172,19 @@ export async function initCommand(_args: string[]): Promise<void> {
|
||||||
placeholder: "postgresql://myst:password@db.example.com:5432/myst",
|
placeholder: "postgresql://myst:password@db.example.com:5432/myst",
|
||||||
validate: validatePostgresUrl,
|
validate: validatePostgresUrl,
|
||||||
}),
|
}),
|
||||||
forgejoServiceAccountUsername: () =>
|
forgejoBotUsername: () =>
|
||||||
p.text({
|
p.text({
|
||||||
message:
|
message: "What dedicated Forgejo username should Myst use for API access?",
|
||||||
"What Forgejo service account username should Myst use for API access?",
|
|
||||||
placeholder: "myst-bot",
|
placeholder: "myst-bot",
|
||||||
validate: (v) =>
|
validate: (v) =>
|
||||||
v?.trim()
|
v?.trim()
|
||||||
? undefined
|
? undefined
|
||||||
: "Forgejo service account username is required",
|
: "Dedicated Forgejo username is required",
|
||||||
}),
|
}),
|
||||||
forgejoPat: () =>
|
forgejoPat: () =>
|
||||||
p.password({
|
p.password({
|
||||||
message:
|
message:
|
||||||
"Paste the Forgejo personal access token for that service account",
|
"Paste the Forgejo personal access token for that dedicated Forgejo user",
|
||||||
validate: (v) => (v?.trim() ? undefined : "Forgejo PAT is required"),
|
validate: (v) => (v?.trim() ? undefined : "Forgejo PAT is required"),
|
||||||
}),
|
}),
|
||||||
grantTokenSecret: () =>
|
grantTokenSecret: () =>
|
||||||
|
|
@ -213,8 +212,8 @@ export async function initCommand(_args: string[]): Promise<void> {
|
||||||
adminUrl,
|
adminUrl,
|
||||||
databaseUrl: answers.databaseUrl,
|
databaseUrl: answers.databaseUrl,
|
||||||
forgejoBaseUrl,
|
forgejoBaseUrl,
|
||||||
|
forgejoBotUsername: answers.forgejoBotUsername,
|
||||||
forgejoPat: answers.forgejoPat,
|
forgejoPat: answers.forgejoPat,
|
||||||
forgejoServiceAccountUsername: answers.forgejoServiceAccountUsername,
|
|
||||||
grantTokenSecret,
|
grantTokenSecret,
|
||||||
publicUrl,
|
publicUrl,
|
||||||
});
|
});
|
||||||
|
|
@ -222,7 +221,7 @@ export async function initCommand(_args: string[]): Promise<void> {
|
||||||
{
|
{
|
||||||
adminUrl,
|
adminUrl,
|
||||||
forgejoBaseUrl,
|
forgejoBaseUrl,
|
||||||
forgejoServiceAccountUsername: answers.forgejoServiceAccountUsername,
|
forgejoBotUsername: answers.forgejoBotUsername,
|
||||||
publicUrl,
|
publicUrl,
|
||||||
},
|
},
|
||||||
null,
|
null,
|
||||||
|
|
@ -259,7 +258,7 @@ export async function initCommand(_args: string[]): Promise<void> {
|
||||||
`${c.bold("Public viewer URL:")} ${c.cyan(publicUrl)}`,
|
`${c.bold("Public viewer URL:")} ${c.cyan(publicUrl)}`,
|
||||||
`${c.bold("Private admin URL:")} ${c.cyan(adminUrl)}`,
|
`${c.bold("Private admin URL:")} ${c.cyan(adminUrl)}`,
|
||||||
`${c.bold("Forgejo base URL:")} ${c.cyan(forgejoBaseUrl)}`,
|
`${c.bold("Forgejo base URL:")} ${c.cyan(forgejoBaseUrl)}`,
|
||||||
`${c.bold("Forgejo service account:")} ${c.green(answers.forgejoServiceAccountUsername)}`,
|
`${c.bold("Forgejo bot username:")} ${c.green(answers.forgejoBotUsername)}`,
|
||||||
"",
|
"",
|
||||||
`${c.bold("Admin URL reminder:")} protect this upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth.`,
|
`${c.bold("Admin URL reminder:")} protect this upstream with Tailscale, VPN, Cloudflare Access, or reverse-proxy auth.`,
|
||||||
].join("\n"),
|
].join("\n"),
|
||||||
|
|
|
||||||
|
|
@ -2,8 +2,8 @@ interface EnvOptions {
|
||||||
adminUrl: string;
|
adminUrl: string;
|
||||||
databaseUrl: string;
|
databaseUrl: string;
|
||||||
forgejoBaseUrl: string;
|
forgejoBaseUrl: string;
|
||||||
|
forgejoBotUsername: string;
|
||||||
forgejoPat: string;
|
forgejoPat: string;
|
||||||
forgejoServiceAccountUsername: string;
|
|
||||||
grantTokenSecret: string;
|
grantTokenSecret: string;
|
||||||
publicUrl: string;
|
publicUrl: string;
|
||||||
}
|
}
|
||||||
|
|
@ -30,9 +30,9 @@ MYST_ADMIN_URL=${escapeEnvValue(options.adminUrl)}
|
||||||
# Myst's own Postgres database.
|
# Myst's own Postgres database.
|
||||||
DATABASE_URL=${escapeEnvValue(options.databaseUrl)}
|
DATABASE_URL=${escapeEnvValue(options.databaseUrl)}
|
||||||
|
|
||||||
# Existing Forgejo instance and operator-created service account token.
|
# Existing Forgejo instance and operator-created PAT for the dedicated Forgejo user.
|
||||||
FORGEJO_BASE_URL=${escapeEnvValue(options.forgejoBaseUrl)}
|
FORGEJO_BASE_URL=${escapeEnvValue(options.forgejoBaseUrl)}
|
||||||
FORGEJO_SERVICE_ACCOUNT_USERNAME=${escapeEnvValue(options.forgejoServiceAccountUsername)}
|
FORGEJO_BOT_USERNAME=${escapeEnvValue(options.forgejoBotUsername)}
|
||||||
FORGEJO_PAT=${escapeEnvValue(options.forgejoPat)}
|
FORGEJO_PAT=${escapeEnvValue(options.forgejoPat)}
|
||||||
|
|
||||||
# Secret used to sign or derive grant tokens.
|
# Secret used to sign or derive grant tokens.
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue