#+title: Mirroring forge from phab to github
#+author: ardumont, olasd

* Need

- the first step is writing a script that takes the URL (or ID) of
  *one* of our repos, and does the entire mirroring setup using the
  github API and the phabricator API
- having that script will also make it easy to maintain the sync in
  the future when we create new repos

* (forge) API token

generation: https://forge.softwareheritage.org/settings/user/ardumont/page/apitokens/

No setup needed, the token will be passed along to the command.

* (github) Create a public repository

With:
- name/description as in the forge
- wiki disabled
- issues disabled

https://developer.github.com/v3/repos/#create

** API (wip)

curl -H 'Authorization: token <user-token>' -X POST -d @/tmp/tmp.data https://api.github.com/v3/orgs/SoftwareHeritage/repos

/tmp/tmp.data:
#+BEGIN_SRC json
{
  "name": "<REPOSITORY>",
  "description": "<DESCRIPTION>",
  "homepage": "<forge's uri>",
  "private": false,
  "has_issues": false,
  "has_wiki": false,
  "has_downloads": true
}
#+END_SRC

Note:
User token is dependent on the user's profile.
When creating the token, it should have 'public_repo'
And the user must be a member of SoftwareHeritage.

* (forge) Edit repository URI

Edit the repository settings on forge.softwareheritage.org:
- Manage repository > URIs (see below for api call)
- Edit the credentials for that new uri to be K2

Values:
- Uri: github's ui
- I/O type: Mirror
- Display type: Hidden

Equivalent api call: https://forge.softwareheritage.org/conduit/method/diffusion.uri.edit/

|------------+---------------------------------------------------------------------------------------------------------------------------------------------------------|
| parameter  | Description                                                                                                                                             |
|------------+---------------------------------------------------------------------------------------------------------------------------------------------------------|
| repository | Create a URI in a given repository. This transaction type must be present when creating a new URI and must not be present when editing an existing URI. |
| uri        | Change the repository URI.                                                                                                                              |
| io         | Adjust I/O behavior.                                                                                                                                    |
| display    | Change display behavior.                                                                                                                                |
| credential | Change the credential for this URI.                                                                                                                     |
| disable    | Disable or activate the URI.                                                                                                                            |
|------------+---------------------------------------------------------------------------------------------------------------------------------------------------------|

Note: For a repository: https://forge.softwareheritage.org/conduit/method/diffusion.repository.edit/

A sample call would then be (thank olasd for the adaptation):
#+BEGIN_SRC sh
API_TOKEN=""  # token generated in setup phase
REPOSITORY_PHID="" # repository concerned by the mirroring (callsign?)
GITHUB_URI="" # github's mirror repository uri

curl https://forge.softwareheritage.org/api/diffusion.uri.edit \
-d api.token=$API_TOKEN \
-d transactions[0][type]=repository \
-d transactions[0][value]=$REPOSITORY_PHID \
-d transactions[1][type]=uri \
-d transactions[1][value]=$GITHUB_URI \
-d transactions[2][type]=io \
-d transactions[2][value]=mirror \
-d transactions[3][type]=display \
-d transactions[3][value]=never \
-d transactions[4][type]=credential \
-d transactions[4][value]=<K2-PHID>
#+END_SRC

* Test

- [ ] Create a dumb repository in phab's forge
- [ ] Trigger the script for that repository
- [ ] check results on github. Is the repository mirrored?
- [ ] Check results in forge. Is the repository's original uri ok?
- [ ] Push a new commit and push through forge, wait for the magic to happen
- [ ] Is that commit pushed on github's mirror? (expected answer is yes here :)