π An "ORM" for storing data in a GitHub repository using GitHub Actions
Usage β’
FAQ
ActionRecord works by running JavaScript functions in the repository to decide how and where to store the provided raw data.
Including it should be as simple as using the action in your .github/workflows
file with the GITHUB_TOKEN
secret:
steps:
- uses: JasonEtco/action-record
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
This will tell ActionRecord to run a JavaScript file called /action-record/events/<EVENT>.js
, where EVENT
is the the event name that triggered the workflow.
These should be JavaScript files that export a function that takes one argument, an instance of the ActionRecord class:
module.exports = async action => {
// Do stuff
}
An example use-case is to store arbitrary data as issues, categorized by labels. For example, we can create a new issue with the label user
to store any new user that pushes to a repo. We do this by defining a user
model, and then using typical ORM methods in our specific event handler. ActionRecord will load all models from action-record/models
before running the event handler, and put them onto action.models
.
// action-record/models/user.js
module.exports = ({ Joi }) => ({
name: 'user',
schema: {
login: Joi.string().meta({ unique: true })
}
})
// action-record/events/push.js
module.exports = async action => {
await action.models.user.create({
login: action.context.payload.sender.login
})
}
This will create a new issue with a label user
:
Need to query your "database"? No problem! Like most ORMs, each model gets findOne
and findAll
methods. These take an object argument to do some basic filtering.
// action-record/events/push.js
module.exports = async action => {
await action.models.user.create({ login: 'JasonEtco' })
const record = await action.models.user.findOne({ login: 'JasonEtco' })
console.log(record)
// -> { login: 'JasonEtco', created_at: 1566405542797, action_record_id: '085aed5c-deac-4d57-bcd3-94fc10b9c50f', issue_number: 1 }
}
Models function similar to any other ORM; they require a name and a schema (here, using Joi). You can even define "hooks":
// action-record/models/user.js
module.exports = ({ Joi }) => ({
name: 'user'
// A Joi schema that will be run to validate any new records
schema: {
login: Joi.string()
},
hooks: {
beforeCreate: async candidateRecord => {},
afterCreate: async newRecord => {}
}
})
Here's a list of all of the available hooks, in the order in which they run:
beforeCreate
beforeValidate
afterValidate
beforeSave
afterSave
afterCreate
A common use-case might be to validate that a record doesn't already exist:
// action-record/models/user.js
module.exports = ({ Joi, github }) => ({
name: 'user'
// A Joi schema that will be run to validate any new records
schema: {
login: Joi.string()
},
hooks: {
async beforeCreate (candidateRecord) {
const existingRecord = await this.findOne({ login: candidateRecord.login })
if (existingRecord) {
throw new Error(`User with ${existingRecord.login} already exists!`)
}
},
}
})
steps:
- uses: JasonEtco/action-record
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
baseDir: action-record
Should I use this in producti-
No. This was made as an experiment - there are far too many reasons not to actually use this. But, if you choose to, awesome!
This is dumb. You shouldn't use GitHub or Actions as a datastore.
Yes. That isn't a question, but I don't disagree. The point of this is to show that we can, not that we should.