Support organization-level runners

Author: tcardonne

README.md

@@ -10,7 +10,8 @@ For now, there is only a Debian Buster image, but I may add more variants in the
 
 ## Important notes
 
-GitHub [recommends](https://help.github.com/en/github/automating-your-workflow-with-github-actions/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories) that you do **NOT** use self-hosted runners with public repositories, for security reasons.
+* GitHub [recommends](https://help.github.com/en/github/automating-your-workflow-with-github-actions/about-self-hosted-runners#self-hosted-runner-security-with-public-repositories) that you do **NOT** use self-hosted runners with public repositories, for security reasons.
+* Organization level self-hosted runners are supported (see environment variables), but be advised that the GitHub API for organization level runners is still in public beta and subject to changes.
 
 ## Usage
 
@@ -49,6 +50,7 @@ services:
       environment:
         RUNNER_NAME: "my-runner"
         RUNNER_REPOSITORY_URL: ${RUNNER_REPOSITORY_URL}
+        #RUNNER_ORGANIZATION_URL: ${RUNNER_ORGANIZATION_URL}
         GITHUB_ACCESS_TOKEN: ${GITHUB_ACCESS_TOKEN}
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock
@@ -57,22 +59,33 @@ services:
 You can create a `.env` to provide environment variables when using docker-compose :
 ```
 RUNNER_REPOSITORY_URL=https://github.com/your_url/your_repo
+# or RUNNER_ORGANIZATION_URL=https://github.com/your-organization
 GITHUB_ACCESS_TOKEN=the_runner_token
 ```
 
 ## Environment variables
 
 The following environment variables allows you to control the configuration parameters.
 
-| Name | Description | Default value |
+| Name | Description | Required/Default value |
 |------|---------------|-------------|
-| RUNNER_REPOSITORY_URL | The runner will be linked to this repository URL | Required |
-| GITHUB_ACCESS_TOKEN | Personal Access Token created on [your settings page](https://github.com/settings/tokens) with `repo` scole. Used to dynamically fetch a new runner token (recommended). | Required if `RUNNER_TOKEN` is not provided.
+| RUNNER_REPOSITORY_URL | The runner will be linked to this repository URL | Required if `RUNNER_ORGANIZATION_URL` is not provided |
+| RUNNER_ORGANIZATION_URL | The runner will be linked to this organization URL. *(Self-hosted runners API for organizations is currently in public beta and subject to changes)* | Required if `RUNNER_REPOSITORY_URL` is not provided |
+| GITHUB_ACCESS_TOKEN | Personal Access Token. Used to dynamically fetch a new runner token (recommended, see below). | Required if `RUNNER_TOKEN` is not provided.
 | RUNNER_TOKEN | Runner token provided by GitHub in the Actions page. These tokens are valid for a short period. | Required if `GITHUB_ACCESS_TOKEN` is not provided
 | RUNNER_WORK_DIRECTORY | Runner's work directory | `"_work"`
 | RUNNER_NAME | Name of the runner displayed in the GitHub UI | Hostname of the container
 | RUNNER_REPLACE_EXISTING | `"true"` will replace existing runner with the same name, `"false"` will use a random name if there is conflict | `"true"`
 
+## Runner Token
+
+In order to link your runner to your repository/organization, you need to provide a token. There is two way of passing the token :
+
+* via `GITHUB_ACCESS_TOKEN` (recommended), containing a [Personnal Access Token](https://github.com/settings/tokens). This token will be used to dynamically fetch a new runner token, as runner tokens are valid for a short period of time.
+  * For a single-repository runner, your PAT should have `repo` scopes.
+  * For an organization runner, your PAT should have `admin:org` scopes.
+* via `RUNNER_TOKEN`. This token is displayed in the Actions settings page of your organization/repository, when opening the "Add Runner" page.
+
 ## Runner auto-update behavior
 
 The GitHub runner (the binary) will update itself when receiving a job, if a new release is available.

debian-buster/entrypoint.sh

@@ -19,8 +19,8 @@ if [[ -z $RUNNER_TOKEN && -z $GITHUB_ACCESS_TOKEN ]]; then
     exit 1
 fi
 
-if [[ -z $RUNNER_REPOSITORY_URL ]]; then
-    echo "Error : You need to set the RUNNER_REPOSITORY_URL environment variable."
+if [[ -z $RUNNER_REPOSITORY_URL && -z $RUNNER_ORGANIZATION_URL ]]; then
+    echo "Error : You need to set the RUNNER_REPOSITORY_URL (or RUNNER_ORGANIZATION_URL) environment variable."
     exit 1
 fi
 
@@ -36,23 +36,31 @@ fi
 if [[ -f ".runner" ]]; then
     echo "Runner already configured. Skipping config."
 else
+    if [[ ! -z $RUNNER_ORGANIZATION_URL ]]; then
+        SCOPE="orgs"
+        RUNNER_URL="${RUNNER_ORGANIZATION_URL}"
+    else
+        SCOPE="repos"
+        RUNNER_URL="${RUNNER_REPOSITORY_URL}"
+    fi
+
     if [[ -n $GITHUB_ACCESS_TOKEN ]]; then
-        echo "Exchanging the GitHub Access Token with a Runner Token..."
-        _PROTO="$(echo "${RUNNER_REPOSITORY_URL}" | grep :// | sed -e's,^\(.*://\).*,\1,g')"
-        _URL="$(echo "${RUNNER_REPOSITORY_URL/${_PROTO}/}")"
+
+        echo "Exchanging the GitHub Access Token with a Runner Token (scope: ${SCOPE})..."
+
+        _PROTO="$(echo "${RUNNER_URL}" | grep :// | sed -e's,^\(.*://\).*,\1,g')"
+        _URL="$(echo "${RUNNER_URL/${_PROTO}/}")"
         _PATH="$(echo "${_URL}" | grep / | cut -d/ -f2-)"
-        _ACCOUNT="$(echo "${_PATH}" | cut -d/ -f1)"
-        _REPO="$(echo "${_PATH}" | cut -d/ -f2)"
 
         RUNNER_TOKEN="$(curl -XPOST -fsSL \
             -H "Authorization: token ${GITHUB_ACCESS_TOKEN}" \
             -H "Accept: application/vnd.github.v3+json" \
-            "https://api.github.com/repos/${_ACCOUNT}/${_REPO}/actions/runners/registration-token" \
+            "https://api.github.com/${SCOPE}/${_PATH}/actions/runners/registration-token" \
             | jq -r '.token')"
     fi
 
     ./config.sh \
-        --url $RUNNER_REPOSITORY_URL \
+        --url $RUNNER_URL \
         --token $RUNNER_TOKEN \
         --name $RUNNER_NAME \
         --work $RUNNER_WORK_DIRECTORY \

docker-compose.yml

@@ -6,6 +6,7 @@ services:
       environment:
         RUNNER_NAME: "my-runner"
         RUNNER_REPOSITORY_URL: ${RUNNER_REPOSITORY_URL}
+        #RUNNER_ORGANIZATION_URL: ${RUNNER_ORGANIZATION_URL}
         GITHUB_ACCESS_TOKEN: ${GITHUB_ACCESS_TOKEN}
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock