diff --git a/.env.example b/.env.example index cb60066..62c35e8 100644 --- a/.env.example +++ b/.env.example @@ -1,18 +1,21 @@ # RepoFoundry credentials. Placeholders only: never put a real value in this # file or commit one. # -# Everything in this file is optional: a credential that is missing here is -# asked for when the script runs (the token is not echoed). +# Every key in this file may be left empty: a credential that is missing here +# is asked for when the script runs (the token is not echoed). GITEA_TOKEN is +# always needed; GITHUB_PAT and GITHUB_USER only when you choose GitHub; +# TOKEN_FOR_GITEA_WIKI is optional and never asked for. # # Copy this file to .env, fill in the values and keep it private # (chmod 600 .env on Linux and macOS). .env is ignored by git. The file is # read as plain KEY=VALUE lines and never executed. Values may be wrapped in # single or double quotes. -# GitHub personal access token. Needed only when you choose to create a -# GitHub repository. It creates the repository and is also the password of the -# Gitea push mirror, so it needs permission to create repositories for the -# chosen owner and to push to the new one. Prefer a fine-grained token. +# GitHub personal access token. Required when you choose to create a GitHub +# repository (the mirror); not used otherwise. It creates the repository and +# is also the password of the Gitea push mirror, so it needs permission to +# create repositories for the chosen owner and to push to the new one. Prefer +# a fine-grained token. GITHUB_PAT= ######################################## @@ -27,3 +30,8 @@ GITHUB_USER= # Gitea access token. It needs permission to create repositories # for the chosen owner and to manage the repository's push mirror. GITEA_TOKEN= + +# Optional. Gitea access token for publishing the wiki, with repository write +# scope only. RepoFoundry accepts it so one .env can serve both, but never uses +# or asks for it. +TOKEN_FOR_GITEA_WIKI= diff --git a/README.md b/README.md index 1fd573d..0caa433 100644 --- a/README.md +++ b/README.md @@ -197,12 +197,13 @@ src/create-project.sh --apply # asks only "Create these now (y/n) [n]" | Key | Meaning | | --- | --- | | `GITEA_TOKEN` | Gitea access token | -| `GITHUB_PAT` | GitHub personal access token (only when you choose GitHub) | -| `GITHUB_USER` | the GitHub account the token belongs to (only when you choose GitHub) | +| `GITHUB_PAT` | GitHub personal access token (required when you choose GitHub, so the mirror can be created; not used otherwise) | +| `GITHUB_USER` | the GitHub account the token belongs to (required when you choose GitHub; not used otherwise) | +| `TOKEN_FOR_GITEA_WIKI` | optional: Gitea access token for publishing the wiki, with the repository write scope (`write:repository`) only; accepted so one `.env` serves both, never used or asked for by this script | `.env` is ignored by git. The script warns if it is readable by other users or not ignored by git. See [Token permissions](#token-permissions) for what each -token needs, and [How to create the access tokens](howto/create-access-tokens.md) +token needs, and [How to create the access tokens](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/wiki/AccessTokens) for the steps, with pictures, to create the Gitea and the GitHub token. `.env` is optional, and so is each key in it. A credential that is not @@ -364,7 +365,7 @@ Both tokens go in `.env` (never in `config.env`, never in a remote URL). The script sends them only in a request header, through a private temporary file, and never prints them. -New to this? [How to create the access tokens](howto/create-access-tokens.md) +New to this? [How to create the access tokens](https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/wiki/AccessTokens) walks through both, step by step, with pictures. ### GitHub token (`GITHUB_PAT`, only when you choose GitHub) diff --git a/docs/artifact-registry.md b/docs/artifact-registry.md index 0392c0c..5d4b767 100644 --- a/docs/artifact-registry.md +++ b/docs/artifact-registry.md @@ -14,7 +14,7 @@ document of a type. `Primary File` may contain a glob (e.g. | BC | Business Case | docs/business-case.md | 002 | | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 | | PP | Project Plan | docs/project-plan.md | 002 | -| MIL | Milestone / Gateway | docs/milestones/*.md | 010 | +| MIL | Milestone / Gateway | docs/milestones/*.md | 011 | | US | User Story | docs/user-stories.md | 002 | | UC | Use Case | docs/uc-*/uc.md | 003 | | SSD | System Sequence Diagram | docs/uc-*/ssd.md | 003 | @@ -24,7 +24,7 @@ document of a type. `Primary File` may contain a glob (e.g. | DCD | Design Class Diagram | docs/dcd.md | 004 | | DICT | Domain Dictionary (PO and IT terms) | docs/dictionary.md | 002 | | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 | -| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 033 | +| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 034 | | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 | ## Languages diff --git a/docs/milestones/mil-010-wiki-token-and-access-token-guide.md b/docs/milestones/mil-010-wiki-token-and-access-token-guide.md new file mode 100644 index 0000000..3d29624 --- /dev/null +++ b/docs/milestones/mil-010-wiki-token-and-access-token-guide.md @@ -0,0 +1,77 @@ +# MIL-010 Wiki Token Accepted and Access-Token Guide in the Wiki + +## Metadata +| Key | Value | +| --- | --- | +| ID | MIL-010 | +| CrossReference | [BC-001], [US-001], [MIL-005] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S02 | Initial version | [9cca295] | + +--- + +## Purpose + +Decide whether one `.env` can serve both RepoFoundry and the publishing of its wiki, and whether the guide for creating the access tokens belongs to the wiki. The wiki is published with its own Gitea token, `TOKEN_FOR_GITEA_WIKI`, which has only the repository write scope. Today `create-project.sh` refuses a `.env` that holds it, because it rejects every key it does not know. The guide for creating the tokens lives in `howto/`, outside the wiki that is published in English, Danish and Bahasa Malaysia. + +## Deliverable + +`create-project.sh` that accepts `TOKEN_FOR_GITEA_WIKI` in `.env`: the key is optional, checked like the other tokens, kept out of every message and never used or asked for. The credential rules read the same everywhere: `GITEA_TOKEN` is always needed, `GITHUB_PAT` and `GITHUB_USER` only when GitHub is chosen, `TOKEN_FOR_GITEA_WIKI` never. The guide for creating the access tokens moves from `howto/create-access-tokens.md` to the wiki page `AccessTokens`, with a Danish and a Bahasa Malaysia translation and its pictures in `wiki/img/`; `README.md`, the wiki Home pages, the sidebar and the SSH and tokens pages link to it. The tests cover the cases below. + +The credentials the script asks for do not change, and no host request changes. The use cases and models are not changed: no concept, operation or class is added. [US-001] gets this phase in its CrossReference and one acceptance criterion on US-001.05. + +## Go / No-Go Criteria + +| # | Criterion (objectively checkable) | Go | No-Go | +| --- | --- | --- | --- | +| 1 | A `.env` that holds `TOKEN_FOR_GITEA_WIKI` is read without an error, and a `.env` without it behaves as before | Tests pass | An error for the key, or a changed result without it | +| 2 | A value of `TOKEN_FOR_GITEA_WIKI` that is not a valid token is refused with a message that names the key and never shows the value | Tests pass | The value shown, or an invalid value accepted | +| 3 | The value is registered as a secret: it appears in no message, summary or trace, and is never written to the project's own `.env` | Tests pass | The value shown or written | +| 4 | The key is never asked for, with or without GitHub chosen | Tests pass | A prompt for the key | +| 5 | `GITHUB_PAT` and `GITHUB_USER` are asked only when GitHub is chosen, as before | Tests pass | A prompt without GitHub, or none with it | +| 6 | `.env.example` is read without an error and documents the key as optional | Tests pass | An error, or the key undocumented | +| 7 | The page `AccessTokens` exists in English, Danish and Bahasa Malaysia; each translation names the hash of the English page it follows, and the hash matches | Reviewed by S02 | A missing language or a stale hash | +| 8 | The nine pictures are in `wiki/img/`, `howto/` is gone, and no file refers to `howto/` | Reviewed by S02 | A broken or leftover reference | +| 9 | `README.md`, the wiki Home pages, the sidebar and the SSH and tokens pages state the same required and optional keys and link to `AccessTokens` | Reviewed by S02 | A page that contradicts the code | + +## Dependencies + +| Depends on | Reason | +| --- | --- | +| [MIL-005] | The `.env` parser, the credential checks and the credential prompts are the ones this phase extends | + +## Traceability + +| Business Case objective / KPI / user story | Reference | +| --- | --- | +| Objective 9 (a credential not provided in `.env` is asked, never exposed) | [BC-001] | +| User story US-001.05 | [US-001] | + +## Ownership + +| Role | Stakeholder ID (SA) | +| --- | --- | +| Owner | S01 | +| Approving reviewer | S02 | + +## Target Date + +2026-12-30 — proposed; the Business Case sets no deadline. + +## Tasks + +| # | Task | Summary | Needs its own Use Case/User Story? | Reference | +| --- | --- | --- | --- | --- | +| 1 | Accept TOKEN_FOR_GITEA_WIKI in .env | Add the key to `CREDENTIAL_KEYS` (`src/lib/constants.sh`) so the parser no longer rejects a `.env` that is shared with the wiki publishing. In `validate_credentials` (`src/lib/config.sh`) register its value as a secret and check it like the other tokens; it is never asked for and never written to the project's own `.env`. Add it, as optional, to `.env.example` and the header of `src/create-project.sh`. Test the key accepted, an invalid value refused without showing it, and `.env.example` read. | No | | +| 2 | Move the access-token guide to the wiki | `git mv` `howto/create-access-tokens.md` to `wiki/AccessTokens.md` and its nine pictures to `wiki/img/`. Add the Danish and Bahasa Malaysia translations with the source-hash header the other pages use, and refresh the hashes of the pages whose English text changed. Link the page from `README.md` (it replaces the `howto/` links), the Home pages, the sidebar and the SSH and tokens pages. | No | | +| 3 | Document which credentials are required | Say in `README.md`, the SSH and tokens pages, the guide and `.env.example` that `GITEA_TOKEN` is always needed, `GITHUB_PAT` and `GITHUB_USER` only when GitHub is chosen (the mirror), and `TOKEN_FOR_GITEA_WIKI` is optional and used only to publish the wiki. | No | | + +--- + +[BC-001]: ../business-case.md +[US-001]: ../user-stories.md +[MIL-005]: ./mil-005-credentials.md +[9cca295]: https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/commit/9cca29579f032538902e9cfe929bb3c7768281ab diff --git a/docs/project-plan.md b/docs/project-plan.md index ef4153f..c73702c 100644 --- a/docs/project-plan.md +++ b/docs/project-plan.md @@ -4,23 +4,23 @@ | Key | Value | | --- | --- | | ID | PP-001 | -| CrossReference | [BC-001], [SA-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [US-001] | +| CrossReference | [BC-001], [SA-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [US-001] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-08 | Deprecated | Jens Tirsvad Nielsen | S02 | Added phase MIL-008 (proposed dates 2026-12-14 to 2026-12-18): the local project has origin as its only remote | [039a28c] | -| 2026-10-08 | Accepted | Jens Tirsvad Nielsen | S02 | Added phase MIL-009 (proposed dates 2026-12-21 to 2026-12-23): the framework files .claude, .agents and AGENTS.md are excluded from git | [08cb484] | +| 2026-10-08 | Deprecated | Jens Tirsvad Nielsen | S02 | Added phase MIL-009 (proposed dates 2026-12-21 to 2026-12-23): the framework files .claude, .agents and AGENTS.md are excluded from git | [08cb484] | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S02 | Added phase MIL-010 (proposed dates 2026-12-28 to 2026-12-30): the wiki token is accepted in .env and the access-token guide moves to the wiki | [9cca295] | --- ## Purpose -Schedule the nine phases that deliver RepoFoundry (`create-project.sh` and its documentation) in dependency order. The Business Case sets no deadline, so the dates below are proposals for S01 to confirm. +Schedule the ten phases that deliver RepoFoundry (`create-project.sh` and its documentation) in dependency order. The Business Case sets no deadline, so the dates below are proposals for S01 to confirm. ## Planning Assumptions -- Week 1 starts 2026-10-05; the plan ends by 2026-12-23 (the last four phases are proposed). +- Week 1 starts 2026-10-05; the plan ends by 2026-12-30 (the last five phases are proposed). - Phase length: two weeks. - S01 and S02 review each phase through a pull request, as described in [SA-001]. For now one person holds both roles. - The PO language is English, so no translated copies are kept. @@ -38,6 +38,7 @@ Schedule the nine phases that deliver RepoFoundry (`create-project.sh` and its d | Framework Checklists and Usage | [MIL-007] | 2026-12-07 to 2026-12-11 | 2026-12-11 | S01 | US-001.07 | qc fetched with the framework; global command; README usage | | | Gitea Is the Only Remote | [MIL-008] | 2026-12-14 to 2026-12-18 | 2026-12-18 | S01 | US-001.03 | The local project has `origin` only; GitHub is reached through the mirror | | | Framework Files Excluded from Git | [MIL-009] | 2026-12-21 to 2026-12-23 | 2026-12-23 | S01 | US-001.03 | `.claude`, `.agents` and `AGENTS.md` excluded from git in the new project | | +| Wiki Token and Access-Token Guide | [MIL-010] | 2026-12-28 to 2026-12-30 | 2026-12-30 | S01 | US-001.05 | `TOKEN_FOR_GITEA_WIKI` accepted in `.env`; access-token guide in the wiki | | ```plantuml @startgantt @@ -60,6 +61,8 @@ Project starts 2026-10-05 [Gitea Is the Only Remote Go/No-Go] happens 2026-12-18 [Framework Files Excluded from Git] starts 2026-12-21 and ends 2026-12-23 [Framework Files Excluded from Git Go/No-Go] happens 2026-12-23 +[Wiki Token and Access-Token Guide] starts 2026-12-28 and ends 2026-12-30 +[Wiki Token and Access-Token Guide Go/No-Go] happens 2026-12-30 @endgantt ``` @@ -80,11 +83,12 @@ Project starts 2026-10-05 | README usage from the target folder and as a global command | [MIL-007] | | The local project has `origin` as its only remote | [MIL-008] | | `.claude`, `.agents` and `AGENTS.md` excluded from git in the new project | [MIL-009] | +| `TOKEN_FOR_GITEA_WIKI` accepted in `.env`; access-token guide in the wiki | [MIL-010] | ## Dependencies ``` -MIL-001 → MIL-002 → MIL-003 → MIL-004 → MIL-005 → MIL-006 → MIL-007 → MIL-008 → MIL-009 +MIL-001 → MIL-002 → MIL-003 → MIL-004 → MIL-005 → MIL-006 → MIL-007 → MIL-008 → MIL-009 → MIL-010 ``` A No-Go moves every later date by the time needed to rework the failed criteria. @@ -117,11 +121,12 @@ A No-Go moves every later date by the time needed to rework the failed criteria. [MIL-007]: ./milestones/mil-007-framework-checklists.md [MIL-008]: ./milestones/mil-008-gitea-only-remote.md [MIL-009]: ./milestones/mil-009-exclude-framework-files.md +[MIL-010]: ./milestones/mil-010-wiki-token-and-access-token-guide.md [US-001]: ./user-stories.md [UC-001]: ./uc-001/uc.md [SSD-001]: ./uc-001/ssd.md [Milestone 43]: https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/milestone/43 [Milestone 44]: https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/milestone/44 [Milestone 45]: https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/milestone/45 -[039a28c]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/039a28c01b56f8cf0af73f55d1a604b43d67ba03 [08cb484]: https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/commit/08cb484498bab3d9480decda9df89e9564438185 +[9cca295]: https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/commit/9cca29579f032538902e9cfe929bb3c7768281ab diff --git a/docs/sqa/reviews/rc-033-wiki-token-and-access-token-guide.md b/docs/sqa/reviews/rc-033-wiki-token-and-access-token-guide.md new file mode 100644 index 0000000..6d3636a --- /dev/null +++ b/docs/sqa/reviews/rc-033-wiki-token-and-access-token-guide.md @@ -0,0 +1,74 @@ +# SQA Review Record: Wiki token accepted and access-token guide in the wiki + +## Metadata +| Key | Value | +| --- | --- | +| ID | RC-033 | +| CrossReference | [MIL-010], [QC-MIL-001], [MIL-005], [BC-001], [US-001], [PP-001] | + +## Version History +| Date | Status | Author | Reviewer | Change | Commit | +| --- | --- | --- | --- | --- | --- | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S02 | Initial version: draft for S02's decision | [9cca295] | + +--- + +## Artifact Under Review + +- Instance reviewed: [MIL-010], and the changes it causes in [US-001], [PP-001] and [TM-001]. +- Why: the wiki is published with its own Gitea token, `TOKEN_FOR_GITEA_WIKI`, which has only the repository write scope. A `.env` that holds it is refused today, because the parser rejects every key it does not know. The guide for creating the access tokens is also moved from `howto/` into the wiki, which is published in English, Danish and Bahasa Malaysia. The phase adds the key as an optional, never-asked credential, and states which credentials are required when. +- Checklist used: [QC-MIL-001] for [MIL-010]. The other artifacts were changed, not created; their change is checked below. +- Review date: 2026-10-13 + +## Checklist Results (QC-MIL-001) + +| # | Criterion | Status | Evidence/Notes | +| --- | --- | --- | --- | +| 1 | A concrete deliverable is defined for every gate | Pass | `create-project.sh` accepting `TOKEN_FOR_GITEA_WIKI` as an optional key that is checked, masked and never used or asked for; the access-token guide as the wiki page `AccessTokens` in three languages with its pictures in `wiki/img/`; the links in the README, Home pages, sidebar and SSH and tokens pages; the tests. The credentials the script asks for and every host request are stated as unchanged. | +| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Nine criteria, each with an objective Go and No-Go: key accepted, invalid value refused without being shown, value registered as a secret and never written, never asked, GitHub keys asked only when GitHub is chosen, `.env.example` read, the page in three languages with matching hashes, no reference to `howto/`, and the documents in agreement. Criteria 7 to 9 are "Reviewed by S02", as in [MIL-009]. | +| 3 | Dependencies on other milestones are explicitly mapped | Pass | [MIL-005], whose `.env` parser, credential checks and prompts are extended, with its reason. | +| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Objective 9 of [BC-001] (a credential not provided in `.env` is asked, never exposed), and US-001.05 of [US-001]. | +| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S01, approving reviewer S02. | +| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-12-30, proposed in [PP-001]; the window 2026-12-28 (Monday) to 2026-12-30 (Wednesday) follows [MIL-009], which ends Wednesday 2026-12-23. The Business Case sets no deadline. | + +## Change checks on the other artifacts + +| Artifact | Change | Status | Evidence/Notes | +| --- | --- | --- | --- | +| [US-001] | [MIL-010] in the CrossReference; one acceptance criterion and the Traces row of US-001.05 | Pass | One given/when/then: a `.env` that also holds `TOKEN_FOR_GITEA_WIKI` is read, the key is never asked for and never shown. No new story: the behavior belongs to the credentials story. | +| [PP-001] | Phase [MIL-010], its window, the Gantt, the scope coverage, the dependency chain, "ten phases" and the end date | Pass | Proposed dates 2026-12-28 to 2026-12-30. | +| [TM-001] | Row for [MIL-010] and this record; Last Reviewed updated for each changed artifact | Pass | See the matrix. | + +The Business Case, the use cases, the operation contracts and the models are not changed: no concept, operation or class is added, and the credentials the script asks for are the same. + +Mechanical checks run for this review: every link definition of the changed files points at an existing file and none is unused; the Gantt dates fall on the weekdays named above; [MIL-010] has 9 criteria and 3 tasks; `sync-project.sh --milestone MIL-010` parses it (milestone 103, issues #83 to #85 created on Gitea); the English page `AccessTokens` and its two translations carry the same hash, and the Home and SSH and tokens translations carry the hash of their changed English pages; the credential tests (`tests/run-tests.sh credentials`) pass, including the new test for the wiki token. + +Not covered by this review: the code, the wiki pages and the README are the tasks of [MIL-010] and are checked at its gate. Two tests of the full suite (`test_the_framework_checklists_are_fetched` and `test_an_empty_qc_is_filled_by_a_second_run_and_a_complete_one_is_not_changed`) fail on an untouched `HEAD` as well; they fetch the framework checklists and are not caused by this phase. + +## Consequences S02 accepts with a Go + +- The wiki pictures are published only if the shared `publish-wiki` workflow copies files other than Markdown. This was not verified here; if it does not, the pictures must be referenced by their address on `main` instead. +- The pictures keep their English labels in the Danish and Bahasa Malaysia pages. + +## Overall Verdict + +Go — every criterion of the checklist passes and the changed documents agree with each other. Drafted by Claude Code for S02; the author and reviewer are the same person for now, as in [RC-032]. S02 accepted [MIL-010] in chat on 2026-10-13 and asked for this record; the Version History rows of [MIL-010] and the changed documents were set to `Accepted` and the rows before them to `Deprecated`. + +## Action Items + +| Action | Owner | Due | +| --- | --- | --- | +| Check that the published wiki shows the pictures of `AccessTokens`, and fall back to addresses on `main` if it does not | S01 | After the wiki is published | + +--- + +[MIL-010]: ../../milestones/mil-010-wiki-token-and-access-token-guide.md +[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md +[MIL-005]: ../../milestones/mil-005-credentials.md +[MIL-009]: ../../milestones/mil-009-exclude-framework-files.md +[BC-001]: ../../business-case.md +[US-001]: ../../user-stories.md +[PP-001]: ../../project-plan.md +[TM-001]: ../traceability-matrix.md +[RC-032]: ./rc-032-exclude-framework-files.md +[9cca295]: https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/commit/9cca29579f032538902e9cfe929bb3c7768281ab diff --git a/docs/sqa/traceability-matrix.md b/docs/sqa/traceability-matrix.md index fc933e8..9d86cb8 100644 --- a/docs/sqa/traceability-matrix.md +++ b/docs/sqa/traceability-matrix.md @@ -9,8 +9,8 @@ ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-08 | Deprecated | Jens Tirsvad Nielsen | S02 | Added MIL-009 (framework files excluded from git); not yet reviewed | [08cb484] | -| 2026-10-08 | Accepted | Jens Tirsvad Nielsen | S02 | Added review RC-032 (MIL-009: framework files excluded from git), Go | [1b1b6be] | +| 2026-10-08 | Deprecated | Jens Tirsvad Nielsen | S02 | Added review RC-032 (MIL-009: framework files excluded from git), Go | [1b1b6be] | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S02 | Added MIL-010 (wiki token accepted, access-token guide in the wiki) and review RC-033, Go | [9cca295] | --- @@ -24,9 +24,9 @@ updated whenever an artifact instance is created or reviewed. | Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) | | --- | --- | --- | --- | --- | -| [BC-001] | BC | - | [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [US-001], [UCD-001] | [RC-010], [RC-018], [RC-020], [RC-022], [RC-029], [RC-031], [RC-032] | +| [BC-001] | BC | - | [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [US-001], [UCD-001] | [RC-010], [RC-018], [RC-020], [RC-022], [RC-029], [RC-031], [RC-032], [RC-033] | | [SA-001] | SA | [BC-001] | [UCD-001], [UC-001], [DICT-001] | [RC-013] | -| [PP-001] | PP | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009] | [RC-012], [RC-018], [RC-020], [RC-022], [RC-031], [RC-032] | +| [PP-001] | PP | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010] | [RC-012], [RC-018], [RC-020], [RC-022], [RC-031], [RC-032], [RC-033] | | [MIL-001] | MIL | [BC-001], [PP-001] | [US-001] | [RC-011], [RC-016] | | [MIL-002] | MIL | [BC-001], [PP-001] | [US-001] | [RC-014], [RC-017] | | [MIL-003] | MIL | [BC-001], [PP-001] | [US-001] | [RC-015], [RC-017], [RC-031] | @@ -36,8 +36,9 @@ updated whenever an artifact instance is created or reviewed. | [MIL-007] | MIL | [BC-001], [PP-001] | [US-001], [UC-002] | [RC-022], [RC-029], [RC-030] | | [MIL-008] | MIL | [BC-001], [PP-001] | [US-001] | [RC-031] | | [MIL-009] | MIL | [BC-001], [PP-001] | [US-001] | [RC-032] | +| [MIL-010] | MIL | [BC-001], [PP-001], [MIL-005] | [US-001] | [RC-033] | | [UCD-001] | UCD | [BC-001], [SA-001] | [US-001], [UC-001], [UC-002] | [RC-009], [RC-023] | -| [US-001] | US | [BC-001], [UCD-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009] | [UC-001] | [RC-001], [RC-020], [RC-022], [RC-029], [RC-030], [RC-031], [RC-032] | +| [US-001] | US | [BC-001], [UCD-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010] | [UC-001] | [RC-001], [RC-020], [RC-022], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033] | | [UC-001] | UC | [UCD-001], [US-001], [SA-001] | [SSD-001], [DM-001] | [RC-002], [RC-020], [RC-023], [RC-031], [RC-032] | | [UC-002] | UC | [UCD-001], [US-001], [SA-001], [BC-001] | [SSD-002], [DM-003] | [RC-023], [RC-029], [RC-030] | | [SSD-002] | SSD | [UC-002], [DM-003] | [OC-002] | [RC-024], [RC-029] | @@ -73,6 +74,7 @@ updated whenever an artifact instance is created or reviewed. [MIL-007]: ../milestones/mil-007-framework-checklists.md [MIL-008]: ../milestones/mil-008-gitea-only-remote.md [MIL-009]: ../milestones/mil-009-exclude-framework-files.md +[MIL-010]: ../milestones/mil-010-wiki-token-and-access-token-guide.md [RC-018]: ./reviews/rc-018-mil-004.md [RC-019]: ./reviews/rc-019-mil-004-code.md [RC-020]: ./reviews/rc-020-mil-005.md @@ -88,6 +90,7 @@ updated whenever an artifact instance is created or reviewed. [RC-030]: ./reviews/rc-030-env-optional.md [RC-031]: ./reviews/rc-031-gitea-only-remote.md [RC-032]: ./reviews/rc-032-exclude-framework-files.md +[RC-033]: ./reviews/rc-033-wiki-token-and-access-token-guide.md [DCD-001]: ../uc-001/dcd.md [DCD-002]: ../dcd.md [UCD-001]: ../use-case-diagram.md @@ -122,5 +125,5 @@ updated whenever an artifact instance is created or reviewed. [RC-015]: ./reviews/rc-015-mil-003.md [RC-016]: ./reviews/rc-016-create-project-sh.md [RC-017]: ./reviews/rc-017-e2e-security-review.md -[08cb484]: https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/commit/08cb484498bab3d9480decda9df89e9564438185 [1b1b6be]: https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/commit/1b1b6bec2effe5f566479ef94fcc5bc73a9fd609 +[9cca295]: https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/commit/9cca29579f032538902e9cfe929bb3c7768281ab diff --git a/docs/user-stories.md b/docs/user-stories.md index 1b04d1f..3101828 100644 --- a/docs/user-stories.md +++ b/docs/user-stories.md @@ -4,13 +4,13 @@ | Key | Value | | --- | --- | | ID | US-001 | -| CrossReference | [BC-001], [UCD-001], [UC-002], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009] | +| CrossReference | [BC-001], [UCD-001], [UC-002], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010] | ## Version History | Date | Status | Author | Reviewer | Change | Commit | | --- | --- | --- | --- | --- | --- | -| 2026-10-08 | Deprecated | Jens Tirsvad Nielsen | S02 | US-001.03: one remote, origin; no github remote (MIL-008) | [039a28c] | -| 2026-10-08 | Accepted | Jens Tirsvad Nielsen | S02 | US-001.03: `.claude`, `.agents` and `AGENTS.md` are excluded from git; MIL-009 added to CrossReference | [08cb484] | +| 2026-10-08 | Deprecated | Jens Tirsvad Nielsen | S02 | US-001.03: `.claude`, `.agents` and `AGENTS.md` are excluded from git; MIL-009 added to CrossReference | [08cb484] | +| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S02 | US-001.05: a `.env` shared with the wiki publishing may hold `TOKEN_FOR_GITEA_WIKI`, which is never asked for; MIL-010 added to CrossReference | [9cca295] | --- @@ -90,11 +90,12 @@ The epic is split into seven stories, one per milestone (US-001.01 to US-001.07) - Given an entered credential is not valid, when the script checks it, then it asks again and never shows the value. - Given the project exists, when the Maintainer agrees, then the new project has a `.env` that holds only the credentials the project needs, is readable by its owner only and is ignored by git. - Given the Maintainer declines, or `.env` already exists in the project and the Maintainer declines replacing it, then no `.env` is written or replaced and the summary says so. +- Given `.env` also holds `TOKEN_FOR_GITEA_WIKI`, when the script runs, then it is read without an error, is never asked for, with or without GitHub chosen, and never appears in output. - Given any run, then no credential appears in output, remotes, tracked files or the summary. | Traces to | Size | INVEST exceptions | | --- | --- | --- | -| [UC-001] steps 2 and 9, [MIL-005] | fits one phase | Independent: needs the local project of US-001.03 | +| [UC-001] steps 2 and 9, [MIL-005], [MIL-010] | fits one phase | Independent: needs the local project of US-001.03 | ### US-001.06 — Create a new project: choose the license in `config.env` @@ -168,6 +169,7 @@ Valuable, Negotiable, Estimable, Small and Testable hold for each story. Indepen [MIL-007]: ./milestones/mil-007-framework-checklists.md [MIL-008]: ./milestones/mil-008-gitea-only-remote.md [MIL-009]: ./milestones/mil-009-exclude-framework-files.md +[MIL-010]: ./milestones/mil-010-wiki-token-and-access-token-guide.md [PP-001]: ./project-plan.md -[039a28c]: https://git.tirsystem.com/TirSystem-BashScript/repo_foundry/commit/039a28c01b56f8cf0af73f55d1a604b43d67ba03 [08cb484]: https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/commit/08cb484498bab3d9480decda9df89e9564438185 +[9cca295]: https://git.tirsystem.com/TirSystem-BashScript/repo-foundry/commit/9cca29579f032538902e9cfe929bb3c7768281ab diff --git a/src/create-project.sh b/src/create-project.sh index d2d1189..ee9674d 100644 --- a/src/create-project.sh +++ b/src/create-project.sh @@ -40,8 +40,9 @@ # the optional GITEA_SSH_PORT (default 10022), MIRROR_INTERVAL # (default 10m0s) and FRAMEWORK_REPO (default # TirSystem/SQA-QC-Framework, the submodule's OWNER/NAME) -# .env GITHUB_PAT, GITHUB_USER, GITEA_TOKEN (all optional, each -# asked when missing) +# .env GITHUB_PAT, GITHUB_USER (required only when GitHub is chosen), +# GITEA_TOKEN (always required); each is asked when missing. +# TOKEN_FOR_GITEA_WIKI is optional and not used here # # Environment # REPOFOUNDRY_NAME project name used in messages (default: RepoFoundry) diff --git a/src/lib/config.sh b/src/lib/config.sh index 900333f..ed43000 100644 --- a/src/lib/config.sh +++ b/src/lib/config.sh @@ -155,6 +155,11 @@ validate_credentials() { if [[ -n ${CREDENTIALS[GITHUB_PAT]:-} ]]; then SECRET_VALUES+=("${CREDENTIALS[GITHUB_PAT]}") fi + if [[ -n ${CREDENTIALS[TOKEN_FOR_GITEA_WIKI]:-} ]]; then + SECRET_VALUES+=("${CREDENTIALS[TOKEN_FOR_GITEA_WIKI]}") + is_valid_token "${CREDENTIALS[TOKEN_FOR_GITEA_WIKI]}" || + die "TOKEN_FOR_GITEA_WIKI in $ENV_FILE is not a valid token ($HINT_TOKEN)" + fi if [[ -n ${CREDENTIALS[GITEA_TOKEN]:-} ]] && ! is_valid_token "${CREDENTIALS[GITEA_TOKEN]}"; then die "GITEA_TOKEN in $ENV_FILE is not a valid token ($HINT_TOKEN)" diff --git a/src/lib/constants.sh b/src/lib/constants.sh index 2a7eff9..01ab93e 100644 --- a/src/lib/constants.sh +++ b/src/lib/constants.sh @@ -41,7 +41,9 @@ readonly CONFIG_KEYS=(GITHUB_API_URL GITHUB_WEB_URL GITEA_URL GITEA_API_URL GITEA_SSH_PORT MIRROR_INTERVAL FRAMEWORK_REPO PROJECT_NAME PROJECT_DESCRIPTION PROJECT_VISIBILITY GITEA_OWNER USE_GITHUB GITHUB_OWNER PROJECT_DIRECTORY ENABLE_PLAN_GATE PROJECT_LICENSE) -readonly CREDENTIAL_KEYS=(GITHUB_PAT GITHUB_USER GITEA_TOKEN) +# TOKEN_FOR_GITEA_WIKI belongs to the wiki publishing; it is accepted so that +# one .env can serve both, checked and kept secret, but never used here. +readonly CREDENTIAL_KEYS=(GITHUB_PAT GITHUB_USER GITEA_TOKEN TOKEN_FOR_GITEA_WIKI) # The configuration files: named by --config and --env, or chosen by # locate_config_file. The origin is named, folder or checkout. diff --git a/tests/test-config.sh b/tests/test-config.sh index b5b0ddb..56095fa 100644 --- a/tests/test-config.sh +++ b/tests/test-config.sh @@ -100,6 +100,7 @@ token too short|GITEA_TOKEN=short\n|not a valid token token with a backslash|GITEA_TOKEN=abc\\defgh12345\n|not a valid token bad GitHub token|GITEA_TOKEN=abcdefgh12345\nGITHUB_PAT=bad token\n|GITHUB_PAT bad GitHub user|GITEA_TOKEN=abcdefgh12345\nGITHUB_USER=-bad-\n|GITHUB_USER +bad wiki token|TOKEN_FOR_GITEA_WIKI=short\n|TOKEN_FOR_GITEA_WIKI EOF } diff --git a/tests/test-credentials.sh b/tests/test-credentials.sh index 31fbb7f..c9de08a 100644 --- a/tests/test-credentials.sh +++ b/tests/test-credentials.sh @@ -136,6 +136,21 @@ test_github_credentials_are_asked_only_when_github_is_chosen() { assert_not_contains "token not shown" "$OUT$ERR" "$FAKE_GITHUB_PAT" } +test_the_wiki_token_is_accepted_never_asked_and_never_shown() { + local wiki_token="wikiFAKEtoken1234567890" + setup_hosts + printf 'GITEA_TOKEN=%s\nTOKEN_FOR_GITEA_WIKI=%s\n' "$FAKE_GITEA_TOKEN" "$wiki_token" >"$WORK/.env" + run_dry_cred "$ANSWERS_GITEA_ONLY" + assert_status "accepted in .env" 0 "$STATUS" + assert_not_contains "not asked" "$ERR" "wiki" + assert_not_contains "not shown" "$OUT$ERR" "$wiki_token" + run_dry_cred "$ANSWERS_GITHUB$FAKE_GITHUB_PAT${NL}octo-user$NL" + assert_status "accepted with GitHub chosen" 0 "$STATUS" + assert_not_contains "not asked with GitHub" "$ERR" "wiki" + assert_not_contains "not shown with GitHub" "$OUT$ERR" "$wiki_token" + assert_not_contains "never sent to a host" "$(calls)" "$wiki_token" +} + test_an_invalid_asked_value_is_asked_again_and_never_shown() { setup_hosts without_env diff --git a/wiki/AccessTokens.da.md b/wiki/AccessTokens.da.md new file mode 100644 index 0000000..366e9c5 --- /dev/null +++ b/wiki/AccessTokens.da.md @@ -0,0 +1,197 @@ + + +> 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: `/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= +GITHUB_PAT= +GITHUB_USER= +TOKEN_FOR_GITEA_WIKI= +``` + +`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 | diff --git a/howto/create-access-tokens.md b/wiki/AccessTokens.md similarity index 89% rename from howto/create-access-tokens.md rename to wiki/AccessTokens.md index 286d468..a2e7d6d 100644 --- a/howto/create-access-tokens.md +++ b/wiki/AccessTokens.md @@ -1,3 +1,5 @@ +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: @@ -5,10 +7,15 @@ 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` | only when you choose GitHub | a **classic** personal access token (PAT) | +| 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 | -This guide shows both, step by step. The red numbers in each picture match the -numbered steps next to it. +`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 @@ -17,7 +24,7 @@ numbered steps next to it. > pictures; on your screen you see its real value. The full list of what each token may do is in -[Token permissions](../README.md#token-permissions) in the README. This guide +[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: @@ -195,10 +202,12 @@ remove the brackets: GITEA_TOKEN= GITHUB_PAT= GITHUB_USER= +TOKEN_FOR_GITEA_WIKI= ``` -`GITHUB_PAT` and `GITHUB_USER` are needed only when you create a GitHub -repository. Git ignores `.env`. Never commit it, send it, or paste it into a +`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 diff --git a/wiki/AccessTokens.ms.md b/wiki/AccessTokens.ms.md new file mode 100644 index 0000000..8a79ef8 --- /dev/null +++ b/wiki/AccessTokens.ms.md @@ -0,0 +1,197 @@ + + +> 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: `/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= +GITHUB_PAT= +GITHUB_USER= +TOKEN_FOR_GITEA_WIKI= +``` + +`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 | diff --git a/wiki/Home.da.md b/wiki/Home.da.md index 8110382..fc5945d 100644 --- a/wiki/Home.da.md +++ b/wiki/Home.da.md @@ -1,4 +1,4 @@ - + > 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 | diff --git a/wiki/Home.md b/wiki/Home.md index 84d68b3..5ed8fc4 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -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 | diff --git a/wiki/Home.ms.md b/wiki/Home.ms.md index 3566876..f7b3edf 100644 --- a/wiki/Home.ms.md +++ b/wiki/Home.ms.md @@ -1,4 +1,4 @@ - + > 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 | diff --git a/wiki/SshAndTokens.da.md b/wiki/SshAndTokens.da.md index a31e911..4e28a27 100644 --- a/wiki/SshAndTokens.da.md +++ b/wiki/SshAndTokens.da.md @@ -1,4 +1,4 @@ - + > 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. diff --git a/wiki/SshAndTokens.md b/wiki/SshAndTokens.md index ba3eaef..c003b0c 100644 --- a/wiki/SshAndTokens.md +++ b/wiki/SshAndTokens.md @@ -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. diff --git a/wiki/SshAndTokens.ms.md b/wiki/SshAndTokens.ms.md index 31d3f3d..9de3a83 100644 --- a/wiki/SshAndTokens.ms.md +++ b/wiki/SshAndTokens.ms.md @@ -1,4 +1,4 @@ - + > 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. diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index b91942c..6bfbf3c 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -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) diff --git a/howto/img/gitea-1-open-settings.svg b/wiki/img/gitea-1-open-settings.svg similarity index 100% rename from howto/img/gitea-1-open-settings.svg rename to wiki/img/gitea-1-open-settings.svg diff --git a/howto/img/gitea-2-applications.svg b/wiki/img/gitea-2-applications.svg similarity index 100% rename from howto/img/gitea-2-applications.svg rename to wiki/img/gitea-2-applications.svg diff --git a/howto/img/gitea-3-token-form.svg b/wiki/img/gitea-3-token-form.svg similarity index 100% rename from howto/img/gitea-3-token-form.svg rename to wiki/img/gitea-3-token-form.svg diff --git a/howto/img/gitea-4-copy-token.svg b/wiki/img/gitea-4-copy-token.svg similarity index 100% rename from howto/img/gitea-4-copy-token.svg rename to wiki/img/gitea-4-copy-token.svg diff --git a/howto/img/github-1-open-settings.svg b/wiki/img/github-1-open-settings.svg similarity index 100% rename from howto/img/github-1-open-settings.svg rename to wiki/img/github-1-open-settings.svg diff --git a/howto/img/github-2-developer-settings.svg b/wiki/img/github-2-developer-settings.svg similarity index 100% rename from howto/img/github-2-developer-settings.svg rename to wiki/img/github-2-developer-settings.svg diff --git a/howto/img/github-3-tokens-classic.svg b/wiki/img/github-3-tokens-classic.svg similarity index 100% rename from howto/img/github-3-tokens-classic.svg rename to wiki/img/github-3-tokens-classic.svg diff --git a/howto/img/github-4-token-form.svg b/wiki/img/github-4-token-form.svg similarity index 100% rename from howto/img/github-4-token-form.svg rename to wiki/img/github-4-token-form.svg diff --git a/howto/img/github-5-copy-token.svg b/wiki/img/github-5-copy-token.svg similarity index 100% rename from howto/img/github-5-copy-token.svg rename to wiki/img/github-5-copy-token.svg