GitHub Actions

Running on GitHub Actions will automatically enable custom theming for your build log output including collapsible groups for better structuring:

info

Please refer to the official GitHub Actions documentation for questions not covered here.

Environment Variables

You can access predefined environment variables by using the GitHubActions class:

GitHubActions GitHubActions => GitHubActions.Instance;

Target Print => _ => _
    .Executes(() =>
    {
        Log.Information("Branch = {Branch}", GitHubActions.Ref);
        Log.Information("Commit = {Commit}", GitHubActions.Sha);
    });

Exhaustive list of strongly-typed properties

class GitHubActions
{
    string  Action            { get; }
    string  Actor             { get; }
    string  BaseRef           { get; }
    string  EventName         { get; }
    string  EventPath         { get; }
    JObject GitHubContext     { get; }
    JObject GitHubEvent       { get; }
    string  HeadRef           { get; }
    string  Home              { get; }
    bool    IsPullRequest     { get; }
    string  Job               { get; }
    long    JobId             { get; }
    string  PullRequestAction { get; }
    int?    PullRequestNumber { get; }
    string  Ref               { get; }
    string  Repository        { get; }
    string  RepositoryOwner   { get; }
    long    RunId             { get; }
    long    RunNumber         { get; }
    string  ServerUrl         { get; }
    string  Sha               { get; }
    string  Token             { get; }
    string  Workflow          { get; }
    string  Workspace         { get; }
}

Configuration Generation

You can generate workflow files from your existing target definitions by adding the GitHubActions attribute. For instance, you can run the Compile target on every push with the latest Ubuntu image:

Build.cs

[GitHubActions(
    "continuous",
    GitHubActionsImage.UbuntuLatest,
    On = new[] { GitHubActionsTrigger.Push },
    InvokedTargets = new[] { nameof(Compile) })]
class Build : NukeBuild { /* ... */ }

Generated output

.github/workflows/continuous.yml

name: continuous

on: [push]

jobs:
  ubuntu-latest:
    name: ubuntu-latest
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Run './build.cmd Compile'
        run: ./build.cmd Compile

info

Whenever you make changes to the attribute, you have to run the build at least once to regenerate the workflow file.

Artifacts

If your targets produce artifacts, like packages or coverage reports, you can publish those directly from the target definition:

Target Pack => _ => _
    .Produces(PackagesDirectory / "*.nupkg")
    .Executes(() => { /* Implementation */ });

Generated output

.github/workflows/continuous.yml

- uses: actions/upload-artifact@v1
  with:
    name: packages
    path: output/packages

After your build has finished, those artifacts will be listed under the Summary tab:

Importing Secrets

If you want to use encrypted secrets from your organization or repository, you can use the ImportSecrets property to automatically load them into a secret parameter defined in your build:

Build.cs

[GitHubActions(
    // ...
    ImportSecrets = new[] { nameof(NuGetApiKey) })]
class Build : NukeBuild
{
    [Parameter] [Secret] readonly string NuGetApiKey;
}

Generated output

.github/workflows/continuous.yml

- name: Run './build.cmd Publish'
  run: ./build.cmd Publish
  env:
    NuGetApiKey: ${{ secrets.NUGET_API_KEY }}

note

If you're facing any issues, make sure that the name in the GitHub settings is the same as generated into the workflow file.

Using the GitHub Token

For every workflow run, GitHub generates a one-time token with adequate permissions that you can use to authenticate with the GitHub API. You can enable the GitHub token in your attribute as follows:

Build.cs

[GitHubActions(
    // ...
    EnableGitHubToken = true)]
class Build : NukeBuild
{
    GitHubActions GitHubActions => GitHubActions.Instance;

    Target Request => _ => _
        .Executes(() =>
        {
            Log.Information("GitHub Token = {Token}", GitHubActions.Token);
        });
}

Generated output

.github/workflows/continuous.yml

- name: Run './build.cmd Release'
  run: ./build.cmd Publish
  env:
    GITHUB_CONTEXT: ${{ toJSON(github) }}

Caching

By default, the generated workflow file will include a caching step to reduce the time for installing the .NET SDK (if not preinstalled) and restoring NuGet packages.

Generated output

.github/workflows/continuous.yml

- name: Cache .nuke/temp, ~/.nuget/packages
  uses: actions/cache@v2
  with:
    path: |
      .nuke/temp
      ~/.nuget/packages
    key: ${{ runner.os }}-${{ hashFiles('global.json', 'source/**/*.csproj') }}

You can customize the caching step by overwriting the following properties:

Build.cs

[GitHubActions(
    // ...
    CacheKeyFiles = new[] { "**/global.json", "**/*.csproj" },
    CacheIncludePatterns = new[] { ".nuke/temp", "~/.nuget/packages" },
    CacheExcludePatterns = new string[0])]
class Build : NukeBuild { /* ... */ }