How-to
Send the code to GitHub
After the load, the tool can put the code it moved into your GitHub repository, so your team can keep working on it there. It always uses a new branch and opens a pull request. It never writes to the branch you choose as the base.
IMT_GITHUB_SEND).What is sent
Every code and asset file the tool wrote to the new instance, read back from the new instance as it is now, at the path it has in a project, such as app/views/pages/index.liquid. So a change made on Transform, a final sync or a Copy again is in it. The files of a final sync are included.
Not sent: database rows, people, the values of constants, keys, and a module's private files. A file you left behind on Transform is not sent either.
When the source was read, and files only the old site has
The tool reads the old site's code once, at the start of a migration. A copy of it can be days old by the time you use it. So the tool says exactly when it was read, and, where a repository is linked to the migration, compares the two.
- When it was read. The Pages and code step on Transform, and the GitHub step, say The source code was read on a date and time (UTC). It also names the repository's latest commit at that moment.
- Newer commits. If the repository's branch has commits the read did not see, a warning says Re-read the source before copying and names the latest commit. Copying the old read in would undo what those commits changed. A send also notes it on its log and in the pull request.
- Files only the old site has. The tool lists the files the old site holds that the repository does not, grouped by folder, as one To do job: Files on the old site that are not in your repository: drop or keep. A repository often deleted such files on purpose (an old checkout, old order pages, test pages, an old migration). Copying them makes those old pages work again on the new site.
- Drop or keep. Press Leave these files behind on Pages and code, or on the To do job, to leave them out of the copy. They then show under Code files left behind, with the reason. Do nothing, or tick the job done, to copy them as before. The tool never leaves a file out on its own.
- No repository linked. The comparison is not possible, and the page says so. Choose a repository on the Destination step, then press Check against the repository again. The tool reads the repository only. It never writes to it for this check.
The repository must hold the site's code at app/ and modules/ at the top. If none of the old site's files are in it at those paths, the tool says it cannot compare them, instead of listing every file.
1. Connect GitHub
- On the Destination stage, open the GitHub (optional) step.
- Press Connect GitHub. GitHub opens in a small window. Install the Insites GitHub App on your organization and choose which repositories it may reach. If the App is on your organization already, press The Insites GitHub App is installed already and sign in to GitHub.
- The window closes and the step lists the organizations you connected. Only organizations your own GitHub sign-in can see are connected, and only to the account you are working in. Press Install on another organization to add one more.
You need the operator role in the tool. Roles.
Installed the App on GitHub first?
If you installed the Insites GitHub App from GitHub itself, rather than from the GitHub step, GitHub sends you to the tool's GitHub is installed page. It connects the installation to your account like this:
- Not signed in? Press Sign in. You come back to the same page once you are signed in.
- The page asks GitHub which installations your own GitHub sign-in can see, and names them, such as insites-io (GitHub organization). Nothing is connected yet.
- Check the account you are working in, in the account switcher in the menu on the left. Switch account there first if the installation belongs to another one.
- Press Connect, for example Connect insites-io to Acme Digital. The page says GitHub is connected and links to Settings, your migrations and a new migration.
- Only an owner of the account can connect from this page. In your Personal account you are its owner. Operators can connect GitHub on a migration's Destination step instead.
- GitHub's sign-in lasts about 10 minutes. If it runs out first, for example while you wait for the sign-in email, the page says so. Press Connect GitHub again to sign in to GitHub once more and come straight back. You do not need to install the App again.
- An installation your own GitHub sign-in cannot see is never connected, even if its number is in the address.
- When you change which repositories the App can reach on GitHub, GitHub sends you back to the same page, which says the installation is updated. There is nothing more to do.
- To connect GitHub from Settings, an owner presses connect it here or Connect another, which opens the same page.
2. Choose where the code goes
- Organization: one you connected.
- Repository: one the App can reach, or Create a new repository. Only the repositories the App was given are listed. If yours is missing, an owner of the organization adds it in the App's settings on GitHub (the step links there), then press load the list again. A new one is private unless you untick Private, and it is made when the code is first sent. GitHub lets the App make a repository only in an organization. For a personal account, make the repository on GitHub, give the App access to it, and choose it here.
- Base branch: the branch the pull request goes into. Nothing is written to it.
- New branch for the moved code: filled in for you as
insites-migration/and the date. It must be a new name: the tool refuses a branch that already exists unless this migration made it. - Press Save this choice. The tool checks the choice with GitHub before the load, so the load does not finish into a choice that cannot work. The button turns on as soon as the choice is complete, and while it is held it says what is still needed. Once saved, the step says Saved. If you press Next with a complete choice that is not saved, it is saved first. Press Change repository to choose again, or Do not send to GitHub, the red outlined button, to turn it off.
3. Send it
When the migration is verified, the step after Result in Verify is Send to GitHub. It is a step of its own so it is not missed. The side list says Needs you until the code is sent, then Sent with the date, or Not connected if there is no GitHub connection (connect it in Settings). The same send is also on the Report step of Launch, for sending again after a final sync. On the step, press Send the code to GitHub. The tool puts all the files in one commit on the new branch and opens a pull request into the base branch. The step then says how many files were sent, how many changed, who sent them and when, with a link to the pull request.
- Send again, for example after a final sync, adds a new commit to the same branch and keeps the same pull request. Only files that changed are sent. If nothing changed, nothing is committed, and the card says so.
- A file the repository already has keeps the repository's whitespace and line endings. One that differs only in line endings, in spaces at the ends of lines or in blank lines at its end is not sent, so the pull request shows only real changes. One that changed is sent with the repository's line endings, so its diff shows the lines that changed, not every line.
- A file the repository once had and later deleted on purpose is left out, not added back. The card lists each one as "The repository deleted this on" a date, in a commit. Tick a file to send it anyway, then press Send again; untick it to leave it out of the next send, which also takes it off the migration's branch. A file the repository never had is sent as usual. The tool checks the history of up to 1,000 new files a send, and says how many it did not check.
- If a code file holds what looks like a key, the tool stops and names the file. Check it, then press Send anyway if it is fine.
- Every file or none. When any file the tool moved cannot be read back from the new site, nothing is sent, and the card says how many of how many, and names each one with why. Try again, and report a problem if they are still missing. Code in the site's own modules, such as
modules/website/public/, is read from the new site's export of each module, asinsites-cli modules pullreads it. - To review and take the code, merge the pull request on GitHub.
See or disconnect GitHub
Settings, in the menu on the left, shows whether GitHub is connected to the account you are working in, and to which organizations. Everyone in the account can open it. It also shows your own saved Teamwork key.
To stop the account sending code to an organization, an owner disconnects it:
- Open Settings and press Disconnect beside the organization, then confirm.
- No more code can be sent to it from this account. A migration that was set to send there asks for a new choice. Branches and pull requests already sent stay on GitHub.
- The Insites GitHub App stays installed on the organization until you remove it there. Follow the uninstall it on GitHub link the page then shows.
A migration moved from your Personal account into an agency keeps its choice only when the agency has connected the same organization itself. Otherwise the choice is cleared and the agency's owner connects the organization here first. Moving a migration into an agency.
Only an owner can disconnect. In your Personal account you are its owner. Operators and viewers see whether GitHub is connected, with no button. Disconnecting is recorded in Activity. Roles.
What the tool keeps
The tool keeps no GitHub key. Each time it sends, it asks GitHub for a short-lived permission for that one repository, with the least access it needs. Only making a new repository asks for more. No GitHub token is stored, written to a log, put on the migration or sent to your browser. The connection to an organization is removed after 180 days without use.
Each choice and each send is recorded in the migration's decisions, in Activity and in the technical report, with who did it and when.