Skip to content

Latest commit

 

History

History
160 lines (105 loc) · 6.16 KB

contribute.md

File metadata and controls

160 lines (105 loc) · 6.16 KB
Raw

Contributions

We welcome contributions in the form of issues and pull requests. We view the contributions and the process as the same for github and external contributors.Please note the runner typically requires changes across the entire system and we aim for issues in the runner to be entirely self contained and fixable here. Therefore, we will primarily handle bug issues opened in this repo and we kindly request you to create all feature and enhancement requests on the GitHub Feedback page.

IMPORTANT: Building your own runner is critical for the dev inner loop process when contributing changes. However, only runners built and distributed by GitHub (releases) are supported in production. Be aware that workflows and orchestrations run service side with the runner being a remote process to run steps. For that reason, the service can pull the runner forward so customizations can be lost.

Issues

Log issues for both bugs and enhancement requests. Logging issues are important for the open community.

Issues in this repository should be for the runner application. Note that the VM and virtual machine images (including the developer toolsets) installed on the actions hosted machine pools are located in this repository

Enhancements and Feature Requests

We ask that before significant effort is put into code changes, that we have agreement on taking the change before time is invested in code changes.

  1. Create a feature request. Once agreed we will take the enhancement
  2. Create an ADR to agree on the details of the change.

An ADR is an Architectural Decision Record. This allows consensus on the direction forward and also serves as a record of the change and motivation. Read more here

Required Dev Dependencies

Win *nix Git for Windows and Linux Install Here (needed for dev sh script)

*nix cURL Install here (needed for external sh script)

Win Visual Studio 2017 or newer Install here (needed for dev sh script)

Win-arm Visual Studio 2022 17.3 Preview or later. Install here

Quickstart: Run a job from a real repository

If you just want to get from building the sourcecode to using it to execute an action, you will need:

  • The url of your repository
  • A runner registration token. You can find it at https://github.com/{your-repo}/settings/actions/runners/new
git clone https://github.com/actions/runner
cd runner/src
./dev.(sh/cmd) layout # the runner that built from source is in {root}/_layout
cd ../_layout
./config.(sh/cmd) --url https://github.com/{your-repo} --token ABCABCABCABCABCABCABCABCABCAB # accept default name, labels and work folder
./run.(sh/cmd)

If you trigger a job now, you can see the runner execute it.

Tip: Make sure your job can run on this runner. The easiest way is to set runs-on: self-hosted in the workflow file.

Development Life Cycle

If you're using VS Code, you can follow these steps instead.

To Build, Test, Layout

Navigate to the src directory and run the following command:

Win dev {command}

*nix ./dev.sh {command}

Commands:

  • layout (l): Run first time to create a full runner layout in {root}/_layout
  • build (b): Build everything and update runner layout folder
  • test (t): Build runner binaries and run unit tests

Sample developer flow:

git clone https://github.com/actions/runner
cd runner
cd ./src
./dev.(sh/cmd) layout # the runner that built from source is in {root}/_layout
<make code changes>
./dev.(sh/cmd) build # {root}/_layout will get updated
./dev.(sh/cmd) test # run all unit tests before git commit/push

Let's break that down.

Clone repository:

git clone https://github.com/actions/runner
cd runner

If you want to push your changes to a remote, it is recommended you fork the repository and use that fork as your origin instead of https://github.com/actions/runner.

Build Layout:

This command will build all projects, then copies them and other dependencies into a folder called _layout. The binaries in this folder are then used for running, debugging the runner.

cd ./src # execute the script from this folder
./dev.(sh/cmd) layout # the runner that built from source is in {root}/_layout

If you make code changes after this point, use the argument build to build your code in the src folder to keep your _layout folder up to date.

cd ./src
./dev.(sh/cmd) build # {root}/_layout will get updated

Test Layout:

This command runs the suite of unit tests in the project

cd ./src
./dev.(sh/cmd) test # run all unit tests before git commit/push

Configure Runner:

If you want to manually test your runner and run actions from a real repository, you'll have to configure it before running it.

cd runner/_layout
./config.(sh/cmd) # configure your custom runner

You will need your the name of your repository and a runner registration token. Check Quickstart if you don't know how to get this token.

These can also be passed down as arguments to config.(sh/cmd):

cd runner/_layout
./config.(sh/cmd) --url https://github.com/{your-repo} --token ABCABCABCABCABCABCABCABCABCAB

Run Runner

All that's left to do is to start the runner:

cd runner/_layout
./run.(sh/cmd) # run your custom runner

View logs:

cd runner/_layout/_diag
ls
cat (Runner/Worker)_TIMESTAMP.log # view your log file

Editors

Using Visual Studio Code Using Visual Studio

Styling

We use the .NET Foundation and CoreCLR style guidelines located here