Accept TOKEN_FOR_GITEA_WIKI in .env and move the token howto to the wiki

TOKEN_FOR_GITEA_WIKI is an optional key, checked and masked but never used or asked for, so one .env can serve the wiki publishing too. GITHUB_PAT and GITHUB_USER are documented as required only when GitHub is chosen. The how-to for creating the access tokens moves from howto/ to the wiki as AccessTokens in English, Danish and Bahasa Malaysia, with its pictures in wiki/img/. README, Home and the sidebar link to it. Adds MIL-010 with its review RC-033 and the matching plan, user story and traceability rows. Task: MIL-010#1 Task: MIL-010#2 Task: MIL-010#3 Closes #83 Closes #84 Closes #85
2026-10-13 12:12:04 +08:00
parent fb549bfecc
commit 9cca29579f
32 changed files with 650 additions and 49 deletions
@@ -0,0 +1,197 @@
+<!-- translation of AccessTokens.md, source sha256 0cf4521af282 -->
+
+> Dette er en oversættelse af [`AccessTokens`](AccessTokens). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
+
+[English](AccessTokens) | Dansk | [Bahasa Melayu](AccessTokens.ms)
+
+# Sådan opretter du de adgangstokens, RepoFoundry har brug for
+
+RepoFoundry taler med to værter og har brug for ét token til hver:
+
+| Token | Nøgle | Nødvendig | Type |
+| --- | --- | --- | --- |
+| Gitea-adgangstoken | `GITEA_TOKEN` | altid | et adgangstoken med scopes |
+| GitHub personal access token | `GITHUB_PAT` | påkrævet, når du vælger GitHub (spejlet) | et **klassisk** personal access token (PAT) |
+| Gitea-adgangstoken til wikien | `TOKEN_FOR_GITEA_WIKI` | valgfri (kun for at udgive wikien) | et adgangstoken kun med repository-skriveadgang (`write:repository`) |
+
+`TOKEN_FOR_GITEA_WIKI` bruges ikke af RepoFoundry. Det er nævnt her, fordi den samme `.env` kan indeholde det, og RepoFoundry accepterer det dér. Opret det på samme måde som Gitea-tokenet i del 1, og sæt kun flueben ved repository-skriveadgang.
+
+Denne vejledning viser de to første trin for trin. De røde tal i hvert billede svarer til de nummererede trin ved siden af.
+
+> **Om billederne.** De er tegninger af siderne, ikke skærmbilleder, så de ikke viser kontodata. Navne, farver og placeringen af en knap kan afvige lidt i din version af Gitea eller GitHub. Ordene med fed skrift i trinene er de etiketter, du skal lede efter. Et nyt token vises som prikker i billederne; på din skærm ser du den rigtige værdi.
+
+Den fulde liste over, hvad hvert token må, står under [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) i README. Denne vejledning er klik-for-klik-udgaven af den.
+
+Indhold:
+
+1. [Opret et Gitea-adgangstoken](#1-opret-et-gitea-adgangstoken)
+2. [Opret et GitHub personal access token (klassisk)](#2-opret-et-github-personal-access-token-klassisk)
+3. [Giv tokens til RepoFoundry](#3-giv-tokens-til-repofoundry)
+4. [Opbevar tokens sikkert](#4-opbevar-tokens-sikkert)
+5. [Hvis noget går galt](#5-hvis-noget-går-galt)
+
+---
+
+## 1. Opret et Gitea-adgangstoken
+
+Eksemplerne bruger `https://git.tirsystem.com`. Hvis din Gitea kører et andet sted, så brug den adresse, du har sat som `GITEA_URL` i `config.env`.
+
+### Trin 1. Åbn dine indstillinger
+
+Log ind på Gitea. Klik på din **avatar** øverst til højre (1), og vælg **Settings** (2).
+
+![Trin 1: avatarmenuen øverst til højre med Settings fremhævet](img/gitea-1-open-settings.svg)
+
+### Trin 2. Åbn "Applications"
+
+Klik på **Applications** (1) i menuen til venstre.
+
+Du kan også gå direkte dertil: `<din Gitea-adresse>/user/settings/applications`.
+
+![Trin 2: Applications i venstre menu i indstillingerne](img/gitea-2-applications.svg)
+
+### Trin 3. Udfyld token-formularen
+
+Rul til **Generate New Token** og udfyld den:
+
+1. **Token Name:** et navn, du kan genkende senere, for eksempel `RepoFoundry`.
+2. **Repository and Organization Access:** vælg **All (public, private, and limited)**. Et token, der er begrænset til **Public only**, kan ikke se private repositories eller organisationer, så oprettelse af et privat projekt ville fejle.
+3. **Select permissions:** sæt disse tre til **Read and Write**, og lad alle andre linjer stå på **No Access**:
+
+   | Permission | Niveau | Hvorfor RepoFoundry har brug for den |
+   | --- | --- | --- |
+   | `organization` | Read and Write | slå ejeren og dine rettigheder op, oprette repositories i en organisation |
+   | `repository` | Read and Write | oprette repositoriet og styre dets push-spejl |
+   | `user` | Read and Write | læse hvilken konto tokenet tilhører, og oprette et repository under din **egen** konto |
+
+4. Klik på **Generate Token**.
+
+![Trin 3: token-formularen med navn, adgangsvalg og tre permissions sat til Read and Write](img/gitea-3-token-form.svg)
+
+> **Opretter du kun projekter i organisationer?** Så kan `user` blive på **Read**. `Read and Write` på `user` er kun nødvendigt for at oprette et repository under din egen konto; uden det svarer Gitea `required=[write:user]`.
+
+### Trin 4. Kopiér tokenet nu
+
+Gitea viser det nye token **én gang**, i en grøn besked øverst på siden (1). Kopiér det (brug kopiknappen, hvis din version har en, eller markér teksten og tryk Ctrl+C, Cmd+C på en Mac), og gem det til [del 3 i denne vejledning](#3-giv-tokens-til-repofoundry). Det nye token står nu på listen under (2) med sine permissions, men listen viser aldrig værdien igen.
+
+Hvis du mister værdien, så slet tokenet og opret et nyt.
+
+![Trin 4: den grønne besked med det nye token og en Copy-knap, og tokenet på listen nedenunder](img/gitea-4-copy-token.svg)
+
+---
+
+## 2. Opret et GitHub personal access token (klassisk)
+
+Spring denne del over, hvis du ikke vil oprette et GitHub-repository (`USE_GITHUB=no`, eller du svarer nej, når du bliver spurgt). `GITHUB_PAT` er så ikke nødvendig.
+
+Brug et **klassisk** token. RepoFoundry er ikke testet med fine-grained tokens, fordi GitHub ikke dokumenterer nogen fine-grained permission til at oprette et repository.
+
+### Trin 1. Åbn dine indstillinger
+
+Log ind på GitHub. Klik på dit **profilbillede** øverst til højre (1), og vælg **Settings** (2).
+
+![Trin 1: profilmenuen øverst til højre med Settings fremhævet](img/github-1-open-settings.svg)
+
+### Trin 2. Åbn "Developer settings"
+
+Rul ned i bunden af sidebjælken til venstre, og klik på **Developer settings** (1). Det er det sidste punkt.
+
+![Trin 2: Developer settings nederst i sidebjælken til venstre](img/github-2-developer-settings.svg)
+
+### Trin 3. Vælg "Tokens (classic)"
+
+1. Åbn **Personal access tokens** i sidebjælken til venstre, og klik på **Tokens (classic)** (1).
+2. Klik på **Generate new token** (2).
+3. I menuen, der åbner, vælg **Generate new token (classic)** (3). Ikke det første punkt, som er den fine-grained slags.
+
+GitHub kan bede dig bekræfte din adgangskode eller en tofaktorkode. Gør det selv; ingen andre bør skrive den.
+
+![Trin 3: Tokens (classic) i sidebjælken og Generate new token (classic) i knapmenuen](img/github-3-tokens-classic.svg)
+
+> Direkte adresse: `https://github.com/settings/tokens/new`
+
+### Trin 4. Udfyld formularen
+
+1. **Note:** et navn, du kan genkende senere, for eksempel `RepoFoundry`.
+2. **Expiration:** vælg en dato. En kortere levetid begrænser skaden, hvis tokenet lækker; du opretter så et nyt token, når det udløber.
+3. **Select scopes:** sæt flueben ved scopes nedenfor og intet andet.
+
+   | Scope | Sæt flueben, når | Hvorfor |
+   | --- | --- | --- |
+   | `repo` | altid (private eller offentlige projekter) | opretter repositoriet og er den adgangskode, Gitea bruger til at pushe spejlet |
+   | `public_repo` i stedet for `repo` | **kun** offentlige projekter | nok til at oprette og pushe et offentligt repository; `repo` omfatter det allerede |
+   | `read:org` | kun hvis scriptet siger, at du ikke tilhører din organisation | lader scriptet kontrollere dit medlemskab af en organisation som ejer |
+
+   Når du sætter flueben ved `repo`, får de fem underscopes (`repo:status`, `repo_deployment`, `public_repo`, `repo:invite`, `security_events`) også flueben; det er forventet. Lad `workflow`, `write:packages` og resten stå uden flueben.
+
+4. Rul ned, og klik på **Generate token** (4).
+
+![Trin 4: formularen til et nyt token med note, udløb, scopet repo afkrydset og knappen Generate token](img/github-4-token-form.svg)
+
+> **`read:org` og `admin:org`.** README fastslår, at kontrollen virkede med et token, der havde `repo` og `admin:org`, og at `read:org` alene er utestet. Prøv `read:org` først. `admin:org` giver langt mere magt, end RepoFoundry har brug for, så brug det kun, hvis `read:org` ikke er nok.
+
+### Trin 5. Kopiér tokenet nu
+
+GitHub viser tokenet **én gang**, i en grøn boks øverst (1). Klik på kopiikonet ved siden af. Det begynder med `ghp_`. Gem det til [del 3 i denne vejledning](#3-giv-tokens-til-repofoundry).
+
+Hvis ejeren af det nye repository er en organisation, der bruger SAML single sign-on, skal tokenet også godkendes til den organisation: klik på listen over tokens på **Configure SSO** (2) ved tokenet og derefter **Authorize** for organisationen.
+
+![Trin 5: den grønne boks med det nye token og et kopiikon, og Configure SSO på listen over tokens](img/github-5-copy-token.svg)
+
+---
+
+## 3. Giv tokens til RepoFoundry
+
+Vælg én måde. Begge holder tokenet ude af `config.env` (et token dér bliver afvist).
+
+**Mulighed A: skriv det, når du bliver spurgt (intet gemmes).** Gør ingenting på forhånd. RepoFoundry spørger efter `Gitea access token` fra start og efter `GitHub personal access token` og `GitHub account name`, når du vælger GitHub. Det, du skriver, vises ikke på skærmen. Indsæt kun tokenet, uden mellemrum, linjeskift eller anførselstegn.
+
+**Mulighed B: gem dem i `.env` (bekvemt, almindelig tekst på disken).** I RepoFoundry-mappen:
+
+```bash
+cp .env.example .env
+chmod 600 .env          # Linux og macOS: kun du kan læse den
+```
+
+Åbn `.env` og udfyld værdierne; erstat teksten i vinkelparenteser, og fjern parenteserne:
+
+```text
+GITEA_TOKEN=<Gitea-tokenet>
+GITHUB_PAT=<GitHub-tokenet>
+GITHUB_USER=<dit GitHub-kontonavn>
+TOKEN_FOR_GITEA_WIKI=<Gitea-tokenet til wikien, kun repository-skriveadgang>
+```
+
+`GITHUB_PAT` og `GITHUB_USER` er kun påkrævede, når du vælger GitHub (spejlet); udelad dem ellers. `TOKEN_FOR_GITEA_WIKI` er valgfri og kun nødvendig for at udgive wikien. Git ignorerer `.env`. Du må aldrig committe den, sende den eller indsætte den i en chat eller en issue.
+
+Kontrollér derefter opsætningen med en prøvekørsel, som kun læser fra værterne og ikke opretter noget:
+
+```bash
+src/create-project.sh
+```
+
+---
+
+## 4. Opbevar tokens sikkert
+
+- Et token er en adgangskode. Enhver, der har det, kan gøre det, det tillader.
+- Giv hvert token kun den adgang, der står i denne vejledning, og en udløbsdato.
+- Indsæt aldrig et token i en kommandolinje, en URL, en commit, en issue eller en chat.
+- Hvis et token kan være lækket, så slet det med det samme og opret et nyt:
+  - Gitea: **Settings**, **Applications**, derefter **Delete** ved det token.
+  - GitHub: **Settings**, **Developer settings**, **Personal access tokens**, **Tokens (classic)**, derefter **Delete** ved det token.
+- Når et token udløber, så opret et nyt på samme måde og erstat det i `.env`.
+
+---
+
+## 5. Hvis noget går galt
+
+| Det, du ser | Sandsynlig årsag | Hvad du skal gøre |
+| --- | --- | --- |
+| `authentication failed: the token is missing, expired or invalid` | tokenet er skrevet forkert, er udløbet eller er slettet | opret et nyt token og brug det |
+| `the token is valid but not allowed to do this (check its scopes)` | en permission mangler | Gitea: sæt `organization`, `repository` og `user` til **Read and Write**. GitHub: sæt flueben ved `repo` |
+| Gitea svarer `required=[write:user]` | projektet oprettes under din egen konto | sæt `user` til **Read and Write** |
+| `Gitea owner '...' is neither your account (...) nor an organization the token can see` | tokenet er begrænset til **Public only**, eller ejernavnet er forkert | gør tokenet **All (public, private, and limited)**, eller ret ejeren |
+| `GitHub owner '...' is neither your account (...) nor an organization you belong to (or the token lacks the read:org scope)` | tokenet kan ikke se organisationen | sæt flueben ved `read:org`, og godkend tokenet til organisationen, hvis den bruger single sign-on |
+| det indsatte token bliver afvist igen og igen | mellemrum, et linjeskift eller anførselstegn fulgte med indsætningen | kopiér det igen og indsæt kun tokenet |
+| `GITHUB_USER is '...' but the token belongs to '...'` | en advarsel: navnet i `.env` er ikke tokenets konto | ingen handling nødvendig; RepoFoundry bruger den konto, tokenet tilhører |
@@ -0,0 +1,245 @@
+English | [Dansk](AccessTokens.da) | [Bahasa Melayu](AccessTokens.ms)
+
+# How to create the access tokens RepoFoundry needs
+
+RepoFoundry talks to two hosts and needs one token for each:
+
+| Token | Key | Needed | Type |
+| --- | --- | --- | --- |
+| Gitea access token | `GITEA_TOKEN` | always | an access token with scopes |
+| GitHub personal access token | `GITHUB_PAT` | required when you choose GitHub (the mirror) | a **classic** personal access token (PAT) |
+| Gitea access token for the wiki | `TOKEN_FOR_GITEA_WIKI` | optional (only to publish the wiki) | an access token with the repository write scope (`write:repository`) only |
+
+`TOKEN_FOR_GITEA_WIKI` is not used by RepoFoundry. It is listed because the
+same `.env` may hold it, and RepoFoundry accepts it there. Create it the same
+way as the Gitea token in part 1, ticking only the repository write scope.
+
+This guide shows the first two, step by step. The red numbers in each picture
+match the numbered steps next to it.
+
+> **About the pictures.** They are drawings of the pages, not screenshots, so
+> that they show no account data. Names, colors and the position of a control
+> can differ a little in your version of Gitea or GitHub. The words in bold in
+> the steps are the labels to look for. A new token is shown as dots in the
+> pictures; on your screen you see its real value.
+
+The full list of what each token may do is in
+[Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) in the README. This guide
+is the click-by-click version of it.
+
+Contents:
+
+1. [Create a Gitea access token](#1-create-a-gitea-access-token)
+2. [Create a GitHub personal access token (classic)](#2-create-a-github-personal-access-token-classic)
+3. [Give the tokens to RepoFoundry](#3-give-the-tokens-to-repofoundry)
+4. [Keep the tokens safe](#4-keep-the-tokens-safe)
+5. [If something goes wrong](#5-if-something-goes-wrong)
+
+---
+
+## 1. Create a Gitea access token
+
+The examples use `https://git.tirsystem.com`. If your Gitea runs elsewhere, use
+the address you set as `GITEA_URL` in `config.env`.
+
+### Step 1. Open your settings
+
+Sign in to Gitea. Click your **avatar** in the top-right corner (1), then
+choose **Settings** (2).
+
+![Step 1: the avatar menu in the top-right corner, with Settings highlighted](img/gitea-1-open-settings.svg)
+
+### Step 2. Open "Applications"
+
+In the menu on the left, click **Applications** (1).
+
+You can also go straight there: `<your Gitea address>/user/settings/applications`.
+
+![Step 2: the Applications entry in the left menu of the settings](img/gitea-2-applications.svg)
+
+### Step 3. Fill in the token form
+
+Scroll to **Generate New Token** and fill it in:
+
+1. **Token Name:** a name you will recognise later, for example `RepoFoundry`.
+2. **Repository and Organization Access:** choose **All (public, private, and
+   limited)**. A token that is limited to **Public only** cannot see private
+   repositories or organizations, so creating a private project would fail.
+3. **Select permissions:** set these three to **Read and Write** and leave
+   every other line at **No Access**:
+
+   | Permission | Level | Why RepoFoundry needs it |
+   | --- | --- | --- |
+   | `organization` | Read and Write | look up the owner and your rights in it, create repositories in an organization |
+   | `repository` | Read and Write | create the repository and manage its push mirror |
+   | `user` | Read and Write | read which account the token belongs to, and create a repository under **your own** account |
+
+4. Click **Generate Token**.
+
+![Step 3: the token form with the name, the access choice and three permissions set to Read and Write](img/gitea-3-token-form.svg)
+
+> **Only creating projects in organizations?** Then `user` can stay at **Read**.
+> `Read and Write` on `user` is needed only to create a repository under your
+> own account; without it Gitea answers `required=[write:user]`.
+
+### Step 4. Copy the token now
+
+Gitea shows the new token **once**, in a green message at the top of the page
+(1). Copy it (use the copy button if your version has one, or select the text
+and press Ctrl+C, Cmd+C on a Mac) and keep it for
+[step 3 of this guide](#3-give-the-tokens-to-repofoundry). The new token is now
+in the list below it (2), with its permissions, but the list never shows its
+value again.
+
+If you lose the value, delete that token and generate a new one.
+
+![Step 4: the green message with the new token and a Copy button, and the token in the list below](img/gitea-4-copy-token.svg)
+
+---
+
+## 2. Create a GitHub personal access token (classic)
+
+Skip this part when you will not create a GitHub repository (`USE_GITHUB=no` or
+answering no when asked). `GITHUB_PAT` is then not needed.
+
+Use a **classic** token. RepoFoundry has not been tested with fine-grained
+tokens, because GitHub documents no fine-grained permission for creating a
+repository.
+
+### Step 1. Open your settings
+
+Sign in to GitHub. Click your **profile picture** in the top-right corner (1),
+then **Settings** (2).
+
+![Step 1: the profile menu in the top-right corner, with Settings highlighted](img/github-1-open-settings.svg)
+
+### Step 2. Open "Developer settings"
+
+In the left sidebar, scroll to the bottom and click **Developer settings** (1).
+It is the last entry.
+
+![Step 2: Developer settings at the bottom of the left sidebar](img/github-2-developer-settings.svg)
+
+### Step 3. Choose "Tokens (classic)"
+
+1. In the left sidebar, open **Personal access tokens** and click **Tokens
+   (classic)** (1).
+2. Click **Generate new token** (2).
+3. In the menu that opens, choose **Generate new token (classic)** (3). Not
+   the first entry, which is the fine-grained kind.
+
+GitHub may ask you to confirm your password or a two-factor code. Do that
+yourself; nobody else should type it.
+
+![Step 3: Tokens (classic) in the sidebar, and Generate new token (classic) in the button menu](img/github-3-tokens-classic.svg)
+
+> Direct address: `https://github.com/settings/tokens/new`
+
+### Step 4. Fill in the form
+
+1. **Note:** a name you will recognise later, for example `RepoFoundry`.
+2. **Expiration:** pick a date. A shorter life limits the damage if the token
+   leaks; you then create a new token when it ends.
+3. **Select scopes:** tick the scopes below and nothing else.
+
+   | Scope | Tick it when | Why |
+   | --- | --- | --- |
+   | `repo` | always (private or public projects) | creates the repository, and is the password Gitea uses to push the mirror |
+   | `public_repo` instead of `repo` | **only** public projects | enough to create and push a public repository; ticking `repo` already includes it |
+   | `read:org` | only if the script says you do not belong to your organization | lets the script check your membership of an organization owner |
+
+   Ticking `repo` also ticks its five sub-scopes (`repo:status`,
+   `repo_deployment`, `public_repo`, `repo:invite`, `security_events`); that is
+   expected. Leave `workflow`, `write:packages` and the rest unticked.
+
+4. Scroll down and click **Generate token** (4).
+
+![Step 4: the new token form with a note, an expiration, the repo scope ticked and the Generate token button](img/github-4-token-form.svg)
+
+> **`read:org` and `admin:org`.** The README records that the check worked with
+> a token that had `repo` and `admin:org`, and that `read:org` alone is
+> untested. Try `read:org` first. `admin:org` gives far more power than
+> RepoFoundry needs, so use it only if `read:org` is not enough.
+
+### Step 5. Copy the token now
+
+GitHub shows the token **once**, in a green box at the top (1). Click the copy
+icon next to it. It starts with `ghp_`. Keep it for
+[step 3 of this guide](#3-give-the-tokens-to-repofoundry).
+
+If the owner of the new repository is an organization that uses SAML single
+sign-on, the token must also be authorised for that organization: in the token
+list click **Configure SSO** (2) next to the token and then **Authorize**
+for the organization.
+
+![Step 5: the green box with the new token and a copy icon, and Configure SSO in the token list](img/github-5-copy-token.svg)
+
+---
+
+## 3. Give the tokens to RepoFoundry
+
+Choose one way. Both keep the token out of `config.env` (a token there is
+rejected).
+
+**Option A: type it when asked (nothing is stored).** Do nothing in advance.
+RepoFoundry asks for `Gitea access token` at the start, and for
+`GitHub personal access token` and `GitHub account name` once you choose
+GitHub. What you type is not shown on the screen. Paste only the token, with no
+spaces, no line break and no quote marks.
+
+**Option B: keep them in `.env` (convenient, plain text on disk).** In the
+RepoFoundry folder:
+
+```bash
+cp .env.example .env
+chmod 600 .env          # Linux and macOS: only you can read it
+```
+
+Open `.env` and fill in the values; replace the text in angle brackets and
+remove the brackets:
+
+```text
+GITEA_TOKEN=<the Gitea token>
+GITHUB_PAT=<the GitHub token>
+GITHUB_USER=<your GitHub account name>
+TOKEN_FOR_GITEA_WIKI=<the Gitea token for the wiki, repository write scope only>
+```
+
+`GITHUB_PAT` and `GITHUB_USER` are required only when you choose GitHub (the
+mirror); otherwise leave them out. `TOKEN_FOR_GITEA_WIKI` is optional and only
+needed to publish the wiki. Git ignores `.env`. Never commit it, send it, or paste it into a
+chat or an issue.
+
+Then check the setup with a dry run, which only reads from the hosts and
+creates nothing:
+
+```bash
+src/create-project.sh
+```
+
+---
+
+## 4. Keep the tokens safe
+
+- A token is a password. Anyone who has it can do what it allows.
+- Give each token only the access in this guide, and an expiration date.
+- Do not paste a token in a command line, a URL, a commit, an issue or a chat.
+- If a token may have leaked, delete it at once and make a new one:
+  - Gitea: **Settings**, **Applications**, then **Delete** on that token.
+  - GitHub: **Settings**, **Developer settings**, **Personal access tokens**,
+    **Tokens (classic)**, then **Delete** on that token.
+- When a token expires, create a new one the same way and replace it in `.env`.
+
+---
+
+## 5. If something goes wrong
+
+| What you see | Likely cause | What to do |
+| --- | --- | --- |
+| `authentication failed: the token is missing, expired or invalid` | the token was mistyped, has expired or was deleted | create a new token and use it |
+| `the token is valid but not allowed to do this (check its scopes)` | a permission is missing | Gitea: set `organization`, `repository` and `user` to **Read and Write**. GitHub: tick `repo` |
+| Gitea answers `required=[write:user]` | the project is being created under your own account | set `user` to **Read and Write** |
+| `Gitea owner '...' is neither your account (...) nor an organization the token can see` | the token is limited to **Public only**, or the owner name is wrong | make the token **All (public, private, and limited)**, or fix the owner |
+| `GitHub owner '...' is neither your account (...) nor an organization you belong to (or the token lacks the read:org scope)` | the token cannot see the organization | tick `read:org`, and authorise the token for the organization if it uses single sign-on |
+| the pasted token is refused again and again | spaces, a line break or quote marks came with the paste | copy it again and paste only the token |
+| `GITHUB_USER is '...' but the token belongs to '...'` | a warning: the name in `.env` is not the account of the token | no action needed; RepoFoundry uses the account the token belongs to |
@@ -0,0 +1,197 @@
+<!-- translation of AccessTokens.md, source sha256 0cf4521af282 -->
+
+> Ini ialah terjemahan [`AccessTokens`](AccessTokens). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
+
+[English](AccessTokens) | [Dansk](AccessTokens.da) | Bahasa Melayu
+
+# Cara mencipta token akses yang diperlukan RepoFoundry
+
+RepoFoundry berhubung dengan dua hos dan memerlukan satu token untuk setiap satu:
+
+| Token | Kunci | Diperlukan | Jenis |
+| --- | --- | --- | --- |
+| Token akses Gitea | `GITEA_TOKEN` | sentiasa | token akses dengan skop |
+| GitHub personal access token | `GITHUB_PAT` | diperlukan apabila anda memilih GitHub (cermin) | personal access token **klasik** (PAT) |
+| Token akses Gitea untuk wiki | `TOKEN_FOR_GITEA_WIKI` | pilihan (hanya untuk menerbitkan wiki) | token akses dengan skop tulis repositori sahaja (`write:repository`) |
+
+`TOKEN_FOR_GITEA_WIKI` tidak digunakan oleh RepoFoundry. Ia disenaraikan kerana `.env` yang sama mungkin mengandunginya, dan RepoFoundry menerimanya di situ. Cipta ia dengan cara yang sama seperti token Gitea dalam bahagian 1, dan tandakan skop tulis repositori sahaja.
+
+Panduan ini menunjukkan dua yang pertama, langkah demi langkah. Nombor merah dalam setiap gambar sepadan dengan langkah bernombor di sebelahnya.
+
+> **Tentang gambar.** Ia ialah lukisan halaman, bukan tangkapan skrin, supaya tiada data akaun dipaparkan. Nama, warna dan kedudukan sesuatu kawalan mungkin sedikit berbeza dalam versi Gitea atau GitHub anda. Perkataan bercetak tebal dalam langkah ialah label yang perlu dicari. Token baharu ditunjukkan sebagai titik dalam gambar; pada skrin anda, anda melihat nilai sebenarnya.
+
+Senarai penuh perkara yang dibenarkan oleh setiap token terdapat di bawah [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) dalam README. Panduan ini ialah versi klik demi klik daripadanya.
+
+Kandungan:
+
+1. [Cipta token akses Gitea](#1-cipta-token-akses-gitea)
+2. [Cipta GitHub personal access token (klasik)](#2-cipta-github-personal-access-token-klasik)
+3. [Berikan token kepada RepoFoundry](#3-berikan-token-kepada-repofoundry)
+4. [Simpan token dengan selamat](#4-simpan-token-dengan-selamat)
+5. [Jika sesuatu tidak berjalan lancar](#5-jika-sesuatu-tidak-berjalan-lancar)
+
+---
+
+## 1. Cipta token akses Gitea
+
+Contoh menggunakan `https://git.tirsystem.com`. Jika Gitea anda berada di tempat lain, gunakan alamat yang anda tetapkan sebagai `GITEA_URL` dalam `config.env`.
+
+### Langkah 1. Buka tetapan anda
+
+Log masuk ke Gitea. Klik **avatar** anda di penjuru kanan atas (1), kemudian pilih **Settings** (2).
+
+![Langkah 1: menu avatar di penjuru kanan atas dengan Settings ditonjolkan](img/gitea-1-open-settings.svg)
+
+### Langkah 2. Buka "Applications"
+
+Dalam menu di sebelah kiri, klik **Applications** (1).
+
+Anda juga boleh terus ke sana: `<alamat Gitea anda>/user/settings/applications`.
+
+![Langkah 2: entri Applications dalam menu kiri tetapan](img/gitea-2-applications.svg)
+
+### Langkah 3. Isi borang token
+
+Tatal ke **Generate New Token** dan isikannya:
+
+1. **Token Name:** nama yang anda akan kenali kemudian, contohnya `RepoFoundry`.
+2. **Repository and Organization Access:** pilih **All (public, private, and limited)**. Token yang terhad kepada **Public only** tidak dapat melihat repositori atau organisasi persendirian, jadi mencipta projek persendirian akan gagal.
+3. **Select permissions:** tetapkan ketiga-tiga ini kepada **Read and Write** dan biarkan setiap baris lain pada **No Access**:
+
+   | Permission | Tahap | Mengapa RepoFoundry memerlukannya |
+   | --- | --- | --- |
+   | `organization` | Read and Write | mencari pemilik dan hak anda di dalamnya, mencipta repositori dalam organisasi |
+   | `repository` | Read and Write | mencipta repositori dan mengurus cermin push-nya |
+   | `user` | Read and Write | membaca akaun yang memiliki token, dan mencipta repositori di bawah akaun **anda sendiri** |
+
+4. Klik **Generate Token**.
+
+![Langkah 3: borang token dengan nama, pilihan akses dan tiga permission ditetapkan kepada Read and Write](img/gitea-3-token-form.svg)
+
+> **Hanya mencipta projek dalam organisasi?** Maka `user` boleh kekal pada **Read**. `Read and Write` pada `user` hanya diperlukan untuk mencipta repositori di bawah akaun anda sendiri; tanpanya Gitea menjawab `required=[write:user]`.
+
+### Langkah 4. Salin token sekarang
+
+Gitea menunjukkan token baharu **sekali sahaja**, dalam mesej hijau di bahagian atas halaman (1). Salinnya (gunakan butang salin jika versi anda ada, atau pilih teks dan tekan Ctrl+C, Cmd+C pada Mac) dan simpan untuk [bahagian 3 panduan ini](#3-berikan-token-kepada-repofoundry). Token baharu kini berada dalam senarai di bawahnya (2), bersama permission-nya, tetapi senarai itu tidak pernah menunjukkan nilainya lagi.
+
+Jika anda kehilangan nilai itu, padam token tersebut dan jana yang baharu.
+
+![Langkah 4: mesej hijau dengan token baharu dan butang Copy, serta token dalam senarai di bawah](img/gitea-4-copy-token.svg)
+
+---
+
+## 2. Cipta GitHub personal access token (klasik)
+
+Langkau bahagian ini jika anda tidak akan mencipta repositori GitHub (`USE_GITHUB=no` atau menjawab tidak apabila ditanya). `GITHUB_PAT` tidak diperlukan.
+
+Gunakan token **klasik**. RepoFoundry belum diuji dengan token fine-grained, kerana GitHub tidak mendokumenkan permission fine-grained untuk mencipta repositori.
+
+### Langkah 1. Buka tetapan anda
+
+Log masuk ke GitHub. Klik **gambar profil** anda di penjuru kanan atas (1), kemudian **Settings** (2).
+
+![Langkah 1: menu profil di penjuru kanan atas dengan Settings ditonjolkan](img/github-1-open-settings.svg)
+
+### Langkah 2. Buka "Developer settings"
+
+Dalam bar sisi kiri, tatal ke bahagian bawah dan klik **Developer settings** (1). Ia ialah entri terakhir.
+
+![Langkah 2: Developer settings di bahagian bawah bar sisi kiri](img/github-2-developer-settings.svg)
+
+### Langkah 3. Pilih "Tokens (classic)"
+
+1. Dalam bar sisi kiri, buka **Personal access tokens** dan klik **Tokens (classic)** (1).
+2. Klik **Generate new token** (2).
+3. Dalam menu yang terbuka, pilih **Generate new token (classic)** (3). Bukan entri pertama, iaitu jenis fine-grained.
+
+GitHub mungkin meminta anda mengesahkan kata laluan atau kod dua faktor. Lakukannya sendiri; tiada orang lain patut menaipnya.
+
+![Langkah 3: Tokens (classic) dalam bar sisi, dan Generate new token (classic) dalam menu butang](img/github-3-tokens-classic.svg)
+
+> Alamat terus: `https://github.com/settings/tokens/new`
+
+### Langkah 4. Isi borang
+
+1. **Note:** nama yang anda akan kenali kemudian, contohnya `RepoFoundry`.
+2. **Expiration:** pilih tarikh. Hayat yang lebih pendek mengehadkan kerosakan jika token bocor; anda kemudian mencipta token baharu apabila ia tamat.
+3. **Select scopes:** tandakan skop di bawah dan tiada yang lain.
+
+   | Skop | Tandakan apabila | Sebab |
+   | --- | --- | --- |
+   | `repo` | sentiasa (projek persendirian atau awam) | mencipta repositori, dan ialah kata laluan yang digunakan Gitea untuk mem-push cermin |
+   | `public_repo` sebagai ganti `repo` | **hanya** projek awam | cukup untuk mencipta dan mem-push repositori awam; menandakan `repo` sudah merangkumnya |
+   | `read:org` | hanya jika skrip berkata anda bukan ahli organisasi anda | membolehkan skrip menyemak keahlian anda dalam organisasi pemilik |
+
+   Menandakan `repo` turut menandakan lima sub-skopnya (`repo:status`, `repo_deployment`, `public_repo`, `repo:invite`, `security_events`); itu dijangka. Biarkan `workflow`, `write:packages` dan yang lain tidak bertanda.
+
+4. Tatal ke bawah dan klik **Generate token** (4).
+
+![Langkah 4: borang token baharu dengan nota, tarikh luput, skop repo ditandakan dan butang Generate token](img/github-4-token-form.svg)
+
+> **`read:org` dan `admin:org`.** README mencatatkan bahawa semakan itu berjaya dengan token yang mempunyai `repo` dan `admin:org`, dan bahawa `read:org` sahaja belum diuji. Cuba `read:org` dahulu. `admin:org` memberi kuasa jauh lebih banyak daripada yang diperlukan RepoFoundry, jadi gunakannya hanya jika `read:org` tidak mencukupi.
+
+### Langkah 5. Salin token sekarang
+
+GitHub menunjukkan token **sekali sahaja**, dalam kotak hijau di bahagian atas (1). Klik ikon salin di sebelahnya. Ia bermula dengan `ghp_`. Simpan untuk [bahagian 3 panduan ini](#3-berikan-token-kepada-repofoundry).
+
+Jika pemilik repositori baharu ialah organisasi yang menggunakan SAML single sign-on, token juga mesti dibenarkan untuk organisasi itu: dalam senarai token, klik **Configure SSO** (2) di sebelah token dan kemudian **Authorize** untuk organisasi.
+
+![Langkah 5: kotak hijau dengan token baharu dan ikon salin, serta Configure SSO dalam senarai token](img/github-5-copy-token.svg)
+
+---
+
+## 3. Berikan token kepada RepoFoundry
+
+Pilih satu cara. Kedua-duanya mengekalkan token di luar `config.env` (token di situ ditolak).
+
+**Pilihan A: taip apabila ditanya (tiada apa disimpan).** Jangan buat apa-apa terlebih dahulu. RepoFoundry meminta `Gitea access token` pada permulaan, dan `GitHub personal access token` serta `GitHub account name` setelah anda memilih GitHub. Apa yang anda taip tidak dipaparkan pada skrin. Tampal token sahaja, tanpa ruang, pemisah baris atau tanda petik.
+
+**Pilihan B: simpan dalam `.env` (mudah, teks biasa pada cakera).** Dalam folder RepoFoundry:
+
+```bash
+cp .env.example .env
+chmod 600 .env          # Linux dan macOS: hanya anda boleh membacanya
+```
+
+Buka `.env` dan isi nilai; gantikan teks dalam kurungan sudut dan buang kurungan itu:
+
+```text
+GITEA_TOKEN=<token Gitea>
+GITHUB_PAT=<token GitHub>
+GITHUB_USER=<nama akaun GitHub anda>
+TOKEN_FOR_GITEA_WIKI=<token Gitea untuk wiki, skop tulis repositori sahaja>
+```
+
+`GITHUB_PAT` dan `GITHUB_USER` hanya diperlukan apabila anda memilih GitHub (cermin); tinggalkannya jika tidak. `TOKEN_FOR_GITEA_WIKI` ialah pilihan dan hanya diperlukan untuk menerbitkan wiki. Git mengabaikan `.env`. Jangan sekali-kali commit, hantar atau tampal ia dalam sembang atau issue.
+
+Kemudian semak persediaan dengan larian percubaan, yang hanya membaca daripada hos dan tidak mencipta apa-apa:
+
+```bash
+src/create-project.sh
+```
+
+---
+
+## 4. Simpan token dengan selamat
+
+- Token ialah kata laluan. Sesiapa yang memilikinya boleh melakukan apa yang dibenarkannya.
+- Berikan setiap token hanya akses yang terdapat dalam panduan ini, dan tarikh luput.
+- Jangan tampal token dalam baris perintah, URL, commit, issue atau sembang.
+- Jika token mungkin telah bocor, padamnya serta-merta dan cipta yang baharu:
+  - Gitea: **Settings**, **Applications**, kemudian **Delete** pada token itu.
+  - GitHub: **Settings**, **Developer settings**, **Personal access tokens**, **Tokens (classic)**, kemudian **Delete** pada token itu.
+- Apabila token tamat tempoh, cipta yang baharu dengan cara yang sama dan gantikannya dalam `.env`.
+
+---
+
+## 5. Jika sesuatu tidak berjalan lancar
+
+| Apa yang anda lihat | Punca yang mungkin | Apa yang perlu dibuat |
+| --- | --- | --- |
+| `authentication failed: the token is missing, expired or invalid` | token tersalah taip, telah tamat tempoh atau telah dipadam | cipta token baharu dan gunakannya |
+| `the token is valid but not allowed to do this (check its scopes)` | sesuatu permission tiada | Gitea: tetapkan `organization`, `repository` dan `user` kepada **Read and Write**. GitHub: tandakan `repo` |
+| Gitea menjawab `required=[write:user]` | projek dicipta di bawah akaun anda sendiri | tetapkan `user` kepada **Read and Write** |
+| `Gitea owner '...' is neither your account (...) nor an organization the token can see` | token terhad kepada **Public only**, atau nama pemilik salah | jadikan token **All (public, private, and limited)**, atau betulkan pemilik |
+| `GitHub owner '...' is neither your account (...) nor an organization you belong to (or the token lacks the read:org scope)` | token tidak dapat melihat organisasi | tandakan `read:org`, dan benarkan token untuk organisasi jika ia menggunakan single sign-on |
+| token yang ditampal ditolak berulang kali | ruang, pemisah baris atau tanda petik turut tertampal | salin semula dan tampal token sahaja |
+| `GITHUB_USER is '...' but the token belongs to '...'` | amaran: nama dalam `.env` bukan akaun pemilik token | tiada tindakan diperlukan; RepoFoundry menggunakan akaun yang memiliki token |
@@ -1,4 +1,4 @@
-<!-- translation of Home.md, source sha256 3ab3ef0f5a55 -->
+<!-- translation of Home.md, source sha256 18808e63abb7 -->

 > Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.

@@ -20,6 +20,7 @@ Det er et Bash-script. Det viser først en plan og opretter intet, før du angiv
 | --- | --- |
 | [Kom godt i gang](GettingStarted.da) | Krav, installation og første kørsel |
 | [SSH og tokens](SshAndTokens.da) | SSH-adgang til Gitea og de to adgangstokens |
+| [Adgangstokens](AccessTokens.da) | Opret adgangstokens trin for trin med billeder |
 | [Opdatering af frameworket](UpdatingTheFramework.da) | Hold et projekts framework-submodul opdateret |
 | [Fejlfinding](Troubleshooting.da) | Almindelige fejl og hvad du skal gøre |

@@ -16,6 +16,7 @@ It is a Bash script. It shows a plan first and creates nothing until you pass `-
 | --- | --- |
 | [Getting started](GettingStarted) | Requirements, install and the first run |
 | [SSH and tokens](SshAndTokens) | SSH access to Gitea and the two access tokens |
+| [Access tokens](AccessTokens) | Create the access tokens, step by step with pictures |
 | [Updating the framework](UpdatingTheFramework) | Keep the framework submodule of a project up to date |
 | [Troubleshooting](Troubleshooting) | Common failures and what to do |

@@ -1,4 +1,4 @@
-<!-- translation of Home.md, source sha256 3ab3ef0f5a55 -->
+<!-- translation of Home.md, source sha256 18808e63abb7 -->

 > Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.

@@ -20,6 +20,7 @@ Ia ialah skrip Bash. Ia memaparkan pelan dahulu dan tidak mencipta apa-apa sehin
 | --- | --- |
 | [Bermula](GettingStarted.ms) | Keperluan, pemasangan dan larian pertama |
 | [SSH dan token](SshAndTokens.ms) | Akses SSH ke Gitea dan dua token akses |
+| [Token akses](AccessTokens.ms) | Cipta token akses langkah demi langkah dengan gambar |
 | [Mengemas kini framework](UpdatingTheFramework.ms) | Pastikan submodul framework projek sentiasa terkini |
 | [Diagnosis](Troubleshooting.ms) | Kegagalan lazim dan tindakan yang perlu diambil |

@@ -1,4 +1,4 @@
-<!-- translation of SshAndTokens.md, source sha256 52d740c096c8 -->
+<!-- translation of SshAndTokens.md, source sha256 ec9001c0248b -->

 > Dette er en oversættelse af [`SshAndTokens`](SshAndTokens). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.

@@ -26,6 +26,7 @@ Framework-submodulet hentes over SSH på port **10022**. Før du kører scriptet
 | Token | Nøgle i `.env` | Nødvendig | Type |
 | --- | --- | --- | --- |
 | Gitea-adgangstoken | `GITEA_TOKEN` | altid | adgangstoken med scopes |
-| GitHub personal access token | `GITHUB_PAT` | kun hvis du vælger GitHub | **klassisk** personal access token |
+| GitHub personal access token | `GITHUB_PAT` | påkrævet, når du vælger GitHub (spejlet) | **klassisk** personal access token |
+| Gitea-adgangstoken til wikien | `TOKEN_FOR_GITEA_WIKI` | valgfri (kun for at udgive wikien) | adgangstoken kun med repository-skriveadgang (`write:repository`); scriptet accepterer den, men bruger den aldrig |

-Trin for trin med billeder: [sådan opretter du adgangstokens](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/howto/create-access-tokens.md). De præcise tilladelser står under [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) i README.
+Trin for trin med billeder: [sådan opretter du adgangstokens](AccessTokens.da). De præcise tilladelser står under [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) i README.
@@ -22,6 +22,7 @@ The framework submodule is fetched over SSH on port **10022**. Before you run th
 | Token | Key in `.env` | Needed | Type |
 | --- | --- | --- | --- |
 | Gitea access token | `GITEA_TOKEN` | always | access token with scopes |
-| GitHub personal access token | `GITHUB_PAT` | only when you choose GitHub | **classic** personal access token |
+| GitHub personal access token | `GITHUB_PAT` | required when you choose GitHub (the mirror) | **classic** personal access token |
+| Gitea access token for the wiki | `TOKEN_FOR_GITEA_WIKI` | optional (only to publish the wiki) | access token with the repository write scope (`write:repository`) only; the script accepts it but never uses it |

-Step by step with pictures: [how to create the access tokens](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/howto/create-access-tokens.md). The exact permissions are under [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) in the README.
+Step by step with pictures: [how to create the access tokens](AccessTokens). The exact permissions are under [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) in the README.
@@ -1,4 +1,4 @@
-<!-- translation of SshAndTokens.md, source sha256 52d740c096c8 -->
+<!-- translation of SshAndTokens.md, source sha256 ec9001c0248b -->

 > Ini ialah terjemahan [`SshAndTokens`](SshAndTokens). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.

@@ -26,6 +26,7 @@ Submodul framework diambil melalui SSH pada port **10022**. Sebelum anda menjala
 | Token | Kunci dalam `.env` | Diperlukan | Jenis |
 | --- | --- | --- | --- |
 | Token akses Gitea | `GITEA_TOKEN` | sentiasa | token akses dengan skop |
-| GitHub personal access token | `GITHUB_PAT` | hanya jika anda memilih GitHub | personal access token **klasik** |
+| GitHub personal access token | `GITHUB_PAT` | diperlukan apabila anda memilih GitHub (cermin) | personal access token **klasik** |
+| Token akses Gitea untuk wiki | `TOKEN_FOR_GITEA_WIKI` | pilihan (hanya untuk menerbitkan wiki) | token akses dengan skop tulis repositori sahaja (`write:repository`); skrip menerimanya tetapi tidak pernah menggunakannya |

-Langkah demi langkah dengan gambar: [cara mencipta token akses](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/howto/create-access-tokens.md). Kebenaran yang tepat terdapat di bawah [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) dalam README.
+Langkah demi langkah dengan gambar: [cara mencipta token akses](AccessTokens.ms). Kebenaran yang tepat terdapat di bawah [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/src/branch/main/README.md#token-permissions) dalam README.
@@ -5,6 +5,7 @@
 - [Home](Home)
 - [Getting started](GettingStarted)
 - [SSH and tokens](SshAndTokens)
+- [Access tokens](AccessTokens)
 - [Updating the framework](UpdatingTheFramework)
 - [Troubleshooting](Troubleshooting)

@@ -13,6 +14,7 @@
 - [Hjem](Home.da)
 - [Kom godt i gang](GettingStarted.da)
 - [SSH og tokens](SshAndTokens.da)
+- [Adgangstokens](AccessTokens.da)
 - [Opdatering af frameworket](UpdatingTheFramework.da)
 - [Fejlfinding](Troubleshooting.da)

@@ -21,5 +23,6 @@
 - [Utama](Home.ms)
 - [Bermula](GettingStarted.ms)
 - [SSH dan token](SshAndTokens.ms)
+- [Token akses](AccessTokens.ms)
 - [Mengemas kini framework](UpdatingTheFramework.ms)
 - [Diagnosis](Troubleshooting.ms)