GitHub Partner Portal

Releasing and maintaining actions

2021-03-19T00:00:00+00:00

Problem statement

So you have created an action…now what? This pattern guide shows a minimal solution to releasing and maintaining actions in open source, favoring automation whenever possible, providing value while keeping overhead at a minimum.

The solution should:

Leverage GitHub Actions for continuous integration, dependency updates, release management, and task automation.
Promote discoverability with regular publishing to GitHub Marketplace.
Provide confidence through automated tests and build badges.
Indicate how the action can be used, ideally as part of a broader workflow.
Signal what type of community contributions you welcome, e.g. issues, pull requests, or vulnerability reports.

Solution

We recommend that Technology Partners build actions with JavaScript instead of in containers for speed and cross-platform functionality, so this guide will focus on JavaScript actions.

Though they are “just” Node.js repositories with metadata in an action.yml file, JavaScript actions have a few interesting properties compared to traditional Node.js projects:

Dependent packages are committed alongside the code, typically in a compiled and minified form, so automated builds and secure community contributions are important.
Tagged releases can be published directly to GitHub Marketplace and consumed by workflows across GitHub, making sensible releasing and tagging of special interest.
Many actions make use of the GitHub API and third party APIs, so we encourage robust end-to-end testing.

We base a solution on actions/javascript-action, putting special focus on solving the problem areas identified above. We use GitHub Actions to automate releasing the action and publishing to GitHub Marketplace, and open source best practices to increase confidence and usage.

Implementation

Automate release management

GitHub recommends creating releases using semantically versioned tags – for example, v1.1.3 – and keeping major (v1) and minor (v1.1) tags current to the latest appropriate commit. When a release is created, it can be published to GitHub Marketplace for increased discoverability.

^
|
|
| * commit 9a4eb0d (tag: v1, tag: v1.1, tag: v1.1.0)
|/  Author: Octocat <octocat@github.com>
|
|      New features!
|
|  
| * commit ac2415 (tag: v1.0, tag: v1.0.3)
|/  Author: Octocat <octocat@github.com>
|
|       Initial release
|
*
|
main

We let GitHub Actions do the automation for us to enable this workflow:

Do feature work in branches per GitHub flow.

When a feature branch commit is pushed, GitHub Actions runs a test workflow from which you can call unit and integration tests.

Create pull requests to the main branch to initiate discussion and review, merging when ready.

When a pull request is opened, either from a branch or a fork, GitHub Actions again runs the test workflow, this time with the merge commit. A label workflow also runs to add appropriate labels to the pull request depending on which file path is being changed.
Note: for security reasons, workflows triggered by pull_request from forks have restricted GITHUB_TOKEN permissions and do not have access to secrets. If your tests or other workflows triggered upon pull request require access to secrets, consider using a different event like a manual trigger or a pull_request_target. Read more here.

Create a semantically tagged release using the GitHub UI, also publishing to GitHub Marketplace with a simple checkbox.

When the release is created, GitHub Actions runs a publish workflow that uses a community action, JasonEtco/build-and-tag-action to compile and bundle the JavaScript and metadata file and force push semantic major, minor, and patch tags as visualized above.

Unlike some other automated release management strategies, we intentionally do not commit dependencies to the main branch, only to the tagged release commits. By doing so, we encourage users of our action to reference named tags or shas, and we help ensure the security of third party pull requests by doing the build ourselves during a release.

Committing to semantic releases means that the users of your actions can pin their workflows to a version and know that they might continue to receive the latest stable, non-breaking features, depending on their comfort level:

### A workflow consuming your action

# The latest major release version:
uses: github-developer/javascript-action@v1

# Or, the latest minor release version:
uses: github-developer/javascript-action@v1.1

# Or, the latest patch release version:
uses: github-developer/javascript-action@v1.1.0

# Or, a specific commit sha:
uses: github-developer/javascript-action@ff958b3d4b36abb3d3058e1e866695ce6111d213

Open source like the best

Working in the open can be hard, but fortunately, GitHub provides tools and guides to make it easier. Here are a few structures we recommend setting up for healthy bidirectional communication.

By providing the following signals to the community, we encourage use, modification, and contribution to our action:

Maintain a great README with plenty of usage examples, guidance, and badges
- How to add a workflow status badge (docs)
- Other metadata badges (shields.io)
Set up community health files like CODE_OF_CONDUCT, CONTRIBUTING, and SECURITY, either organization-wide or in your action repository.
Keep issues current by utilizing actions like stale

Check out more resources for building in the open here.

Concrete implementation

Template repository: https://github.com/github-developer/javascript-action

