Atlas is built on Git; each of your projects in Atlas is a repository. And if you’re working on an open source project tracked by Git, you probably use GitHub.

We are very excited to announce that you can now automatically trigger builds in an Atlas project when you push to a connected public GitHub repository.

Getting your Atlas project ready

To start you’ll need an Atlas account and project. When you are signed into Atlas, go to the User Settings page and copy your API Token. We will use it to set up the webhook on GitHub.

Setting up GitHub

Now from your public project on GitHub, click the Settings link on the right side of the page and then click Webhooks & Services. Next click the Add webhook button; you’ll be prompted for your GitHub password. The resulting screen should look something like the following:

Fill in Payload URL with https://atlas.oreilly.com/api/hooks/github/USERNAME, replacing USERNAME with your Atlas username. In the above screenshot, the username is the same on both GitHub and Atlas, but this may not be the case for you.

Pingback URL

If you would like to be pinged each time builds are completed via a webhook, append ?pingback_url= to the Payloud URL and enter in an address with http(s):// that can receive a POST request.

Entering your Atlas API Token

Paste the Atlas API Token you copied earlier into the Secret text field. Leave Just the push event selected and click Add webhook.

Now Atlas will be notified every time a push is made to the GitHub project.

Setting up the atlas.json file

Now we need to specify in GitHub what Atlas project we want to sync with. To do this, add a "name" value to the atlas.json file in your GitHub project that contains the relative path to the corresponding Atlas project:

{
	"name": "sklise/introduction-to-sinatra",
	"files": ["readme.md"],
	"branches": ["master"],
	"export_formats": ["html","pdf"]
}

There are a couple additional optional settings you can add to atlas.json for webhooks:

  • “branches”: optional array. If present, only pushes to the whitelisted branches will trigger builds. If absent, every branch will trigger a build.
  • “export_formats”: optional array of formats to build on each push. If absent or an empty array, all current formats will be built. Otherwise only the listed formats will be built.

GitHub and Atlas In Sync

In Atlas builds are displayed next to your content. Now that you can trigger builds by pushing to GitHub, we want to make sure that the content of the builds matches the files listed beside the builds. If you have a GitHub webhook set up, when you push to GitHub, the same process that builds your content in Atlas will also push your repo from GitHub to Atlas. This action will happen with a git push --force.

Protected Master Branch

Atlas by default prevents git push --force on the master branch of all projects which may prevent Github and Atlas from staying in sync. To unprotect the master branch, go to the Project Settings of your project and click the button under Unprotect Master Branch. You will only have to do this once.