First please take a look at our code of conduct if you wish to contribute to OTTR.
OTTR relies on R Markdown and GitHub actions. You do not need to be an expert about either R Markdown or GitHub to get started using OTTR, as we will guide you through the process! However, we recommend reading up a bit about both to better understand how they work in general before diving in to our guide. These readings only take a few minutes.
Please check out these resources if you are not familiar with R Markdown:
If you aren’t familiar with markdown this is a nice introduction.
For information on R Markdown (a variation of a markdown file that we use here): RStudio has their lessons here.
If you are not familiar with Git and GitHub, we recommend going through these chapters from our Reproducibility courses for a quick orientation:
We have two recommended ways of writing content based on your comfort and interest level in using Git and GitHub:
If you choose to use our OTTR Advanced guidance, you will need a method for working with git.
If you do not have a method of working with Git already it is recommended you use a Git client to help you manage your branches more easily. Install GitKraken for a handy way to manage your course locally.
In the upper right of the landing page for this repository, click the green
Use this template button and follow the steps to set up your course’s GitHub repository.
*If you want to use OTTR Website or a different spin off go to that respective repository:
publicfor all GitHub actions to work
In particular, the rendered preview on pull requests won’t work, but you can alternatively preview the content by re-rendering locally if you want to keep your course private. We will cover this later.
*You can skip this step if your course is in the
The GitHub actions in this repository need permissions to fully function. To this end, you need to add the
jhudsl-robot as a collaborator on your repository with write permissions.
In your repository, go to your
Collaborators & Teams and click on
Add people. In the pop up window, search for and add
write option then click
Add jhudsl-robot to this repository.
If you have a personal repository, or a organization that hasn’t used Github Actions before, you’ll also need to check that workflow actions have been enabled.
Go to the
Settings and then
Actions Make sure that you’ve: 1. Given
read and write permissions and … 2. have also checked
Allow GitHub Actions to create and approve pull requests.
The OTTR robots need permissions to run some of the actions.
To give them permission for all the actions, you need to set a GitHub secret we will call
GH_PAT. Go to
Secrets and variables on the left side menu >
Actions. On this page, scroll down to
Repository secrets. Read more about GitHub secrets here if you have general questions.
If you have organization admin privileges and plan on making multiple courses with OTTR, you can set
GH_PAT as an organization secret so you don’t have to do this again. You only need to do this once as an organization (if this course is under
jhudsl you don’t need to do this step).
New repository secret/
New organization secretbutton.
Nameyou must use
Secret: Create a personal access token following these instructions to create a “Classic” token (and not a “Fine-grained token”).
Select scopes, check both
Your GitHub actions should all be able to run smoothly now.
In your repository, go to
Source, pick the drop down menu and pick
Enforce HTTPSat the bottom of this page.
The URL for your material will be your
main github pages url +
your OTTR repository name and it will be displayed underneath your
Pages if you aren’t sure.
By default, Github pages is sent to a url that looks like
username is either your individual user name or your organization’s name. However, you can set your GitHub pages URL to be custom (like we have in this example here -
jhudatascience.org). So it is likely your pages URL is something like
For more information about GitHub pages we recommend you reference the GitHub documentation here.
* Warning: if you go to your pages url right now (before you’ve pushed any file changes) you might see a 404 error because nothing has been triggered to be rendered. You can check your url pages after you file your first pull request (which we will guide you through in the next section).
* Don’t set these settings right away! Wait a few minutes after starting your repository.
Branches and click
Add rule. This is only possible if you have GitHub Pro, Team, or Enterprise access. We recommend seeing if your organization can give you access if you do not already have access. To get this access through your organization, you will need to transfer ownership of your repo to your organization. See here about how to do this.
Branch name pattern, put
Protect the main branch:
Then check the box that says
Require pull requests before merging.
* Note that if the user whose personal access token does not have admin privileges for step
6. Set up your GitHub personal access token, then you will need to skip this setting.
Make sure branches are updated:
- Check the box that says
Require status checks to pass before merging. - Underneath this also check the box that says
Require branches to be up to date before merging.
After setting up these new branch items, click
This original course template: https://github.com/jhudsl/OTTR_Template is always a work in progress. We are working on adding more features and smoothing out bugs as we go. This is also why your feedback is greatly appreciated.
When updates are made to files that aren’t specific to the course content but instead run checks and other processes in the original repository, pull requests are filed automatically to any downstream repositories made from this template.
To enroll in these automatic update pull requests, the new course’s repository name will need to be added to this file in the original template
.github/sync.ymlof the OTTR template repository you created your repository from:
#NEW REPO HERE#, being careful to indent the same amount as the other repositories listed.
Create a new branch for this commit and start a pull request.Name the branch what you like.
Add new repository to sync
Create Pull Request
@cansavvyas a reviewer.
If your new course doesn’t need some of the functionality of these files or you find the automatic updates bothersome, you can feel free to use this guide to tailor which files you want updates for. If you have any questions about the implications of any of these updates or files, please tag
Again we have two recommended ways of writing content based on your comfort and interest level in using Git and GitHub:
Jump to OTTR Entry Level instructions here Jump to OTTR Advanced instructions here
Now you are ready to start writing content!