Examples

Examples where similar patterns are employed include:

Integrating with Code Scanning

2021-03-09T00:00:00+00:00

Problem statement

Many of GitHub’s Technology Partners offering security products in the form of static analysis tooling, wish to surface their tools’ security findings directly in GitHub’s UI, making it easier for developers to adopt their tooling, and adding value to the development workflow by identifying potential vulnerabilities before they reach production. This kind of developer workflow is often associated with DevSecOps and the concept of shifting left, as security analyses are performed frequently and earlier in the development process.

Solution

A paved path exists that is tailored for this type of integration in the form of GitHub code scanning, a developer-first, GitHub-native approach to easily find security vulnerabilities before they reach production.

Technology Partners can integrate their tooling with code scanning by submitting analyses in the Static Analysis Results Interchange Format (SARIF) (v2.1.0) format to GitHub. This format is specified formally here, however GitHub code scanning supports only a subset of the properties, which are listed here.

The analysis is typically triggered by events originating from GitHub, such as developers pushing code (the push event), opening a pull request (the pull_request event), or on some pre-determined automated schedule (i.e. once per week).

Two implementation approaches are available, via GitHub Actions, or via GitHub Apps, each of which are explored further below.

Prior to diving in to the implementation detail, it is worth designing how your tool should structure its output using the SARIF format, with consideration for the SARIF properties that are supported by GitHub code scanning.

Commonly, this will be an iterative process:

Generate your SARIF report (potentially by hand, at least initally)
Validate your SARIF report, using the online SARIF validator at sarifweb.azurewebsites.net/Validation
- Important: It is recommended to enable GitHub ingestion rules, for additional code scanning compatibility validation
Upload your SARIF report to GitHub code scanning for visual verification. Note: Code scanning is available for all public repositories and for private repositories owned by organizations where GitHub Advanced Security is enabled. For more information, see About GitHub Advanced Security.
- Uploading may be done using the REST API, via a curl command. Note, the SARIF report must be gzipped and base64-encoded prior to being uploaded to GitHub.
- Alternatively, commit the SARIF report directly to a GitHub repo and upload it to code scanning using the github/codeql-action/upload-sarif action.
Repeat.

Example SARIF report

An example SARIF report (generated by the Brakeman tool for an intentially vulnerable Ruby on Rails application), whose structure was designed by following the process outlined above, is available:

The following points warrant special mention:

The output conforms to version 2.1.0 of the SARIF spec, as indicated by the top-level version and schema properties, and confirmed by the online SARIF validator
The top-level runs object is an array containing a single element, an object representing the tool, rules, and results of the run.
- The tool’s semanticVersion is useful to include, it’s helpful for ingestion systems to know run-over-run if a tool is updated.
The rules array represents the set of vulnerabilities that the tool scans for, each rule is represnted by an id, name, fullDescription, helpUri, help text, and an additional properties bag
- Each rule’s id uses a prefix that is representative of the tool name, BRAKE in this instance, followed by a numeric identifier. This helps with filtering of rules in the GitHub code scanning UI
- Each rule’s name is a hierarchical property, this makes sense for this particular tool and othes may also adopt this pattern where it makes sense
- Each rule’s fullDescription ends with a period, which helps facilitate a consistent user experience when the rule is rendered by GitHub code scanning
- Each rule’s help references an external article via a URL. Generally it is preferred to include the help text inline, within the SARIF report, but for this implementation this was not straightforward, and will hopefully be addressed in a subsequent iteration.
The results array captures the results of the analysis, with each violation of a rule being captured in a single result entry. For example, rule BRAKE0014 is violated five times, as indicated by results on lines 437, 458, 479, and 500, 521
- Each result’s entry references the rule being violated, via the rule’s id and position in the rules array
- Each result’s entry maps onto a source file via the locations array, for portability across systems, the uri is expressed a path relative to %SRCROOT%

The following screenshot shows the GitHub code scanning representation of a violation of rule BRAKE0014, derived from the corresponding result object on lines 520 through 540.

Note, this is a relatively straightforward SARIF report, more sophisticated constructs are possible. To learn more, it is recommended to follow the SARIF tutorials, and review the specification.

Implementation detail

Once you are satisfied with the structure of the SARIF produced by your tool, there are two primary approaches when integrating it with code scanning:

Via GitHub Actions
Via GitHub Apps

The former is generally applicable where:

The tooling is installable as a CLI tool that can easily execute on GitHub’s compute (e.g. Brakeman, detekt), -or-
The tooling may be easily invoked via public or authenticated API calls. Tokens for authentication may be held in GitHub as encrypted secrets.

