Our program

Tools & Services

Microsoft uses many tools and services in supporting its open source program. Here are just a few that you may find useful in your own company or open source community.

GitHub Enterprise Cloud with SAML single-sign on

Microsoft has over 100 GitHub organizations dedicated to open source activities. Collectively, these are part of an enterprise account at GitHub.

Some of the features the enterprise product brings to us include:

• SAML single sign-on adds an additional layer of protection for Microsoft by connecting with Microsoft's Azure Active Directory system, verifying access and protecting access tokens and SSH keys.
• Secure supply chain features such as private repo secret scanning help to discover accidental check-in of credentials, while vulnerability notifications and built-in dependency update pull request capabilities help projects to stay in the best shape.

GitHub Actions and Azure Pipelines

While Microsoft uses many different continuous integration systems, and open source projects adopt whatever common toolset an open source community prefers, many projects are powered by GitHub Actions and Azure Pipelines.

• GitHub Actions are the preferred way for projects to build and validate. Being built-in to the GitHub experience for developers, configuration is quick and easy.
• Azure Pipelines can be exposed to public, open communities, allowing many Microsoft projects to continue using the build system they've been using for many years, but with a collaborative angle.

Component Governance

At Microsoft, a internal extension for Azure DevOps called Component Governance was created to help provide automatic inventory of all the open source components used.

• Automatic inventory registration: every build at Microsoft is connected to Component Governance. Detected open source is registered, enabling teams to trace a specific build to the bill of materials it contained, and providing historical snapshots and build-by-build analysis of change. The automatic inventory is connected to an alerting system and business review system as needed.
• Security alerts: by connecting to security data sources, public known vulnerability data such as CVEs, and curated Microsoft-internal security knowledge, alerts can be raised at any time to help engineers protect Microsoft and its customers.
• Legal alerts: open source license data and algorithms specific to Microsoft's open source approach are used to generate alerts when specific components have additional legal obligations or requirements, such as publishing third-party source disclosures to https://3rdpartycode.microsoft.com/.
• Business review process: a legal and business review process, implemented as Azure Boards work items, is used for certain uses of open source.

GitHub Bots

Many different bots and applications are used as part of Microsoft's open source program. Bots help teams to scale and provide a great experience for communities.

Some of the common building blocks for GitHub Bots used at Microsoft include:

• Probot: framework for building GitHub Apps to automate and improve your workflow
• octokit/rest.js: REST API client for JavaScript and Node.js apps to connect to GitHub
• Octokit.net: for .NET applications to integrate with GitHub

Self-service GitHub open source portal

When interfacing with third-party services such as GitHub, it is important to be able to identify employees at the same company working together on open source.

While GitHub allows organization members to publicize their organization membership on their individual profile, there is more to know. GitHub user management solutions will offer the following capabilities:

• Employment lifecycle automation: Employees should be able to join a company organization, if authorized, without needing a manual invitation. When an employee decides to leave the company, their access to company resources and GitHub organization membership should be removed.
• User linking: Authenticating an employee with IT and also GitHub to associate the GitHub account
• Communications: By linking an employee's corporate identity with their GitHub account, comms are possible without having to ask the user to share their email address or other information on their public profile.

Microsoft's self-service GitHub management portal is implemented in TypeScript and is a Node.js service. The portal is open source at https://github.com/microsoft/opensource-portal.

ClearlyDefined

ClearlyDefined provides license, source location, and attribution information on over 10 million open source components. We rely on this data for our compliance systems.

This open source project provides compliance data about open source components from across the package ecosystems. It uses multiple open source scanners and summarizes their results into a high-quality "definition" of the component upon which we base our business policy decisions internally. It also:

• Enables crowd-sourced curation: In cases where the data about a component is missing or incomplete, the project facilitates community curation of the data in order to improve it. This process is all done transparently and with multiple community reviewers.
• Facilitates data improvements upstream: Over time, the corpus of ClearlyDefined curations are intended to be submitted back to the upstream projects as pull requests so that future versions of the component are more clearly defined.

ClearlyDefined is an open source project of the Open Source Initiative (OSI) and its open source code is at https://github.com/clearlydefined.

Microsoft's Contributor License Agreement (CLA)

The Microsoft's Contributor License Agreement is a Contributor License Agreement solution that integrates nicely with GitHub to make sure that all contributors to a project have agreed to common terms by enabling contributors to sign CLAs from within a pull request.

GitHub data crawling

Microsoft has developed and adopted several different approaches to retrieving GitHub data about activity within our organizations: we use the GitHub REST API v3 and GraphQL to regularly make data about our GitHub repos, traffic data, issues and pull requests all available inside our big data systems.

By making data available in Azure Data Explorer, powered by Kusto, it's really quick for Microsoft engineers to be able to query data without having to build specialized GitHub API integrations.

Microsoft's 1ES team is in the process of open sourcing this technology.

Business review process with Azure Boards

Our business and legal review process - kicked off when a particular open source use, contribution, or release, scenario requires - integrates into the engineering system that includes Azure Boards. This helps meet engineers where they are, providing an easy way to review requirements, manage approvals and workflow, and eventually completing any necessary reviews.

This system is built by using the Work Item Tracking extensibility features and the Azure DevOps REST API.

