Skip to content

Generating GIT_REPO urls

Jump to bottom
Jen Weber edited this page Apr 3, 2020 · 1 revision

By default, Card data is saved to a private GitHub repository that you create. In order to make commits, the Hub needs to know which repo and the authentication information. This guide will help you compose the GIT_REPO environment variable that serves this purpose.

Steps

  1. Create a private repository on GitHub
  2. Create a machine user account on GitHub and grant only the limited permissions to the specific repository that you want the Hub to write to.
  3. Log in as the machine user. Go to the Personal access tokens section of the settings, in the "Developer settings" section, and click on the "Generate new token" button.
  4. On the following page, enter a note so you remember this token is used with the Cardstack Hub, and click on the "repo" checkbox (Full control of private repositories). No other permissions are required. Then click on "Generate token" at the bottom of the page. Make sure to copy the token now as it will not be displayed again. See this image for an example.
  5. Once you have the token, you can now create the GIT_REPO url that is passed to the remoteUrl attribute of the git realm card. It follows the format https://<username>:<token>@github.com/<org>/<reponame>.git For example, if you generated the token abc123, and your GitHub repository is https://github.com/cardstack/cardstack, and your machine username is cardstack-deploy-user, then your remoteUrl attribute would be https://cardstack-deploy-user:abc123@github.com/cardstack/cardstack.git

Frequently asked questions

Why do we use this structure for communicating with GitHub?

The Cardstack Hub can only connect to remote git repositories over http or https, as isomorphic git doesn't yet support ssh transport protocol. For this reason, you will need to generate a personal access token to create a git https url to configure the hub with.

What restrictions can I apply to personal access tokens?

Personal access tokens have broad permissions - notably, you cannot create an access token that only works with a single repository, there is no equivalent of the ssh "deploy key" functionality with GitHub right now. Due to the broad permissions, it's strongly recommended to create a machine user account on GitHub and grant only the limited permissions to the specific repository that you want the Hub to write to.

Clone this wiki locally