The latter is more suitable for solutions that have unique compute requirements, or that have user-facing elements (such as configuration controls or dashboards), potentially via a dedicated web UI or control panel.

GitHub Actions and GitHub Apps are both covered in more detail in the Platform Integration 101 presentation.

Additional resources are also available for both GitHub Actions and GitHub Apps

Onboarding your integration into the GitHub code scanning UI

When complete, the onboarding of your integration into the GitHub code scanning can be initiated by opening a new pull request in the actions/starter-workflows repo. Additional instructions are located in the pull request template.

Publication to GitHub Marketplace

In addition to onboarding into the code scanning UI, we highly recommend publishing your integration to Marketplace for increased visibility.

Additional information is available for both GitHub Actions and GitHub Apps.

Examples

Existing implementations and examples are available:

Brakeman SARIF implementation: github.com/presidentbeef/brakeman/pull/1500 (Brakeman is an open source statis analysis tool, popular in the Ruby on Rails community)
Code Scanning playground: github.com/swinton/code-scanning-playground (a forkable template repo, showing a simple code scanning workflow leveraging ESlint)

Resources for learning SARIF

Useful resources for learning SARIF are available:

SARIF tutorials from Microsoft: github.com/microsoft/sarif-tutorials
SARIF Validator web-based tool: sarifweb.azurewebsites.net/Validation
SARIF specification, v2.1.0: docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html

Further documentation

Further documentation is available on GitHub.com, including:

SARIF support for code scanning: docs.github.com/github/finding-security-vulnerabilities-and-errors-in-your-code/sarif-support-for-code-scanning
Code scanning REST API: docs.github.com/rest/reference/code-scanning

Welcome to our new Partner Hub

2020-12-06T08:00:52+00:00

Welcome!

We’re happy to announce that we have launched our new Partner Hub! 🎉 The Partner Hub provides access to all the resources you need so that we can work together to create incredible experiences for our shared customers.

As a first step, evaluate which GitHub Partner Program to join. The Technology Partner program is for ISVs, integrators, and cloud service providers that want to extend the GitHub platform and co-market with us, while the Service and Channel Partner Program is for service-oriented and resell partners that want to deliver services to our joint customers and co-sell with us.

Partner Program Requirements

For the Technology Partner Program, see the Program Requirements section on the Technology Partners tab.
For the Channel Partner Program, see our Services & Channel Partners Handbook.

Where to get started

Get started by browsing through the below articles:

Technology Partners

Platform integration 101 slides - Overview of how to build technical integrations with GitHub
Learn GitHub Actions - Guide to help you use GitHub Actions to accelerate application development workflows
GitHub Apps 101 slides - Introduction to GitHub Apps
GitHub Technology Partner Program: Co-marketing with GitHub

Services & Channel Partners

GitHub Services & Channel Partners Handbook - Accelerate your business and help your customers reach their full DevOps potential
GitHub Channel Partner Value Proposition - Market opportunities, partner growth insights, and GitHub orientated offerings for partners

Partner Hub Updates

Check out our new Resources and Newsfeed sections:

Resources

The Resources section contains info on topics such as integration and go-to-market.

Newsfeed

We will continuously update the Newsfeed with key information such as partner-related product updates, events, and more. Stay tuned for our quarterly newsletter with all of our ecosystem updates.

Sponsorship Opportunities

2020-11-30T08:00:52+00:00

Leverage the GitHub brand to get in front of 1000’s of developers with our Sponsored opportunities.

GitHub Services & Channel Partners Handbook

2020-11-25T16:08:39+00:00

Overview

Welcome to the GitHub Services & Channel Partner Network! By partnering with GitHub, you can accelerate your business and help your customers reach their full DevOps potential.

Developers sit at the heart of any organization. And GitHub serves as a catalyst for driving cultural change within an organization, unifying developers across a single platform and breaking down silos.

GitHub partners can help customers realize the full value of a true DevOps culture.

The purpose of this handbook is to provide an overview of our partner programs and resources to help our partners provide joint value to customers and grow your business.

Documentation GitHub Services & Channel Partners Handbook

Github Channel Partner Value Proposition

2020-11-25T16:00:34+00:00

Market Opportunity - Over 50 million developers use GitHub today. Week by week, we are adding more and more customers across all segments. These customers choose GitHub to unlock the full potential of their development teams to help transform their organisations in a secure and compliant way. They need help to realize this journey. Few customers today are able to unlock the full potential of a mature DevOps approach, they need support from our partners to guide them realize their full potential.