Open source use guidance

This is a summary of how we approach using open source at Microsoft.

Using open source in Microsoft is encouraged. Building on the efforts of others allows us to create meaningful value for our customers faster and engage with new ecosystems and user-bases in a natural way.

Take the following steps to use an open source component at Microsoft:

• Register All Open Source: Following the open source compliance policy, all open source components must be registered. You can do this two ways:
  • One Engineering System automatically registers most types of open source. Open source detectors are run and will handle the registration of open source components. Legal and security alerts will be raised with follow-up actions if there is additional work required, such as meeting legal obligations, posting to the third-party disclosures site, addressing a security issue, or if a commercial or unknown license is present.
  • For repos using certain types of open source, a Manual Registration approach or file can be used in lieu of detectors. Boutique engineering systems will need to refer to the non-standard build environments content.
• Distribution Requirements: If you plan on distributing the open source component in a Microsoft Product or Service, you must take additional steps, as guided by legal alerts, that might include NOTICE file generation and making source code available.

Contributing to open source

This is a summary of how we approach contributing to open source at Microsoft.

We encourage our employees to contribute to open source communities. Contributing improvements to projects we use enhances the value everyone derives from the project and can drive a project forward.

Microsoft's contribution policy varies depending on the size and purpose of contribution.

• Small changes: If your contribution meets the "Small Contribution Exception", just create a fork, make the fix, and submit a pull request. If making the pull request on GitHub, you can create the fork in your personal GitHub account, rather than an official corporate organization account.
• Larger changes: If the contribution is larger, your contribution should be reviewed and approved. There is a contribution request form that will kick of a business and legal review process, how to scope the request. The process will include reviewing the contributor guide and the CLA for the project.
• Meet Community On Its Own Terms: Note that different open source communities take contributions in different ways. Before firing off a pull request, investigate how best to engage the community you will be contributing back to.
• Fork Nicely: Always try to contribute to a community instead of hard forking. Review internal guidelines and training before forking into an official GitHub org.

Working in the open

Teams at Microsoft are encouraged to work in the open and are provided with straightforward guidance on when and how to release code to the world.

This is a summary of how we approach releasing open source at Microsoft.

Approval process

All open sourcing of Microsoft source code and content (e.g., text, images, fonts, data) must be registered with your business and legal team using the workflow outlined in the release documentation.

In other cases, you may need to work with your management and legal teams to review the business case, success plan, and IP management strategy around your proposal.

Location

All Microsoft open source code should be released on GitHub in one of Microsoft's GitHub orgs. The vast majority of projects will go in the official company org.

Where we are participating in existing community that does not work on GitHub, your code should go in the natural location for that community.

If you do not plan on releasing your code to the public, an InnerSource location provided by the One Engineering System team is a better option for private engineering work: for example, using Azure Repos.

Licensing

Microsoft open source code should be released under the MIT license absent a compelling reason to do otherwise.

Contributions

All contributions to a Microsoft-managed open source project must use the Microsoft Contributor License Agreement (CLA). The CLA must be agreed to by all contributors who are not Microsoft Full-time Employees (FTE) or interns prior to the contribution being merged into the project codebase.

The CLA requirement is waived in certain smaller contribution cases.

Release checklist

The following steps should be taken to release and maintain your open source project:

• Create your repo and register your release: The "new repo wizard" contains a form of questions regarding your release. Start there, or, if you created the repo directly on GitHub, you'll receive a link by e-mail to complete the wizard and unlock your repo.
  
  If a business and legal review is needed, the wizard will trigger that review process at the end.
• Include the following in your repo root directory. The default template may have placed these files for you as a start:
  • A README.md file describing the purpose and state of the repository, with a link to the Microsoft Open Source Code of Conduct and a description of any third-party code included in the repository. A good README file is often critical to project success.
  • A LICENSE file with an OSI approved license text.
  • A CONTRIBUTING.md file with instructions on contributing to the project that must include at least the minimum required information. That minimum information includes that contributions to Microsoft projects are subject to our Contributor License Agreement. Additionally, consider providing technical guidance like build instructions, coding conventions, or a project roadmap in the CONTRIBUTING.md file.
• Prepare the code for release:
  • Code license: Include the language-appropriate license comment at the head of each source file.
  • Remove sensitive assets:
    • Remove any reference in the code to internal or confidential information, including internal paths, tools, codenames, proprietary fonts, internal telemetry and email aliases.
    • Prepare the code and commit history for publication, including running certain internal corporate tools for this purpose.
  • Third-party Open Source: If your repository includes third-party OSS, describe its use and its license in a NOTICE file. Your open source attorney team may have additional details on this process for you.
• Publish the code: Once your registration and review process is complete, make your GitHub repository public using the Settings pane on GitHub.
• Going forward:Ensure:
  • Further Microsoft Contributions: You must file a contribution request if either the feature you are adding is outside the scope of your original release request OR you are adding non-open source Microsoft code that your team did not author.
  • Staffing: Ensure at least one team member is committed to managing community interactions merging pull requests, giving feedback, releasing new versions.
  • Buildable & Runnable: Make sure that your project is easy to build and has binaries available is key to attracting contributors.
  • Foster your community: Look for ways to continue engagement with potential contributors.