@cardstack/git
v0.14.38-patch.0
Published
Git data source plugin for @cardstack/hub.
Downloads
923
Readme
@cardstack/git
This is a Cardstack data source plugin for reading and writing to Git. Always have access to see how data has changed across time.
Features:
- Just like using git for code, your data is versioned. A deleted or changed record can be retrieved!
- Card data can be saved to either local or remote git repositories
- Data can be stored in either the same repository as the project code, or a separate repository
- Data for multiple projects can be saved to the same repository
Installing in a Cardstack project
To use a git as a data source, include @cardstack/git
in the devDependencies
of cardhost/package.json
yarn add --dev @cardstack/git
yarn install
See the "Troubleshooting" section of this README if you encounter any issues installing.
Configuration
Data plugins are configured in cardhost/data-sources
.
The only required configuration is to set either repo
or remote
.
| Parameter | Type | Description |
|-----------|------|-------------|
| remote
| object | Use a remote git repository, such as one hosted on Github. The object should contain url
and privateKey
with type string. Example: remote: { url: 'some-url', privateKey: process.env.GIT_PRIVATE_KEY}
|
| repo
| string | The path to a local git repository that already exists on disk, and has an initial commit |
| branchPrefix
| string | optional - a prefix to prepend to the git branch when saving data. This is especially useful when you are storing data in the same repository as your project, or you have one repository that holds code for multiple projects. Example: if you set basePath: 'cs-'
, data will be stored at cs-master
|
| basePath
| string | optional - specify the directory within a repository where the data should be stored. Example: if you set basePath
to my/base
and you save an article
Card, data will be stored at my/base/contents/articles/
|
You can set variables such as process.env.GIT_PRIVATE_KEY
from the command line. For the example below, substitute your own path to the key:
GIT_PRIVATE_KEY="your private key here"
Example configuration
For example, the configuration below is set in cardhost/data-sources/default.js
.
This config creates a @cardstack/git
data source named default
and configures it
as the Hub's default-data-source
.
Now, if a Card does not have its own data source defined, it will use git.
let sources = [
{
type: 'plugin-configs',
id: '@cardstack/hub',
attributes: {
'plugin-config': {
'application-card': { type: 'app-cards', id: 'cardhost' }
}
},
relationships: {
'default-data-source': {
data: { type: 'data-sources', id: 'default' }
}
}
},
{
type: 'data-sources',
id: 'default',
attributes: {
'source-type': '@cardstack/git',
params: {
repo: '/path/to/some-git-repo'
}
}
}
];
module.exports = sources;
Learn more
To learn more about how it can be used in your project, see the Cardstack Guides about git.
Troubleshooting
Windows installation - Building native nodegit dep
Windows users should install windows-build-tools,
which are needed in order to build the nodegit
dependency.
OSX installation - Building native nodegit dep
You need the latest Xcode and you need to manually tell it to get the latest CLI tools via
sudo xcode-select --install
Merely upgrading Xcode will still leave you broken and frustrated.
I cloned and built nodegit in its own repo, and then used yarn link
. This seems to function as insurance against yarn
deciding to rebuild it from scratch (which takes a long time).
Mac OS X Mojave users beware: nodegit does not appear to be compatible with the newer style OpenSSH keys that are generated by default from ssh-keygen
. When generating ssh keys make sure to specify -m PEM
in the ssh-keygen
command in order to generate the older style PEM keypair. If you encounter the error:
Error: Failed to authenticate SSH session: Unable to extract public key from private key.
Then it is likely because you are generating the newer style OpenSSH keypair.
The older PEM style private keys (that are compatible with nodegit) are identifable by having a private key preamble that begins with:
-----BEGIN RSA PRIVATE KEY-----
More information is detailed here: https://github.com/nodegit/nodegit/issues/1606.
In order to use the private key as an env var in TravisCI you will need to replace the newlines in the private key. This issue describes this more in detail: https://github.com/travis-ci/travis-ci/issues/7715#issuecomment-362536708. You can use the following perl script to convert newlines into \n
from the private key file and write to stdout:
$ perl -p -e 's/\n/\\n/' ~/.ssh/my-private-key_id_rsa
Then in Travis you can specify the env var in the following in manner within the Travis env var text field for the newlines to be converted correctly. Note that the "
and '
characters are very critical:
"$(echo -e '-----BEGIN RSA PRIVATE KEY-----\nMKOQ1zYTmd\nzkRpTFq4xu\n-----END RSA PRIVATE KEY-----\n')"