Skip to content

GitHub Apps: How to set up your local environment

Jump to bottom
Josh Smith edited this page Nov 26, 2017 · 1 revision

To work with GitHub integrations, our tests use mocks.

But when developing you'll likely want to actually call the real GitHub API.

For that, we need to do one major and a couple of minor things. We need to:

  1. Create a test GitHub App.
  2. Place some of your GitHub App's keys in your .env file in your code-corps-api directory.
  3. Place other keys in the config/environment.js file in code-corps-ember.
  4. Create at least one test repo to work with.
  5. Set up Ultrahook to receive webhooks locally.

Create a test GitHub App

If you're currently signed in to GitHub, the interface to create a new app is reachable from https://github.com/settings/apps/new.

To get there manually

  • Navigate to your profile settings
  • Click "Developer Settings" in the sidebar
  • Click "Github Apps" in the sidebar
  • Click the "New GitHub App" button

Information to fill out

Most of the fields here are optional, but the following fields are required:

  • Title: Since the title needs to be unique across GitHub, we recommend setting the value based on your GitHub username, such as code-corps-local-YOUR_USERNAME

  • Homepage URL: http://localhost:4200

Must match whichever address you use to access the code-corps-ember application when running ember s.

  • User authorization callback URL: http://localhost:4200/oauth/github

Must match the OAuth redirection route of the Ember application. You can dig through the router or search code-corps-ember/config/environment.js for ENV.github.redirectUri.

  • Setup URL: (leave blank)

May match the Ember route for integration setup. We haven't decided at the moment of writing; for now, leave it blank.

  • Webhook URL: https://localhost:4000/webhooks/github

Must match the API webhook route found in code-corps-api/web/router.ex

  • Webhooks secret: (leave blank)

May match a value set in the API in the future.

NOTE: These values may change in the future.

Permissions

At the moment of writing this, we make use of and require the following permissions:

  • Read & write

    • Repository administration
    • Issues
    • Pull requests
    • Organization members

  • Read-only

    • Commit statuses
    • Deployments
    • Repository contents

  • No access

    • Pages
    • Single file
    • Repository projects
    • Organization projects

Subscribe to events

Subscribe to all of the events available.

Where can this app be installed?

For your own testing and development, you should be fine with picking Only on this account. However, there may be specific test cases or features where you might be interested in doing more.

Just consider Only on this account the default for now.

Submit

Once you fill out the information above, everything else you can fill out however you please and press "Create GitHub App".

Keys

Once you submit, you'll be asked to generate your private key.

Before you do that, scroll to the bottom of the page and take note of your "OAuth Credentials":

  • Client ID
  • Client secret

You'll use both of these soon.

Under the UI to upload a logo, you should also take note of the ID field. Take note of that to.

Now hit Generate private key to get a .pem file.

You now have a .pem file, a client id and a secret key. It's time for the next step.

Set up environment for code-corps-api

Go to your code-corps-api project folder. If you've used environment variables working on this project before, then you already have an .env file in this folder. If you have not, you need to create it, and the quickest way to do that is to use our .env.example file, which is part of the github repo, by copying it over:

cp .env.example .env

If you have it, or you have just created it, open it up in your editor of choice. To it, add the following 3 values:

export GITHUB_APP_CLIENT_ID=<your app client id>
export GITHUB_APP_CLIENT_SECRET=<your app client secret>
export GITHUB_APP_ID=<your app id>
export GITHUB_APP_PEM=<base64 encoded contents of your pem file>

How to get the .pem file contents

That .pem file you downloaded? Open it in your editor of choice. Copy all of its contents to your clipboard.

Now go to https://www.base64encode.org/ and paste it into the first text area. Hit encode and the API you get is the base64 content you need to set as your GITHUB_APP_PEM.

Before you run the API with mix phoenix.server, you still need to source .env from the console, so the keys will actually get added to your environment. You'll need to source .env any time you run your app.

Your code-corps-api environment is now fully set up!

Setting up code-corps-ember environment.

This one is much simpler.

Copy the following values from your GitHub App into the following keys in the development environment of code-corps-ember/config/environment.js:

  • Public link: ENV.github.appUrl
  • ID: ENV.github.appId
  • Client ID: ENV.github.clientId

Now you can run ember s with your new values.

Setting up a test repo

You should create a test GitHub repository for your own testing purposes.

Go to your repository list and create a new GitHub repository or just navigate to https://github.com/new.

The repo's contents can be completely blank since right now we're only dealing with installing the app, and then later creating issues and comments.

Setting up webhooks with ultrahook

If you've used ultrahook before, then you already have an API key and it's set up. Now all you need to do is, on your application setting page, set the webhook url to http://github.<yournamespace>.ultrahook.com.

If you haven't used it before, go to http://www.ultrahook.com/register. Fill out the information and follow the instructions.

Remember to store your Ultrahook API key. There is no way to log back in and get another one.

You'll get instructions on how to put your API key into ~/.ultrahook and how to install the ultrahook gem. Do both:

echo "api_key: <your api key>" > ~/.ultrahook
gem install ultrahook

You should now be ready to start receiving webhooks.

Getting it all running

Start everything

  • In your first console tab, go to code-corps-ember and run ember s
  • In your second console tab, go to code-corps-api and run mix phoenix.server
  • In your third console tab, go to code-corps-api and run ultrahook github http://api.lvh.me:4000/webhooks/github

Use it

  • Navigate your browser to the Ember app at https://localhost:4200
  • Sign in as the seeded organization owning user provided by code-corps-api. Right now, this is:
    • email: owner@codecorps.org
    • password: password
  • If this is a freshly seeded development database, you have not connected your user account with GitHub yet. To do so, go to your user profile settings or navigate straight to http://localhost:4200/settings/integrations and connect your account.
  • Once connected with your account, you can connect a project to your new GitHub App.

Questions? Problems?

Please open an issue and we'll help you out.

Clone this wiki locally