Build Services for Npm

MyGet Build Services allows you to connect to different types of source control systems:

• Git
• Mercurial (Hg)
• Subversion (Svn)

Next to that, integration with several Source Control Repositories is available as well:

• GitHub
• BitBucket
• Visual Studio Team Services
• CodePlex

Once downloaded, source code can then be built using a number of different methodologies.

Note: MyGet Build Services has a 5 minute cooldown period between builds during which you can't trigger a build, manually or otherwise. Please contact MyGet support for more information about our dedicated Build Services offering to avoid this cooldown period.

The Build Process

Using MyGet Build Services, you have the opportunity to control exactly how your project gets built. MyGet Build Services works based on several conventions to run builds. It will scan the contents of your Source Control Repository looking for a file which it can work with. In order of precedence, the following files are searched for:

• Scripts (*.bat, *.cmd, *.ps1) that are explicitly specified in the build source configuration.
• MyGet.bat, MyGet.cmd or MyGet.ps1
• build.bat, build.cmd or build.ps1
• package.json

Based on the files found, the build process will be slightly different.

Build process for package.json files

The following build steps will be run when building from package.json files:

• Fetch source code
• Set npm registry to the current feed
• Update package.json and set the version value to [%PackageVersion%](Available Environment Variables)
• Run npm run pre-myget (if applicable)
• Run npm install
• Run npm test
• Run npm pack
• Run npm run post-myget (if applicable)
• Push packages to your MyGet feed
• Label sources (if enabled)

Build process for batch / PowerShell based builds

The following build steps will be run when building from batch or PowerShell scripts:

• Fetch source code
• Run batch or PowerShell script
• Push packages to your MyGet feed
• Label sources (if enabled)

Configuring Projects to Build

When needed, the project files or scripts to build can be specified in the build source configuration. If this setting is omitted, the default build process conventions will be used.

This setting can contain scripts (like .bat, .cmd and .ps1 files). Note that when configured, pre- and post-build scripts will be ignored unless manually added to this list.

Pre- and post-build steps

Pre- and post-build steps with package.json files

When using package.json files for builds, MyGet Build Services will run the pre-myget script before running any other npm commands, and post-myget after packaging the node module.

For example, we could run npm version before our actual build, by adding the following to package.json:

"scripts": { "pre-myget": "npm version prerelease --no-git-tag-version", "post-myget": "echo This is a post-build step" },

The above example increases the prerelease version of the package. Note that adding git push is not required: you may want to enable labeling in the MyGet build settings to push changes back in a reliable way.

After build, the above will output a message to the build log.

Pre- and post-build steps with batch / PowerShell based builds

When using batch / PowerShell based builds, MyGet Build Services will scan for batch files to be executed. In addition to the MyGet.bat (or .cmd or .ps1) and build.bat (or .cmd or .ps1), we search for pre- and post-build steps as well. These can be batch scripts or PowerShell scripts that are run before and after the actual build file.

The following files are detected as being pre-build steps:

• pre-MyGet.bat, pre-MyGet.cmd or pre-MyGet.ps1
• pre-build.bat, pre-build.cmd or pre-build.ps1

The following files are detected as being post-build steps:

• post-MyGet.bat, post-MyGet.cmd or post-MyGet.ps1
• post-build.bat, post-build.cmd or post-build.ps1

Which packages are pushed to my feed?

By default, MyGet will push all npm packages generated during build to your feed, except for packages that are found in node_modules. The reason for this is that the node_modules folder is reserved by npm itself and may contain packages that were used during the build process and are not necessarily to be added to your feed. Note that when creating a batch-based build, a good practice is to generate packages in a folder that is not named node_modules. A good example would be output.

To override this default behaviour, a series of filters can be specified in the build configuration. When omitted, all packages generated during build will be pushed to your feed. When specified, only packages matching any of the specified filters or wildcards will be pushed to your feed.

Filters can be of different types:

