- forge.yaml: the repository's host (Gitea at git.kenschiano.net, limited visibility); the "Report a run" collector, the page's links (data/public/links.json, filled in by site/build.js) and the dataset metadata read it - collection/etl/forge.py: issues, pull requests (merge when checks succeed) and labels for Gitea and GitHub; `python -m collection forge ...` - .gitea/workflows: CI and the daily update (pushes a branch, opens a pull request that merges itself, opens an issue when a source breaks); .github/workflows kept for GitHub - docs: Gitea setup (REPO_SETTINGS), the bot reading atlas files from the repository Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UCzTd31GphpMXDhQqWrCMQ
120 lines
6.4 KiB
Markdown
120 lines
6.4 KiB
Markdown
# Repository settings
|
|
|
|
The Atlas is hosted on Gitea (`forge.yaml`: git.kenschiano.net). The GitHub repository and its GitHub Pages site are
|
|
paused while that account is suspended; their workflows stay in `.github/workflows/` for when it is back.
|
|
|
|
## Gitea: setting up the repository (once)
|
|
|
|
1. **Your account** on git.kenschiano.net (ask Ken), with 2FA on and your SSH key added (Settings → SSH / GPG Keys).
|
|
2. **Create the repository** `threshing-atlas` under your account, visibility **limited** (only people signed in to
|
|
the server), empty (no README or licence: they come from the push). Put your username in `forge.yaml` (`repo:`),
|
|
then `python -m collection build` and commit.
|
|
3. **Push** from your Mac copy:
|
|
|
|
```
|
|
cd ~/PycharmProjects/threshing-atlas
|
|
git remote rename origin github # keep the GitHub address for later
|
|
git remote add origin git@git.kenschiano.net:<you>/threshing-atlas.git
|
|
git push -u origin main
|
|
```
|
|
|
|
4. **Turn on Actions** (repository Settings → Units → Actions) and ask Ken which runner label the server has. The
|
|
workflows use `ubuntu-latest`; change `runs-on:` in `.gitea/workflows/*.yml` if it is different.
|
|
5. **Secrets** (Settings → Actions → Secrets):
|
|
|
|
| Secret | What it is | How to make it |
|
|
|---|---|---|
|
|
| `ATLAS_BOT_TOKEN` | lets the daily update push its branch, open the pull request and issues | your Settings → Applications → Generate token; permissions: repository read and write, issue read and write |
|
|
| `RAW_ARCHIVE_KEY` | encrypts the private raw store kept in the Actions cache between runs | any long random string (`openssl rand -base64 32`); keep a copy |
|
|
| `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET` | optional: read the megathreads through the Reddit API | see "Data collection secrets" below |
|
|
|
|
6. **Protect main** (Settings → Branches → Add rule for `main`): require a pull request, enable status checks and
|
|
require the check from the CI workflow (it shows up as `CI / test` after its first run), and allow
|
|
"merge when checks succeed". Leave required approvals at 0 so the daily update can merge itself.
|
|
7. **The label** for reports: `python -m collection forge ensure-label --name "run report"` (with
|
|
`ATLAS_BOT_TOKEN` set), or create it under Issues → Labels.
|
|
|
|
The daily update then runs at 10:23 UTC; run it by hand from the Actions tab (workflow "Check sources for new data").
|
|
Locally, `python -m collection refresh` does the same.
|
|
|
|
## The page
|
|
|
|
The page is built by `node site/build.js` and viewed locally or published as a Claude artifact; Gitea has no Pages.
|
|
Its links (the repository, "Report a run") come from `forge.yaml` through `data/public/links.json`.
|
|
|
|
## GitHub (paused)
|
|
|
|
# Repository settings
|
|
|
|
Some settings live on GitHub, not in the code. Only the repository owner (ekcSchiano) can change them.
|
|
They go together: the ruleset makes CI a gate on `main`, auto-merge lets a pull request merge itself once
|
|
it passes, and the token lets the daily data update do that on its own.
|
|
|
|
## 1. Allow auto-merge (issue #4)
|
|
|
|
Settings → General → Pull Requests:
|
|
|
|
- tick **Allow auto-merge**
|
|
- tick **Automatically delete head branches**
|
|
|
|
## 2. Require CI to pass on `main` (issue #5)
|
|
|
|
Settings → Rules → Rulesets → New ruleset → New branch ruleset:
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Ruleset name | `main: CI must pass` |
|
|
| Enforcement status | Active |
|
|
| Bypass list | leave empty |
|
|
| Target branches | Add target → Include default branch |
|
|
| Restrict deletions | on |
|
|
| Block force pushes | on |
|
|
| Require a pull request before merging | on, required approvals **0** |
|
|
| Require status checks to pass | on → Add checks → `test` (GitHub Actions) |
|
|
|
|
`test` is the job in `.github/workflows/ci.yml`. It runs the JS and Python tests, the JS/Python parity
|
|
checks, checks that `data/public/graph.json` is up to date, and builds the site.
|
|
|
|
From then on every change, including ours, goes through a pull request. Nothing can be pushed straight to
|
|
`main`. To merge without waiting, open the PR and turn on auto-merge; it merges when `test` passes.
|
|
|
|
## 3. Access token for automation (issue #6)
|
|
|
|
The daily source check (`.github/workflows/update-sources.yml`) opens a pull request when the community data
|
|
change. If it uses the built-in `GITHUB_TOKEN`, GitHub does not start other workflows from what it does. CI
|
|
still runs on the PR, but after the merge the site would not redeploy. With a token it opens the PR, turns on
|
|
auto-merge, and the merge redeploys the site.
|
|
|
|
Create the token at github.com → Settings → Developer settings → Personal access tokens → Fine-grained tokens →
|
|
Generate new token:
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Token name | `threshing-atlas automation` |
|
|
| Resource owner | ekcSchiano |
|
|
| Expiration | 90 days, with a calendar reminder to renew |
|
|
| Repository access | Only select repositories → `ekcSchiano/threshing-atlas` |
|
|
| Repository permissions | **Contents: Read and write**, **Pull requests: Read and write** (Metadata: Read-only is added automatically) |
|
|
|
|
Then store it as a secret, never in a file, issue, chat or commit: repository Settings → Secrets and
|
|
variables → Actions → New repository secret, name **`ATLAS_BOT_TOKEN`**.
|
|
|
|
Without the secret the workflow still works. It falls back to `GITHUB_TOKEN` and the PR waits for a manual
|
|
merge.
|
|
|
|
If Ken's bot should also open pull requests here (for example to send new bot runs), create a **second** token
|
|
with the same settings and store it as a secret in the bot's own repository. Separate tokens can be revoked
|
|
separately, and a leak in one place does not expose the other.
|
|
|
|
## Data collection secrets (optional)
|
|
|
|
Both are repository secrets (Settings → Secrets and variables → Actions → New repository secret). Without them the
|
|
daily update still runs and says in its report what it skipped.
|
|
|
|
| Secret | What it is for | How to make it |
|
|
|---|---|---|
|
|
| `RAW_ARCHIVE_KEY` | Encrypts the private raw store (current and previous raw file of each source) kept in the Actions cache between runs. | Any long random string, e.g. the output of `openssl rand -base64 32`. Keep a copy somewhere safe: without it the archive cannot be read. |
|
|
| `REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET` | Reading the r/fourthwing megathreads through the official Reddit API. | reddit.com/prefs/apps → "create another app…" → type **script**, any name, redirect uri `http://localhost`. The id is under the app name; the secret is labelled "secret". |
|
|
|
|
The "Report a run" form adds the label `run report` to each report; the label must exist (Issues → Labels).
|