GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production. For more information about GitHub Actions in general, check out the official GitHub documentation for GitHub Actions.

Setting up a Workflow

A workflow is a configurable automated process that will run one or more jobs. Workflows are defined by a YAML file checked in to your repository and will run when triggered by an event in your repository, or they can be triggered manually, or at a defined schedule.

See the official GitHub documentation for workflow syntax, and for recommendations in getting started writing workflows. The NC State GitHub Service Team does not offer support for writing or customizing workflows.

Workflows may utilize Actions from the GitHub Marketplace, with the restriction that only Actions from Verified Creators are available for use. This includes Actions created by GitHub themselves, and from vendors which have been approved by GitHub. Additional exceptions are made on a case-by-case basis by the NC State GitHub Service Team. Contact the service team for more information if you have a request for an exception.

Artifacts and Logs from workflow execution are kept for a period of 90 days, after which they are deleted and are inaccessible.

Configuring Action Runners

In order to execute a workflow, a repository must have an Action Runner available which will do the actual work described in the workflow. Runners are the machines that execute jobs in a GitHub Actions workflow. For example, a runner can clone your repository locally, install testing software, and then run commands that evaluate your code.

Organizations may utilize either the freely available NC State Hosted Runners, the paid GitHub Hosted Runners, or opt to run self-hosted runners.

Repositories owned by a user account may only utilize self-hosted runners.

NC State Hosted Runners

The NC State GitHub Service Team offers a pool of Action Runners for use in any organization in the GitHub Enterprise Cloud service. There is no cost to use these Runners, but workflow runs are processed in the order in which they are received and there may be a queue for processing. These Runners are based on the same configuration as the GitHub Hosted Runners, but are hosted in the NC State datacenters, have access to NC State resources, and are free to use. More details regarding the NC State Hosted Runners is available in the relevant KB article (TBA). 

To allow a workflow to be executed by these Runners, you'll need to configure the `runs-on` property to "ncstate-university":

jobs:
  build-image:
    runs-on: [ ncstate-university ]

The Runners will also need to be permitted for the repositories in the organization settings before they will process workflows. To enable the NC State Hosted Runners for use in your organization, navigate to your organization settings, open the Runner Groups page under the Actions section, and click on the NCState group under "Shared by the Enterprise".

On the configuration page for that Runner Group, select the repositories within your organization that you'd like to be able to utilize the Runners, and optionally configure which workflows you'd like to allow. 

Your repositories should now be able to utilize the NC State Hosted Action Runners.

GitHub Hosted Runners

GitHub offers its own set of hosted Runners, which are available for a usage-based cost. The university is allowed a shared allotment of free usage per month, but this usage is first-come-first-served, with no guarantee of availability, and once the free quota is exhausted for the month workflows will not run. Organizations may opt into a usage-based payment to enable guaranteed access to GitHub Hosted Runners. Contact the NC State GitHub Service Team if you are interested in setting up payment for your organization. 

See the official GitHub documentation for using GitHub Hosted Runners for more details about configuration, features, and limitations.

Self-Hosted Runners

If neither hosted option is acceptable, organization owners and/or repository admins may opt to set up their own self-hosted runner. Please review the official GitHub documentation for self-hosted runners to get started setting up your own runner. Note that the NC State GitHub Service Team is not responsible for the maintenance, security, or support of self-hosted runners, and users who opt to set up and use a self-hosted runner do so at their own risk.