• Plain text, e.g. MyPackage to match a specific package id.
• Containing a wildcard, e.g. MyPackage.* to match all package id's that start with MyPackage..
• Starting with a negation, e.g. !MyPackage.* to explicitly exclude all package id's starting with Mypackage.*.

Filters are executed in order of precedence. If a negation comes first, packages matching the negation will be excluded, even if the next rule defines to include the package.

Source labeling (tagging)

When enabled in the build source configuration on MyGet, source code can be labeled with the build number. This can be done for successful builds only (recommended) as well as for failed builds.

The label originating from MyGet will always be named in the form vX.Y.Z, vX.Y.Z.P or v.X.Y.Z-pre. The description for the label will always be the label name (the version number), followed by "- MyGet Build Services".

Note that for labeling sources, you must provide credentials that can commit to the originating source repository. If omitted, labeling will fail.

The labeling scheme is compatible with GitHub releases and can link a given npm package version number to a GitHub release.

Available Environment Variables

If you provide your own build.bat script or MyGet.sln, you can specifically instruct MyGet Build Services on how to act on your sources. This also means you'll need to take care of applying a version number to your build. That's why we provide you with the following set of parameters so you can benefit from using the version scheme you have already defined within the MyGet User Interface, as well as the build-counter attached to your build source.

Note: These environment variables are read-only and are reset to the initial values at the start of the build process.

Git-based builds

For Git-based builds, the following environment variables are added:

GitVersion and Semantic Versioning

When a Git-based build is executed, it is possible to run GitVersion during your build. This utility uses a convention to derive a SemVer product version from a GitFlow based repository.

Running GitVersion /output buildserver will cause MyGet Build Services to set the current %PackageVersion% value to the npm-compatible SemVer generated by GitVersion.

We advise to run a tool like GitVersion in a pre-build script so that it can set additional environment variables for the actual build script. GitVersion outputs service messages to provide these variables. The variables are explained and demonstrated in the GitVersion documentation.

GitVersion.Major=3
GitVersion.Minor=0
GitVersion.Patch=23
GitVersion.PreReleaseTag=
GitVersion.PreReleaseTagWithDash=
GitVersion.BuildMetaData=0
GitVersion.FullBuildMetaData=0.Branch.master.Sha.4898f534dfd906bd3a56818752f5fa4e16c31267
GitVersion.MajorMinorPatch=3.0.23
GitVersion.SemVer=3.0.23
GitVersion.LegacySemVer=3.0.23
GitVersion.LegacySemVerPadded=3.0.23
GitVersion.AssemblySemVer=3.0.23.0
GitVersion.FullSemVer=3.0.23+0
GitVersion.InformationalVersion=3.0.23+0.Branch.master.Sha.4898f534dfd906bd3a56818752f5fa4e16c31267
GitVersion.ClassicVersion=3.0.23.0
GitVersion.ClassicVersionWithTag=3.0.23.0
GitVersion.BranchName=master
GitVersion.Sha=4898f534dfd906bd3a56818752f5fa4e16c31267
GitVersion.AssemblyVersion=3.0.23.0
GitVersion.AssemblyFileVersion=3.0.23.0
GitVersion.OriginalRelease=4898f534dfd906bd3a56818752f5fa4e16c31267.2014-08-26 13:32:36Z
GitVersion.NuGetVersionV2=3.0.23
GitVersion.NuGetVersion=3.0.23

User-defined environment variables

Sometimes you may want to pass in a value to the build scripts without hard-coding it into the build script. MyGet supports setting additional environment variables that can be used in custom build scripts as well as MSBuild. From the Build Source configuration, you can add user-defined environment variables that will be made available during build.

Environment variables can be used in your builds:

• MSBuild: use the $(VARIABLE_KEY) syntax
• Batch files: use the %VARIABLE_KEY% syntax
• PowerShell: use the $env:VARIABLE_KEY syntax

