publiccode.yml Pusher

Purpose

The intention of this project is to provide Code for America brigade members who are not programmers a convenient and easy way to commit a civic tech schema file to the Github repos of the projects they are involved in. The intended user is a project or product manager who has write access to repos of projects they manage but who does not feel comfortable pulling the project onto their local machine, manually creating a new data file, committing it to a new branch, and then opening a pull request for their changes. We have settled on publiccode.yml for our schema format.

Scope

As much as possible, the code should run entirely in the browser, with minimal need for a backend. The form targets Github, and no other Git hosting site. The plan for now is to deploy to Github pages with a handler for the auth token on Google Cloud Functions.

We have adopted and adapted the official publiccode-editor. It's a React + Redux app, which makes the development setup of this project rather more complex, but hopefully the switch will pay off in saving us work that has already been done by the creator's of publiccode-editor.

Development

NOTE: to make sure the servers get the right config, environment variable NODE_ENV=development

First, install the dependencies:

npm install

There's a development server to stand in for the Cloud Functions runtime. It's entire purpose in life is to receive the code that the frontend gets from GitHub and exchange it for an access_token. We need a server-side function because we must keep the GitHub client_secret private. The token server will look for a couple of environment variables

GH_CLIENT_ID
GH_CLIENT_SECRET

Reach out to someone else on the project for these, or set up your own for your own app.

To run the server locally with nodemon:

npm start

The backend is served at http://localhost:5000

The above development server does not serve the frontend.

To run the system locally:

• client/src/app/utils/GithubClient.js: update TOKEN_SERVER to your local server (typically http://localhost:5000/token)
• client/src/app/components/LoginForm.js: update CLIENT_ID (as of your CLIENT_ID of your github oauth app that you need to create)

The frontend is now a React app

I appropriated it from Italia, who maintain publiccode.yml

If you've worked with React before, you probably know the drill. Navigate into the client/ folder and do:

npm i

Then to run the development server, do:

npm start

The frontend app is served at localhost:3000.

Testing

We are still reviewing what the state of the tests is since we forked the project (and it was at some point switched to the React app).

The tests on the backend use Mocha, Sinon, proxyquire and Chai. We haven't run them since we took on the project, but they should all still work as not much changed on token server.

Deployment

The frontend is deployed to GitHub pages

Just push to the master branch and .github/workflows/publish-site.yaml will automatically update the gh-pages branch

The backend is deployed on Google Cloud Platform

You'll need to install and configure the Google Cloud SDK. Check it out and get all the hottest tips here

Once you've got the thing installed, to push the code to GCP do:

gcloud functions deploy token --source='src/http/token'

But actually I have courteously aliased that command for you to:

npm run deploy

Yer gonna have to set the environment variables GH_CLIENT_ID and GH_CLIENT_SECRET on the GCP function to make it work.