Creating iFrame content using GitHub Pages

An option for securely running code on Mass.gov.

Organizations sometimes want to include JavaScript or other code directly on Mass.gov. Since that’s not allowed for security reasons, we support the option of embedding code in an iFrame, which lets you embed a page from another site into a Mass.gov page.

If you don’t have a host server for the code, we create a public repository for you on GitHub, and enable GitHub pages. It puts a simple web server in place for your code, and you can then embed the GitHub Pages URL in an iFrame that can be added to your Mass.gov pages.

Only front-end code can run in Mass.gov content using GitHub pages. No server-side code is allowed.

Terms of Service

Mass Digital provides the following terms of service, conditions and best practices for agencies to follow while using GitHub Pages for custom applications and code.

Please be advised these guidelines are still under review and are not complete.

Mass Digital responsibilities.

We will:

  • Set up a code repository for your agency in GitHub

  • Manage the assignment of GitHub users to your repository

  • Set the publishing source branch for your GitHub pages.

We will not:

  • Write or review code for an agency

  • Merge code changes for an agency

  • Provide instructions on how to use Github. You can learn this online from a number of sources.

We reserve the right to change policies regarding GitHub.

Repository Permissions

All agency repositories are set to PUBLIC, meaning your code is open sourced and accessible by anyone with a GitHub account. DO NOT put anything in your repository that should not be public (i.e. passwords, login information, personally identifiable information, etc.). This includes any internal state network information.

Agency responsibilities

  • You are responsible for the management and development of all code and merging of changes within your repository.

  • Notify Mass Digital when a person with access to your code base leaves so their access can be removed.

  • Anything embedded via iFrame must be:

◦ Accessible (should meet Web Content Accessibility Guidelines 2.0 standards. See Additional Helpful Resources below)

◦ Responsive (your application should look good on any device)

◦ Consistent with the Mayflower Design System

◦ Comply with privacy and security policies

Best Practices

At a minimum, you should have a develop branch and a master branch within your repository. We recommend you get your code working correctly in the develop branch, then merge those changes into the master branch. We have configured your GitHub repository to use the master branch as the published code. So make sure you merge changes from develop into master to be able to see them on your site.

Documentation of your project/code is critical to every repository. Please make sure you keep your README file up to date and that all your code is well documented for the next person working on your project. For more information, read Documenting your projects on GitHub.

Publishing your code in the Mass.gov content management system

To include your custom application hosted on the GitHub repository within Mass.gov content, you need to rework the URL:

  • Replace the first part of the URL in the repository. So https://github.com/massgov/Treasury/, for example, would become https://massgov.github.io/Treasury/

  • Look at the folder structure in GitHub and attach that to the end of the URL. For the example shown in the screenshot, the URL would become https://massgov.github.io/Treasury/vets/vettest3.html

Using flexible height iFrames

In most cases it makes sense for iFrames to use flexible height because the height they need to display without vertical scrolling within the iFrame can vary between desktop, tablet and mobile displays. When you embed the iFrame, there is an option to enable flexible height and there is a reference to a piece of code you need to add to your iFrame source to enable this. This code can be added to your github page to allow it to have flexible height.

Additional Helpful Resources

Was this article helpful?

Last updated