Skip to content

Latest commit

 

History

History
102 lines (77 loc) · 7.31 KB

PublishingGuide.md

File metadata and controls

102 lines (77 loc) · 7.31 KB

Using Travis to automate publishing of your report to GitHub Pages

Travis-CI enables you to automate RepoSense report generation and publish the report online to GitHub Pages for free.

  1. Fork publish-RepoSense repository using this link
  2. Follow this section to generate a personal access token or deploy key on GitHub for report publishing
  3. Sign up and login to Travis-CI
  4. Go to your account, click on Sync account to fetch all your repositories into Travis-CI
  5. Go to your publish-RepoSense fork in Travis-CI, under Current tab click on Activate repository
  6. In the same page, click on More options on the right then access Settings Travis-CI Dashboard
  7. Under Environment Variables, name a variable as GITHUB_TOKEN or GITHUB_DEPLOY_KEY depending on your earlier choice and paste the content that was copied earlier to its value field; then click Add
    Ensure that the Display value in build log is switched off for security reasons Travis-CI Environment Variable
  8. Edit run.sh, repo-config.csv and author-config.csv to customize the command line parameters or repositories to be analyzed
    Read our User Guide for more information
  9. To access your site, go to the settings of your fork in GitHub, under GitHub Pages section, look for Your site is published at [LINK]
    It should look something like https://[YOUR_GITHUB_ID].github.io/publish-RepoSense
    GitHub Setting

The changes made to the configuration files should trigger Travis-CI to generate your report. Otherwise, follow the next section to manually trigger a build.

It takes a few minutes for report generation. Meanwhile, you can monitor the progress live at Travis-CI's Builds.
Try accessing your site again when a green tick appears beside your fork.

Granting write-access to RepoSense for publishing

We recommmend use of personal access token for ease of setup and deploy key for enhanced security.

If you wish to use personal access token:
  1. Follow this guide and give only public_repo permission
  2. Copy the token for later use
If you wish to use deploy key:

For Windows users, ssh-keygen and base64 are accessible using Git Bash.

  1. Use ssh-keygen to create a public/private key pair without a passphrase
    i.e. ssh-keygen -t ecdsa -b 521 -f id_reposense -q -N ""
  2. Go to the deploy key settings of your publish-RepoSense fork and create a new deploy key with the contents of id_reposense.pub
  3. Copy the base64 encoded content of the private key for later use
    i.e. cat id_reposense | base64 -w 0

Keeping your site up-to-date with your code contribution

Travis-CI offers Cron Jobs in intervals of daily, weekly or monthly.

  1. Login to Travis-CI
  2. Go to your fork in Travis-CI, click on More options on the right then access Settings
  3. Under Cron Jobs, choose master for Branch, Always run for Options and pick an Interval of your choice;
    then click Add Travis-CI Cron

Alternatively, you can manually trigger an update.

  1. Go to your fork in Travis-CI, click on More options on the right then Trigger build
  2. In the pop up, click Trigger custom build

Specifying which version of RepoSense to use

As RepoSense is being actively developed, its master branch is frequently updated with new features and fixes.
For stablility or familiarity, you may want to use the release.

Use our latest release (Stable)

You can find the changelog of latest release here.

Edit line 10 of run.sh to use --release. 

10   ./get-reposense.py --release

Use our master branch (Beta)

You can find the list of commits to master branch here and planned features/fixes here.

Edit line 10 of run.sh to use --master. 

10   ./get-reposense.py --master

Use a specific version of release

Be sure to read and understand all breaking changes and bugs before proceeding.

Edit line 10 of run.sh to use --tag TAG, where TAG is the target version of release. 

10   ./get-reposense.py --tag v1.6.1

Managing your configuration files with the help of collaborators

If you use RepoSense to monitor a large number of collaborators, it may be more systematic to have them update their git configurations into your fork using pull-requests.

To ensure that their pull-requests are correct, we can use Netlify to preview how the changes would look like in production, before deploying them into GitHub Pages.

  1. Sign up and login to Netlify
  2. Use this link to create a new site
  3. Select GitHub as your Git provider and authorize Netlify in the pop up if prompted
  4. If this is your first time using Netlify, pick publish-RepoSense when prompted to install Netlify;
    Otherwise, choose publish-RepoSense when prompted to link a repository
    If you can't find your fork, then Netlify may only have access to selective repositories
    Click on the link in Can't see your repo here? Configure the Netlify app on GitHub to give Netlify access to your fork
  5. In the next page, leave master as the Branch to deploy, enter pip install requests && ./run.sh for Build command and reposense-report for Publish directory
  6. To save, click on Deploy site
  7. To test, go to an open pull-request, scroll down and in All checks have passed, click on Details beside deploy/netlify — Deploy preview ready!, and the report should open in a new tab Netlify Preview