Add the wiki, Quality and Release workflows #78
@@ -3,16 +3,21 @@ name: Quality
|
||||
# Calls the shared quality-check workflow of TirSystem/github-action
|
||||
# (contract: ADR-0005 there). It runs shellcheck and shfmt on the tracked
|
||||
# shell files and changes no file. Configuration comes from .shellcheckrc
|
||||
# and .editorconfig in this repository.
|
||||
# and .editorconfig in this repository. The release workflow requires this run
|
||||
# to be green on the commit it releases.
|
||||
on:
|
||||
pull_request:
|
||||
push:
|
||||
branches: [ main ]
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
quality:
|
||||
permissions:
|
||||
contents: read
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@main
|
||||
# Pinned to an exact tag, never to main; tools-ref pins the script to the
|
||||
# same tag, so the whole check is fixed.
|
||||
uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1.1.0
|
||||
with:
|
||||
languages: shell
|
||||
tools-ref: v1.1.0
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
name: Release
|
||||
|
||||
# Releases this repository: creates the version tag and the release page from
|
||||
# the CHANGELOG.md entry, and only when the commit is the tip of main, its
|
||||
# Quality run is green and the changelog has an entry for the version. The
|
||||
# script is a file of TirSystem/github-action (tools/release.py), fetched at an
|
||||
# exact tag. dry_run defaults to true: it checks and prints and writes nothing,
|
||||
# so a release is a deliberate second run with dry_run false.
|
||||
#
|
||||
# release.py also keeps a moving major tag (v0 for 0.x versions) pointing to
|
||||
# the highest release of its major version, as in TirSystem/github-action.
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: "Version to release, MAJOR.MINOR.PATCH without a leading v"
|
||||
required: true
|
||||
dry_run:
|
||||
description: "true checks only; false creates the tag and the release page"
|
||||
required: false
|
||||
default: "true"
|
||||
|
||||
concurrency:
|
||||
group: release
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
release:
|
||||
permissions:
|
||||
contents: write
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
steps:
|
||||
- name: Check out the repository
|
||||
uses: actions/checkout@v4.2.2
|
||||
|
||||
- name: Fetch the shared script
|
||||
uses: actions/checkout@v4.2.2
|
||||
with:
|
||||
repository: TirSystem/github-action
|
||||
ref: v1.1.0
|
||||
path: shared-scripts
|
||||
|
||||
- name: Check and publish the release
|
||||
env:
|
||||
GITEA_API_URL: ${{ gitea.api_url }}
|
||||
SOURCE_REPOSITORY: ${{ gitea.repository }}
|
||||
RELEASE_CREDENTIALS: ${{ secrets.TOKEN_FOR_GITEA_RELEASE || github.token }}
|
||||
RELEASE_VERSION: ${{ inputs.version }}
|
||||
RELEASE_DRY_RUN: ${{ inputs.dry_run }}
|
||||
RELEASE_SHA: ${{ gitea.sha }}
|
||||
# The status context of the Quality run on the commit. Check the exact
|
||||
# text on a pull request and correct it here if the dry run says the
|
||||
# run was not found.
|
||||
VALIDATION_CONTEXT: "Quality / quality (push)"
|
||||
run: python3 shared-scripts/tools/release.py
|
||||
@@ -0,0 +1,23 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to RepoFoundry. Versions are tags `vMAJOR.MINOR.PATCH`.
|
||||
The release workflow takes the text of a release page from the entry of its
|
||||
version, so every release needs an entry here before it is started.
|
||||
|
||||
Each release lists its changes in these groups, in this order: **Breaking**,
|
||||
**Added**, **Changed**, **Fixed**. A release with a Breaking entry has a new
|
||||
major version.
|
||||
|
||||
`python tools/changelog.py check` of `TirSystem/github-action` verifies this
|
||||
file.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
- Gitea workflows: Quality (shellcheck and shfmt through the shared reusable
|
||||
workflow) and Release (tag and release page from this changelog).
|
||||
- A `wiki/` folder with a `.publish` marker, published to the Gitea wiki by the
|
||||
shared Publish wiki workflow.
|
||||
- `switch_case_indent` for `*.sh` in `.editorconfig`, so `shfmt` accepts the
|
||||
existing layout of `case` branches.
|
||||
@@ -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