# DAIR GitHub Actions Testing
_**Repo to setup GitHub actions and simulate testing**_

This package is for testing template GitHub Actions, including simulating public/private repository synchronisation, and publishing to PyPI.

# Default Behaviour
Behaviour around branch names is overrideable, but by default:
 - PRIVATE branches `main` (default) and `release` (release branch)
 - PUBLIC branches `release` (default) and `incoming_from_private` (auto-generated)

In the PRIVATE repository:
 - Opening/updating a PR targeting `main` or `release` in the triggers build checks and tests
 - Opening a PR to `release` in the PRIVATE repo triggers build and test checks, and version control checks (ensuring a bump has occurred)
 - Merging a PR to `release` triggers synchronisation to the PUBLIC repo, by creating/updating a new `incoming_from_private` branch

In the PUBLIC repository:
 - Mering a PR to `release` triggers publishing to PyPI

These actions use two tokens:
 - `REPO_SYNC_TOKEN` set under the PUBLIC and PRIVATE repos
 - `PYPI_TOKEN` set under the PUBLIC repo

## Instructions
### Quick
 - Setup the PRIVATE and PUBLIC repositories (empty)
 - Setup the `config.yaml` with PRIVATE/PUBLIC repository names and target repos
 - Tweak branch triggering in each `.yaml` file if needed
 - Add a `REPO_SYNC_TOKEN` to the PRIVATE and PUBLIC repos
 - Add a `PYPI_TOKEN` to the PUBLIC repo

### Adding the REPO_SYNC_TOKEN
**Generate the Token**
 - In GitHub go to `Settings` under your profile (not repo settings)
 - Go to `Developer Settings`
 - Click `Personal access tokens` -> `Tokens (classic)`
 - Click `Generate new token` -> `Generate new token (classic)`
 - Provide a `Note` (e.g. 'syncing-package-name')
 - Tick `repo` and `workflow` under `Select scopes`
 - Click `Generate token` and copy the token in full

 **Save the Token**
 - Under both the PRIVATE and PUBLIC repos...
 - Go to the repo `Settings`
 - Click `Secrets and variables` and then `Actions`
 - Under `Repository secrets`, click `New Repository Secret`
 - Under `Name` enter `REPO_SYNC_TOKEN`, and paste the token in full to `Secret`


### Adding the PYPI_TOKEN
 - In PyPI, go to `Account settings` under your user
 - Scroll down to `API tokens` and click `Add API token`
 - Provide a `Token name` (e.g. 'publishing-package-name')
 - If the you have already published, you can select the `Scope` as 'project: project-name'; otherwise, you'll need to generate an `Entire Account (all projects)` scope, and then generate a new token (also updating in GitHub) after first publish
 - In the PUBLIC repo, go to the repo `Settings`
  Click `Secrets and variables` and then `Actions`
 - Under `Repository secrets`, click `New Repository Secret`
 - Under `Name` enter `PYPI_TOKEN`, and paste the token in full to `Secret`


## Note
 - Please suffix PRIVATE repos with `_dev` or `_development` for clarity
 - As PRIVATE -> PUBLIC auto-generated pull requests require a shared history, you will need to manually push your first (empty) commit to both PUBLIC and PRIVATE repos
 - To generate a 'project-specific' API token for PyPI publishing, you'll first need to publish using a general ('Entire account') token. You may publish manually for the first time, if desired. Once the package exists under your account, you'll be able to generate a token scoped to the specific project