Partner Growth Insights - Our most successful Services & Channel partners are looking to develop a Services practice centered around GitHub. These partners lead with services engagements, which our partners leverage to allow customers to get the most value out of GitHub. As we think about the future opportunities for partners and GitHub, our partners’ long-term success will be enhanced by building out their services capabilities. We see potential for growth around the Advanced Security space, and migration, innersource, app modernization, and digital transformation related services are some of the top partner offerings today.

GitHub Orientated Offerings For Partners - Build GitHub-orientated offerings and practice to engage customers in clearly defined scenarios.

Driving GitHub Deployment and Adoption - GitHub is being increasingly successful with acquiring large customers with large GH footprints. These customers require deep support to help them deploy and drive adoption of the customer base. Triangulating our joint customer lists here may be interesting to explore.
Extend GitHub Workloads in Customers:
- Drive Actions Adoption - migrations from other platforms and providing ongoing support for customers CI/CD journey
- GitHub Advanced Security - enabling customers to develop code that secure by design - move security to the left and leverage GHAS capabilities
Adding GitHub to existing offerings:
- Application Modernization - address the underlying root causes that created the need for applications to be modernized. If there was an effective SDLC /DevOps approach applications would be managed more effectively through their lifecycle
- Cloud Native App Development - when supporting customers develop new applications, use GitHub as the catalyst and enabler to accelerate the development cycle, write secure code by design and reduce time to deploy.
- Digital Transformation - Overall Digital Transformation engagement, help customers become software/technology customers. Requires them to invest in the Development capabilities and unlock the potential of their own developers.
- Innersourcing - Driving developer productivity, sharing and collaboration, writing a line of code only once, leveraging OpenS Source in secure ways…..
- **Journey to the Cloud **- Include Infrastructure Migrations (with Infrastructure as Code), moving development to the cloud, deploying applications to the cloud (New/Existing)

GitHub Technology Partner Program: Co-marketing with GitHub

2020-11-25T13:17:15+00:00

General guidelines

Before engaging in co-marketing, we ask our partners to have (or be in the process of producing) a GitHub integration such as a verified Action, Application, or public container image published to GitHub Packages onto the GitHub Marketplace. Partners must also be a part of the GitHub Technology Partner program.

Co-marketing

Joint go-to-market efforts may include co-branding support and social amplification for new integrations or user enablement. For advanced partners, we will consider additional tactics, such as partner-led webcasts, highlights within other GitHub-led content or blog, support for partner public product announcements, joint customer stories, or other items specific to each partner. Please work with your business development manager for more information.

Branding assets

Upon completion of a validated integration, partners can request a social card with their logo and an appropriate GitHub property logo based on their particular integration with GitHub (e.g. Actions, Packages, GitHub Application). Your business development manager will connect you with GitHub marketing teams to work with you on appropriate placement.

Tips on sending brand elements:

SVG files with transparent background are preferred
For flexibility, we request square and longitudinal aspect ratios, as well as dark- and light-colored logos for contrast against light and dark backgrounds
Please also send an SVG of your mark (for most companies, this is your logo, minus text of the company or product name)

Alternatively, you can send a URL for your branding guidelines to your GitHub business development manager or other GitHub marketing contact.

We love highlighting the work our partners do with us! We use two main social media channels, Twitter and LinkedIn. We will amplify:

announcements in which GitHub integrations are included, such as an Action or GitHub App in GitHub Marketplace, or a public container image within GitHub Packages (CTA in the announcement has to include the GitHub Marketplace URL)
walkthrough or how-to content on these integrations when they are on partner-led channels
virtual events in which both GitHub and the partner are participating, such as a webinar, or conference breakout session

We reserve the right to choose which channel(s) to use to amplify, based on our judgment of what will be of interest to the audiences on each. Some items may be a better fit for Twitter, some for LinkedIn; some will find a home on both. Posting is also subject to available space in the GitHub editorial calendar.

Partner-owned content + supporting quote from GitHub

Please let us know if you are planning to do any sort of owned content to discuss your GitHub integration, and would benefit from additional support from GiHub. We’ll want to know a few things:

Will there be a press release, blog, social content? If so, GitHub public relations and marketing will need to review to ensure GitHub and our products are being represented properly.
Are you seeking a supporting quote from GitHub? Please note - we can’t promise every partner a quote, and, if we do, we prefer that it be in support of announcements of new GitHub Actions or integrations that are verified within our Marketplace, or significant updates to existing integrations.
Is there any specific timeline you’re working against? It’s ideal for GitHub public relations to have at least a week to review partner-owned content, so insight into the timeline for publication of partner-owned content is imperative.