Environment variables will be shown in the build log. If needed, environment variable values can be hidden in the build log using the open/closed eye button.

Service Messages

It is possible for a build to interact with MyGet Build Services using Service Messages. For example writing a message to the build log, setting the package version or triggering a build failure.

Service messages are strings that have a specific format that MyGet recognizes and can parse. Being strings, they can be written using an echo or the MSBuild Message task. The format of a service message can be:

• ##myget[messageName 'value'], passing a single value to the build
• ##myget[messageName key='value' key='value'], passing multiple values to the build

Special characters (like \r, \n, ', [ and ]) should be prefixed with a |.

Note: MyGet Build Services also parses TeamCity service messages. This means all tools that use TeamCity-specific service messages for communication with the build process will also work with MyGet Build Services.

Overriding the Package Version

The %PackageVersion% environment variable can be changed by using the buildNumber service message, for example:

##myget[buildNumber '1.0.0-beta1']

Note that this should be done in a pre-build step, as the environment variable is not updated in the running script (this could be done by just setting the environment variable manually).

Explicitly publishing a package

Packages can be published explicitly to a MyGet feed by using the publishPackage service message, for example:

##myget[publishPackage path='<relative-path-no-wildcards>' type='nuget|symbols|npm|bower|vsix|phpc']

This service message requires the relative path to the package (from the root of the source control repository). Wildcards are not supported: each artifact that needs to be published has to be enumerated.

Note that MyGet Build Services also applies package filters when the publishPackage service message is used. If a filter excludes a given package, the package will not be published to the MyGet feed.

Writing messages to the build log

Messages can be written to the build log using the message service message, for example:

##myget[message text='Text to write' errorDetails='stack trace' status='ERROR']

The errorDetails are not required. The status defaults to NORMAL and can be set to NORMAL, WARNING, FAILURE or ERROR.

Setting environment variables for a future process

The setParameter service message allows setting an environment variable that can be used by a future process. For example, in a pre-build step an environment variable can be set for the actual build script that runs later. The setParameter service message has the following format:

##myget[setParameter name='Name' value='Value']

Note that this should be done in a pre-build step, as the environment variable is not updated in the running script (this could be done by just setting the environment variable manually).

Reporting build failure

Using the buildProblem service message, a build failure can be triggered. This will stop the build at the exact position the message was written to output. For example:

##myget[buildProblem description='Build failed because of this error']

Build Status Badges

You can embed a status image for a build into any web page out there, including your project’s README file or documentation. Your users will be immediately updated about the status of the last build performed. Here’s an example badge for a successful build:

Badges will be shown for pending builds (queued or building) as well as successful and failed builds. The URL for a build badge can be obtained through the Build Services configuration:

It can then be used in HTML, for example with a hyperlink to your feed on the MyGet Gallery:

<a href="https://www.myget.org/gallery/googleanalyticstracker"><img alt="GoogleAnalyticsTracker Nightly Build Status" src="https://www.myget.org/BuildSource/Badge/googleanalyticstracker?identifier=479ff619-28f2-47c0-9574-2774ed0cd855" /></a>

You can do the same in Markdown:

[![GoogleAnalyticsTracker Nightly Build Status](https://www.myget.org/BuildSource/Badge/googleanalyticstracker?identifier=479ff619-28f2-47c0-9574-2774ed0cd855)](https://www.myget.org/gallery/googleanalyticstracker)

Of course, you can also use it in any other markup language that supports embedding images.

GitHub Status API

When a build source is linked to a GitHub repository and has credentials specified, MyGet Build Services will make use of the GitHub Commit Status API to report status messages about a build back to GitHub and making them visible with commits and pull requests on GitHub. The status message posted to GitHub reflects the build status and links to the build log on MyGet.

To enable GitHub Commit Status messages on your builds, make sure the build configuration has credentials specified. Specifying credentials can be done by removing and adding the build configuration again, a method which doesn't require you to enter your password. You can also specify credentials manually by editing the build source.