Sharing the "OSS Publishing Tutorial" Created by ROUTE06, Inc.

Hey Devs!

Recently, ROUTE06, Inc. has made two products, Giselle and Liam, open-source.

• https://github.com/giselles-ai/giselle
• https://github.com/liam-hq/liam

In this article, I'll share the "OSS Publishing Tutorial" that ROUTE06, Inc.'s OSS Promotion Office created and used when making these products open-source. Some internal links and references have been omitted.

👉 ROUTE06, Inc.'s OSS Promotion Office functions as an Open Source Program Office (OSPO), responsible for promoting OSS utilization, managing risks, supporting community contributions, and advancing the open-sourcing of internal products and projects.

• OSS Publishing Tutorial
  • 1. Preparation
  • 2. Repository Setup
    • 2-1. Setup Items
      • Column: What to write in [INSERT CONTACT EMAIL]?
    • 2-2. Create a Slack channel #gh-*
  • 3. Pre-Publishing Review
    • 3-1. Conduct a Security Review
    • 3-2. Confirm Compliance
    • 3-3. Obtain Internal Approval for OSS Publishing
  • 4. Repository Publishing
    • 4-1. Publish the Repository
    • 4-2. Conduct a Post-Publishing Review by the OSS Promotion Office
• Conclusion
• Supplement: About Giselle and Liam as OSS

OSS Publishing Tutorial

This is a tutorial on how to publish an OSS repository on GitHub.

💡 The OSS Promotion Office is available to consult on topics like license selection and other aspects.

1. Preparation

1. Decide which GitHub organization will host the repository
   • Choose whether to create the repository under https://github.com/route06inc or another organization¹
2. Decide the repository name
   • Choose a name for the repository under the organization
3. Decide when to make the repository public
   • Typically, start as Private and switch to Public when preparations are complete
   • If everything is ready, create it as Public from the beginning
4. Agree to enable all repository features except for Wikis
   • Issues, Pull requests, Discussions, Projects
   • Note: To encourage external contributions, this is the default policy
5. Decide whether to use English, Japanese, or both in various parts of the repository
   • Repository description
   • Issues, Pull Requests, Discussions, Projects
     • Title, Content, Comments
   • Source code comments
   • Git commit messages
   • Documentation
     • README.md, LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md
       • English is required, Japanese is optional. Both are allowed
     • Other text files
   • Note: Decide within the limits of what won't hinder development. Add this later to CONTRIBUTING.md
