From e15695b3d99beaf8b130d443133bd5cfe8cc4be4 Mon Sep 17 00:00:00 2001
From: ash <ah37@sanger.ac.uk>
Date: Mon, 22 Jan 2024 09:50:27 +0000
Subject: [PATCH] Clarify integration test setup instructions (#38)

---
 README.md | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 9a1e8dd..5de99fc 100644
--- a/README.md
+++ b/README.md
@@ -104,21 +104,26 @@ Run tests with [Tox][]
 poetry run tox
 ```
 
-To run integration tests, you need a git repository set up with token access and
-a branch named after your git repo username (stripped of any @domain if your
-username is an email address).
+To run integration tests, you need:
 
-Make sure the artifacts/repo section of ~/.softpack/core/config.yml is
+- a git repository, hosted on e.g. GitHub or GitLab
+- an access token for the git repository
+  - for GitLab, this requires the "developer" role and the "write_repository" scope
+  - for GitHub, this requires read-write access to repository contents
+- a branch to run the tests on (must match `username` in the config below)
+- the appropriate SoftPack config, described below
+
+Make sure the artifacts/repo section of `~/.softpack/core/config.yml` is
 configured correctly:
 
-```
+```yaml
 artifacts:
   repo:
-    url: https://github.com/[your-org]/development-softpack-artifacts.git
-    username: [your-username]
-    author: [your-name]
-    email: [your-email]
-    writer: [your-token]
+    url: https://github.com/[your-org]/development-softpack-artifacts.git # HTTPS link to the repo
+    username: [your-username] # for whatever platform the repo is hosted on
+    author: [your-name] # can be anything
+    email: [your-email] # can be anything
+    writer: [your-token] # the access token for the repo (or your password for the repo host)
 ```
 
 Then enable the integration tests by suppling --repo to `poetry run pytest`, or