@jasonetco/action-record

ActionRecord

⚠️This is extremely WIP. Please don't use it or open issues just yet!⚠️

📑 An "ORM" for storing data in a GitHub repository using GitHub Actions
Usage • FAQ

Usage

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.

Event handlers

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:

Querying for data

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

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 => {}
  }
})

Available hooks

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!`)
      }
    },
  }
})

Options

steps:
  - uses: JasonEtco/action-record
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    with:
      baseDir: action-record

FAQ

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.