6. Decide the name of the private repository for internal communication
   • Create a private repository for purposes like the following. For example, route06/*-internal
     • Medium- to long-term planning
     • Discussions about vulnerabilities not yet ready for disclosure
     • Discussions involving confidential or collaborator-only² information
     • Others
   • Use public repositories whenever possible to ensure transparency. For example:
     • Feature proposals
     • Bug reports
     • General Q&A
     • Code reviews
     • Documentation updates
7. Decide on the repository's operation policy immediately after publishing
   • While it's unlikely there will be too many contributions right after publishing, set some guidelines. For example:
     • Keep operations light at the start
     • When an Issue, Pull Request, or Discussion from a Contributor comes in, ⚪︎⚪︎ responds to it as needed
     • Establish triage policies when contributions increase

2. Repository Setup

2-1. Setup Items

Create a repository in the organization decided in "1. Preparation" and proceed with the setup. All items are required unless otherwise discussed.

Item	Notes	Official Documentation
Create the repository and invite members	Available to use route06inc/template as a template	Link
Enable Issues, Discussions, Projects, and disable Wiki
Set the Description
Configure Topics		Link
Create README.md		Link
Create LICENSE	Included in route06inc/template	Link
Create issue templates	Included in route06inc/template	Link
Create pull request templates	Included in route06inc/template	Link
Create CONTRIBUTING.md	Included in route06inc/template	Link
Create SECURITY.md	Included in route06inc/template	Link
Create CODE_OF_CONDUCT.md	Included in route06inc/template	Link
Configure automatic deletion of merged branches	Enable "Automatically delete head branches"	Link
Protect the default branch	Define and configure rulesets	Link
Enable Dependabot Alerts	Detect vulnerable dependencies	Link
Enable GitHub Advanced Security (GHAS)	Always enabled for public repositories	Link
Configure CodeQL	Part of GHAS for detecting vulnerabilities. GitHub Actions workflow included in route06inc/template, so no additional setup required3.	Link
Make Dependency Review a required status before PR merges	A GHAS feature to catch vulnerable dependencies before PR merges. GitHub Actions workflow included in route06inc/template.	Link
Enable Secret scanning and Push protection	A GHAS feature to detect secrets in code and block new pushes	Link
Create CODEOWNERS (optional)		Link

Column: What to write in [INSERT CONTACT EMAIL]?

In templates like CODE_OF_CONDUCT.md and SECURITY.md, replace [INSERT CONTACT EMAIL] as follows:

If you want to use separate email addresses for each purpose:

• [e-mail]
  • Specify in CODE_OF_CONDUCT.md
• [e-mail]
  • Specify in SECURITY.md

If you want a single email address for all community inquiries:

• Example 1: [e-mail]
• Example 2: [e-mail]

2-2. Create a Slack channel #gh-*

💡 At ROUTE06, Inc., creating a #gh-* Slack channel for GitHub repository notifications is encouraged.

Once the channel is created, run the following command in it. Replace ORG/REPO as needed.

/github subscribe ORG/REPO issues, pulls, commits, releases, deployments, reviews, comments, discussions

This will enable notifications. Check the configuration with /github subscribe list features.

By default, notifications are posted in threads. Disable this by following these steps:

1. Run /github settings in the channel
2. Click Disable under "Disable threading for Pull Request and Issue notifications"

ref: https://github.com/integrations/slack/issues/1500#issuecomment-1335564029

3. Pre-Publishing Review

3-1. Conduct a Security Review

• Verify that the SECURITY.md file is added to the repository and that it clearly outlines the security policy and vulnerability reporting procedure
• Ensure that the following GHAS features are enabled
  • Code scanning (CodeQL)
    • Confirm the .github/workflows/codeql.yml commit
  • Secret scanning and Push protection
• Confirm that Dependabot Alerts is enabled
• Ensure that no internal information is hardcoded in the repository's source code
  • Example: Preventing non-company email addresses from being registered as a safeguard
• Confirm there are no internal links in the repository's source code or commit messages
  • Example: Slack URLs, internal private repository URLs, issue numbers starting with #, etc.
  • If such links exist, they do not need to be erased from history with git rebase. Just ensure they are not included going forward
• Verify that no proprietary names appear in the repository's source code or commit messages
  • Example: $ git log -p | grep -E '(◯◯|□□|△△)'
• Use full commit hashes for third-party GitHub Actions version specifications (optional)
  • Example: - uses: owner/action-name@26968a09c0ea4f3e233fdddbafd1166051a095f6 # v1.0.0

3-2. Confirm Compliance

• Verify licensing
  • Ensure the LICENSE file is added to the repository and that the selected license applies appropriately to the source code without infringing on third-party rights
  • Confirm compatibility between the repository's license and the licenses of dependent libraries
  • Reference:
    • How We Started Continuous OSS License Monitoring with License Finder - DEV Community
• Check export regulations
  • Confirm that the project does not include technologies subject to export regulations

3-3. Obtain Internal Approval for OSS Publishing

This step requires that you first decide on a license for your project. Handle this as soon as the license is finalized.

4. Repository Publishing

4-1. Publish the Repository

Coordinate as needed with a blog post or a press release.

4-2. Conduct a Post-Publishing Review by the OSS Promotion Office

Even after publishing the repository, verify that the repository settings are configured as intended.

• Check for any omissions in "2. Repository Setup"
• Confirm that the following GHAS features are enabled: Code scanning (CodeQL), Secret scanning, Push protection
• Verify that Dependabot Alerts is enabled
• Ensure the "Report a Vulnerability" link in the repository's SECURITY.md file works for both:
  • Members of the GitHub organization
  • External users of the GitHub organization
    • If the link results in a 404 Not Found error for external users, Private vulnerability reporting might be disabled
• Confirm that Reported content in Reported content settings is set to Prior contributors and collaborators
  • 💡 This setting restricts or relaxes who can report vulnerabilities

Conclusion

In this article, I shared the "OSS Publishing Tutorial" that we created and used when making Giselle and Liam open-source.

Although I have experience with open-sourcing projects personally, I initially thought, "Isn't it just about publishing a repository?" However, in a professional setting, numerous other things to consider came to light, resulting in this detailed "OSS Publishing Tutorial." We plan to keep updating it moving forward.

I hope this serves as a useful reference.

Supplement: About Giselle and Liam as OSS

The giselles-ai/giselle repository recently published as OSS is for Giselle, a platform that enables no-code creation of agents and workflows utilizing generative AI. Detailed information can be found on the Giselle service website: https://giselles.ai/.

The liam-hq/liam repository is for Liam, a tool that effortlessly generates beautiful and easy-to-read ER diagrams. Detailed information can be found on the Liam service website: https://liambx.com/.

---

1. Example: https://github.com/giselles-ai, https://github.com/liam-hq ↩

2. ROUTE06, Inc. employees or partners with Admin/Write permissions for the repository ↩

3. Requires using the default CodeQL configuration to set it as a required status before PR merges ↩