GitHub repository

GitHub repository#

Each student is provided with their IRP GitHub respository at the start of the module. Each IRP repository is private - apart from the IRP-related Imperial College staff, only you and your supervisors have access to it.

Warning

Please note that not all supervisors have GitHub accounts, so some may not be able to access your repository directly. If your supervisor does have a GitHub account, but they don’t have access to it, please let us know and we will add them.

We cannot grant admin access to students in their IRP repositories. Therefore, if additional people (e.g. co-supervisors or collaborators) need access, you may ask us to add them. All access must be requested through us - you cannot manage repository permissions yourself.

After the IRP ends, if you wish to share your project publicly, we cannot change your IRP repository from private to public. Instead, we recommend that you create a new public repository and copy the relevant content into it. However, please be extremely careful before sharing any project materials publicly - especially if your IRP is external or covered by a Non-Disclosure Agreement (NDA). In such cases, public release of the content may breach confidentiality obligations. If you’re unsure, consult your supervisor.

Submitting Your Written Reports#

File Requirements and Location#

Submit your written reports (project plan and final report) by committing and pushing them to the deliverables/ directory in your repository. Each report must follow the strict naming convention specified in the deliverables/README.md, using your Imperial username (not your GitHub username).

Please remember that, according to the IRP-specific academic integrity rules and expectations, the project plan and final report must be version controlled and committed to the repository. In addition to the PDFs, the source files, such as the .tex, .bib, and figure files for LaTeX, or the .docx file for Word, must be committed to the repository.

Automatic Validation Process - GitHub Actions#

Upon submission, GitHub Actions workflows will automatically validate your files:

  • project-plan workflow: Validates the project plan submission

  • final-report workflow: Validates the final report submission

These workflows check that:

  • Files are in the correct deliverables/ directory location

  • Filenames match the required format exactly

  • File sizes are within permitted limits

Troubleshooting Failed Submissions#

Important: The GitHub Actions workflows are designed to fail until you submit the actual reports. This is expected behavior, and you should not create placeholder files to make the workflows pass. For example, the final-report workflow will fail until you submit your final report (for most students, this workflow will be failing until the last few days before the final IRP deadline in August/September)

If your submission doesn’t meet the requirements after uploading your actual report, the workflow will fail. To identify and fix issues:

  • Navigate to the “Actions” tab in your GitHub repository

  • Review the failure logs for specific error details

  • Correct any issues, commit the changes, and push them to the repository

  • Ensure the relevant workflow passes before the submission deadline

PDF Display Issues#

After uploading your written report to GitHub, you may notice that the PDF doesn’t display properly when viewed directly in the GitHub web interface. This is a common browser rendering issue and not a problem with your submission. To verify your PDF is fine, simply download it from GitHub and open it locally – if it displays correctly when downloaded, your submission is valid.

Project Title (title.toml)#

Your project title must be kept up to date. You are responsible for editing the title/title.toml file whenever your title changes.

We regularly collect project titles from all repositories. Title update requests via email will not be accepted. It is your responsibility to ensure the information in title.toml is accurate at all times. Each time you update the file, a GitHub Actions workflow (title) checks that the file exists and is correctly formatted, i.e. it is readable by us.

logbook.md#

As outlined in best practice expectations, you are required to regularly meet with your supervisors and document all meetings in logbook/logbook.md file. For further information, see Academic Integrity and Misconduct. After each push to the repository, a GitHub Actions workflow (logbook) ensures that the logbook.md file exists on the right path.

Repository Inactivity Warnings#

Automated workflows are scheduled to regularly monitor overall repository activity. If no commits have been made to any branch or if the logbook has not been updated on the main branch over a period of time, a warning will be raised as an issue in the repository.

Warning

If you receive an inactivity warning, you do not need to take any action retrospectively. However, please accept this as a reminder that your are expected to make regular progress on your IRP and to keep your logbook up to date.

Using and Modifying Your Repository#

Your repository includes some pre-created files and directories. These must not be renamed, deleted, or altered. Specifically, you must not:

  • Modify or delete existing GitHub Actions workflows

  • Rename, delete, or move the deliverables/, logbook/, or title/ directories

However, you may (and must) add your code, report source files, documentation, or workflows, and other resources needed for your project. You can also modify the contents of README.md in the root directory - you are free to replace or repurpose this file entirely for your own documentation or instructions

Your project should exist independently and alongside the pre-created files. While you should not alter those files, you are encouraged to build your project in whatever way best supports your work, as long as the deliverables and validations remain intact.

Large files#

Large files such as raw or processed data files, simulation results, and high-resolution visualisation outputs should not be stored directly in the repository. These can be uploaded to your university-provided OneDrive, and a link to the relevant folder can be included in the repository README.md. However, all code required to generate these outputs must be included in the repository to preserve the reproducibility and transparency of your work.

Contents