The Atlas Blog

GitHub Webhooks

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.

Managing Collaborators

Managing Collaborators

To use Atlas’s collaboration features you first need to have collaborators on a project. Click the “Project Settings” link in the top right corner when viewing your project.

Follow the Project Settings link to manage collaborators

Use the form to invite a collaborator via email address. If the email matches an Atlas account the user will immediately be able to see the project. If there is no corresponding account then an email will be sent inviting the person to sign up for Atlas.

Setting the permissions for a collaborator

When adding a collaborator there are two permission levels to choose from, Collaborator and Owner. A Collaborator will only be able to make edits to the project from within their own branch, not directly to master. As an Owner a user has the ability to accept or reject changes as well as edit the master branch directly.

To manage group members, visit the Group Settings page. You must be a group owner to add collaborators.

We will cover more aspects of collaboration in Atlas in future posts.

This blog is written by the O'Reilly Atlas team. Here, you'll find up-to-date information about new features and functionality in the Atlas platform.