Files
threshing-atlas/docs/REPO_SETTINGS.md
ekcSchianoandClaude Opus 5.5 614bfcda7c Host on Gitea: forge.yaml, Gitea workflows, host-neutral links
- 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
2026-11-12 02:46:17 +00:00

6.4 KiB

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).