Add the wiki, Quality and Release workflows
Add a wiki/ folder with a .publish marker for the shared Publish wiki workflow, a Quality workflow (shellcheck and shfmt through the shared reusable workflow) and a manual Release workflow that builds the release page from CHANGELOG.md. Set switch_case_indent for *.sh in .editorconfig so shfmt accepts the existing case layout.
This commit is contained in:
@@ -0,0 +1,36 @@
|
||||
# Getting started
|
||||
|
||||
## Requirements
|
||||
|
||||
| Tool | Needed for |
|
||||
| --- | --- |
|
||||
| bash 4.4 or later | the script (macOS ships 3.2: install a newer bash first) |
|
||||
| `git` | the local project and the framework submodule |
|
||||
| `curl` | the GitHub and Gitea APIs |
|
||||
| `ssh` (optional) | the SSH check; without it the framework steps are skipped |
|
||||
| `jq` (optional) | JSON parsing; without it a small built-in reader is used |
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
git clone https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry.git
|
||||
cd RepoFoundry
|
||||
src/create-project.sh --help
|
||||
```
|
||||
|
||||
Nothing is installed system-wide: the script runs from the checkout.
|
||||
|
||||
## Configure
|
||||
|
||||
Copy `config.env.example` to `config.env` and `.env.example` to `.env`, then set the service addresses and the tokens (see [SSH and tokens](SSH-and-tokens)). `.env` holds credentials and is never committed.
|
||||
|
||||
## Run
|
||||
|
||||
Start the script from the folder that should hold the new project:
|
||||
|
||||
```bash
|
||||
src/create-project.sh # dry run: reads from the hosts, creates nothing
|
||||
src/create-project.sh --apply # creates everything after a final yes
|
||||
```
|
||||
|
||||
No commit is made in the new project. Work on a branch there: the framework's hooks refuse commits on `main`.
|
||||
@@ -0,0 +1,20 @@
|
||||
# Repo Foundry
|
||||
|
||||
Repo Foundry (`src/create-project.sh`) sets up a new project in one run:
|
||||
|
||||
- a **Gitea** repository, the source of truth;
|
||||
- optionally an empty **GitHub** repository that receives everything through a push mirror from Gitea;
|
||||
- a **local project** with one credential-free remote, `origin`, and the SQA-QC-Framework as a git submodule, with its skills, git hooks and templates installed.
|
||||
|
||||
It is a Bash script. It shows a plan first and creates nothing until you pass `--apply` and answer yes.
|
||||
|
||||
## Pages
|
||||
|
||||
| Page | What it covers |
|
||||
| --- | --- |
|
||||
| [Getting started](Getting-started) | Requirements, install and the first run |
|
||||
| [SSH and tokens](SSH-and-tokens) | SSH access to Gitea and the two access tokens |
|
||||
| [Troubleshooting](Troubleshooting) | Common failures and what to do |
|
||||
|
||||
The full reference (configuration files, security decisions, error handling, known limitations) is the [README](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/README.md).
|
||||
Report a problem as an [issue](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/issues).
|
||||
@@ -0,0 +1,25 @@
|
||||
# SSH and tokens
|
||||
|
||||
## SSH access to Gitea
|
||||
|
||||
The framework submodule is fetched over SSH on port **10022**. Before you run the script:
|
||||
|
||||
1. Add your SSH public key to your Gitea account.
|
||||
2. Connect once by hand so the server's host key is known (the script refuses unknown host keys):
|
||||
|
||||
```bash
|
||||
ssh -p 10022 -T git@git.tirsystem.com
|
||||
```
|
||||
|
||||
A message that you have successfully authenticated, without shell access, means it works.
|
||||
|
||||
> **Passphrase keys.** The script never prompts for a passphrase. A key with a passphrase must already be loaded in `ssh-agent` (`ssh-add`). This is tracked in [issue 77](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/issues/77).
|
||||
|
||||
## Tokens
|
||||
|
||||
| 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 |
|
||||
|
||||
Step by step with pictures: [how to create the access tokens](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/howto/create-access-tokens.md). The exact permissions are under [Token permissions](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/README.md#token-permissions) in the README.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Troubleshooting
|
||||
|
||||
| Symptom | What to check |
|
||||
| --- | --- |
|
||||
| The plan says the SSH test failed | Your key is in your Gitea account, the host key is known (`ssh -p 10022 -T git@git.tirsystem.com`), and a passphrase key is loaded with `ssh-add` |
|
||||
| The script stops at the tool check | bash is 4.4 or later, and `git` and `curl` are installed |
|
||||
| A host rejects the token | The token is current and has the scopes in [SSH and tokens](SSH-and-tokens) |
|
||||
| A run stopped half way | Fix the cause and run the same command again with `--apply`: what was already created is offered for reuse |
|
||||
|
||||
More: [Error handling and recovery](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/README.md#error-handling-and-recovery) and [Known limitations](https://git.tirsystem.com/TirSystem-BashScript/RepoFoundry/src/branch/main/README.md#known-limitations) in the README.
|
||||
@@ -0,0 +1,4 @@
|
||||
- [Home](Home)
|
||||
- [Getting started](Getting-started)
|
||||
- [SSH and tokens](SSH-and-tokens)
|
||||
- [Troubleshooting](Troubleshooting)
|
||||
Reference in New Issue
Block a user