Partner integration spotlights

On occasion, we may highlight GitHub partner integrations through various customer or user communications channels, highlighting new integrations or partnerships. In these instances, we will proactively reach out to you to ask for 100-word summaries from our partners to include. These summaries should include an introduction to the technology partner and the product that is integrating with GitHub, along with a short description of the specific integration itself. GitHub public relations and marketing will need to review and approve the description for accuracy and messaging.

Potential partner integration spotlight channels include enterprise newsletters, round-up blog posts on partner integrations, or demos through our other online video channels such as Twitch.

For all other questions regarding co-marketing, please reach out through the partner portal, or to your assigned business development manager.

Setting up a CLI on GitHub’s hosted runners

2020-11-24T00:00:00+00:00

Problem statement

Many of GitHub’s Technology Partners wish to provide a way for developers to easily access their services via a configured CLI environment on GitHub’s hosted runners, for example, so that it is available in a CI/CD workflow.

The solution should :

Make it simple for developers to precisely describe the version of the CLI to be installed
Support multiple operating systems
Run in an efficient fashion to minimize run-time and associated costs
Work across hosted and self-hosted runners
Leverage community tooling when possible

Solution

Technology Partners should solve this by providing an action in a repo they maintain, written in, or compiled / transpiled to JavaScript. The action should be responsible for retrieving a specific version of the CLI, installing it, adding it to the path, and (optionally) caching it. Commonly this variety of action that performs some setup of a tool, is named **setup-$TOOL**. Refer to the examples below to see how this pattern is already in use in multiple ecosystems.

GitHub provides the actions/toolkit set of packages, which makes this process more straightforward across all of GitHub’s hosted runners.

Specifically, the actions/core and actions/tool-cache package expose operations that are commonly required in this scenario, in a cross-platform way.

Implementation

A simple cross-platform implementation in JavaScript follows, note, the implementation for getDownloadURL is intentionally absent, so that the example remains generic:

const core = require('@actions/core');
const tc = require('@actions/tool-cache');

async function setup() {
  // Get version of tool to be installed
  const version = core.getInput('version');

  // Download the specific version of the tool, e.g. as a tarball
  const pathToTarball = await tc.downloadTool(getDownloadURL());

  // Extract the tarball onto host runner
  const pathToCLI = await tc.extractTar(pathToTarball);

  // Expose the tool by adding it to the PATH
  core.addPath(pathToCLI)
}

module.exports = setup

Concrete implementation

A concrete implementation of this pattern is available here.

Examples

Example where this pattern is employed include:

For more information on creating a JavaScript action, refer to this guide.

Building blocks: Creating your own GitHub Actions with JavaScript

2020-11-10T00:00:00+00:00

This workshop was originally given at GitHub Universe 2019 and provides a conceptual overview of GitHub Actions and a guide of how to build your very own action using JavaScript.

Repo: Building Blocks: Creating Your Own GitHub Actions With JavaScript

Creating a GitHub App - Demo Days

2020-11-10T00:00:00+00:00

Steve Winton, Partner Engineer, explains why someone might want to build a GitHub app, then builds one from scratch. Create 3rd party integrations to GitHub via the API and allow them to act autonomously on protected resources. Using the example of OAuth, walk through GitHub Enterprise Server and learn how to build then manage administration, monitoring and installations.

Once you’ve built your app, consider partnering with GitHub.

Video: Demo Days - Creating a GitHub App

GitHub Partner Portal

Releasing and maintaining actions

Problem statement

Solution

Implementation

Automate release management

Open source like the best

Concrete implementation

Examples

Related

Integrating with Code Scanning

Problem statement

Solution

Example SARIF report

Implementation detail

Onboarding your integration into the GitHub code scanning UI

Publication to GitHub Marketplace

Examples

Related

Resources for learning SARIF

Further documentation

Welcome to our new Partner Hub

Welcome!

Partner Program Requirements

Where to get started

Technology Partners

Services & Channel Partners

Partner Hub Updates

Resources

Newsfeed

Sponsorship Opportunities

GitHub Services & Channel Partners Handbook

Overview

Github Channel Partner Value Proposition

GitHub Technology Partner Program: Co-marketing with GitHub

General guidelines

Co-marketing

Branding assets

Social amplification

Partner-owned content + supporting quote from GitHub

Partner integration spotlights

Setting up a CLI on GitHub’s hosted runners

Problem statement

Solution

Implementation

Concrete implementation

Examples

Related

Building blocks: Creating your own GitHub Actions with JavaScript

Creating a GitHub App - Demo Days