Merge pull request #23 from DeterminateSystems/readme

README: organize "Running GitHub Actions CI" instructions into own section

.editorconfig

@@ -0,0 +1,15 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+
+[*.{yml,yaml}]
+indent_size = 2

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+##### Description
+
+<!---
+Please include a short description of what your PR does and / or the motivation
+behind it
+--->
+
+##### Checklist
+
+- [ ] Tested functionality against a test repository (see ["How to test changes"](../README.md#how-to-test-changes))
+- [ ] Added or updated relevant documentation (leave unchecked if not applicable)

.github/workflows/validate.yml

@@ -0,0 +1,20 @@
+name: CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Validate YAML
+        uses: nwisbeta/validate-yaml-schema@v1.0.3
+        with:
+          yamlSchemasJson: |
+            {
+              "https://json.schemastore.org/github-action.json": ["action.yml"]
+            }

README.md

@@ -13,7 +13,7 @@ name: update-flake-lock
 on:
   workflow_dispatch: # allows manual triggering
   schedule:
-    - cron: '0 0 * * *' # runs daily at 00:00
+    - cron: '0 0 * * 0' # runs weekly on Sunday at 00:00
 
 jobs:
   lockfile:
@@ -22,14 +22,90 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v2
       - name: Install Nix
-        uses: cachix/install-nix-action@v14
+        uses: cachix/install-nix-action@v16
         with:
-          install_url: https://nixos-nix-install-tests.cachix.org/serve/vij683ly7sl95nnhb67bdjjfabclr85m/install
-          install_options: '--tarball-url-prefix https://nixos-nix-install-tests.cachix.org/serve'
           extra_nix_config: |
-            experimental-features = nix-command flakes
             access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
       - name: Update flake.lock
-        uses: DeterminateSystems/update-flake-lock@v3
+        uses: DeterminateSystems/update-flake-lock@vX
 ```
 
+## Example updating specific input(s)
+
+> **NOTE**: If any inputs have a stale reference (e.g. the lockfile thinks a git input wants its "ref" to be "nixos-unstable", but the flake.nix specifies "nixos-unstable-small"), they will also be updated. At this time, there is no known workaround.
+
+It is also possible to update specific inputs by specifying them in a space-separated list:
+
+```yaml
+name: update-flake-lock
+on:
+  workflow_dispatch: # allows manual triggering
+  schedule:
+    - cron: '0 0 * * 0' # runs weekly on Sunday at 00:00
+
+jobs:
+  lockfile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Install Nix
+        uses: cachix/install-nix-action@v16
+        with:
+          extra_nix_config: |
+            access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
+      - name: Update flake.lock
+        uses: DeterminateSystems/update-flake-lock@vX
+        with:
+          inputs: input1 input2 input3
+```
+
+## Running GitHub Actions CI
+
+GitHub Actions will not run workflows when a branch is pushed by or a PR is opened by a GitHub Action. There are two ways to have GitHub Actions CI run on a PR submitted by this action.
+
+### Without a Personal Authentication Token
+
+Without using a Personal Authentication Token, you can manually run the following to kick off a CI run:
+
+```
+git branch -D update_flake_lock_action
+git fetch origin
+git checkout update_flake_lock_action
+git commit --amend --no-edit
+git push origin update_flake_lock_action --force
+```
+
+### With a Personal Authentication Token
+
+By providing a Personal Authentication Token, the PR will be submitted in a way that bypasses this limitation (GitHub will essentially think it is the owner of the PAT submitting the PR, and not an Action).
+You can create a token by visiting https://github.com/settings/tokens and select at least the `repo` scope. Then, store this token in your repository secrets (i.e. 'https://github.com/<USER>/<REPO>/settings/secrets/actions') as `GH_TOKEN_FOR_UPDATES` and set up your workflow file like the following:
+
+```yaml
+name: update-flake-lock
+on:
+  workflow_dispatch: # allows manual triggering
+  schedule:
+    - cron: '0 0 * * 1,4' # Run twice a week
+
+jobs:
+  lockfile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - name: Install Nix
+        uses: cachix/install-nix-action@v16
+      - name: Update flake.lock
+        uses: DeterminateSystems/update-flake-lock@vX
+        with:
+          token: ${{ secrets.GH_TOKEN_FOR_UPDATES }}
+```
+
+## Contributing
+
+Feel free to send a PR or open an issue if you find something functions unexpectedly! Please make sure to test your changes and update any related documentation before submitting your PR.
+
+### How to test changes
+
+In order to more easily test your changes to this action, we have created a template repository that should point you in the right direction: https://github.com/DeterminateSystems/update-flake-lock-test-template. Please see the README in that repository for instructions on testing your changes.

action.yml

@@ -1,9 +1,27 @@
 name: 'Update flake.lock'
 description: 'Update your flake.lock and send a PR'
+inputs:
+  inputs:
+    description: 'A space-separated list of inputs to update. Leave empty to update all inputs.'
+    required: false
+    default: ''
+  token:
+    description: 'GITHUB_TOKEN or a `repo` scoped Personal Access Token (PAT)'
+    required: false
+    default: ${{ github.token }}
 runs:
   using: "composite"
   steps:
-    - run: nix flake update --commit-lock-file
+    - run: |
+        if [[ -n '${{ inputs.inputs }}' ]]; then
+          inputs=()
+          for input in ${{ inputs.inputs }}; do
+            inputs+=("--update-input" "$input")
+          done
+          nix flake lock "${inputs[@]}" --commit-lock-file
+        else
+          nix flake update --commit-lock-file
+        fi
       shell: bash
       env:
         GIT_AUTHOR_NAME: github-actions[bot]
@@ -24,9 +42,24 @@ runs:
         branch: update_flake_lock_action
         delete-branch: true
         title: "flake.lock: Update"
+        token: ${{ inputs.token }}
         body: |
           Automated changes by the [update-flake-lock](https://github.com/DeterminateSystems/update-flake-lock) GitHub Action.
 
           ```
           ${{ steps.commit_message.outputs.msg }}
           ```
+
+          ### Running GitHub Actions on this PR
+
+          GitHub Actions will not run workflows on pull requests which are opened by a GitHub Action.
+
+          To run GitHub Actions workflows on this PR, run:
+
+          ```sh
+          git branch -D update_flake_lock_action
+          git fetch origin
+          git checkout update_flake_lock_action
+          git commit --amend --no-edit
+          git push origin update_flake_lock_action --force
+          ```

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1638263381,
+        "narHash": "sha256-1rZDxTw74ETuJEjwPfpMgY0sfx8Cv1tRNt3gibol574=",
+        "owner": "nixos",
+        "repo": "nixpkgs",
+        "rev": "7b031d0d99e8cdaf0b70457c0cb33f16c0c958bb",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nixos",
+        "ref": "nixos-unstable-small",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,30 @@
+{
+  description = "update-flake-lock";
+
+  inputs.nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+
+  outputs =
+    { self
+    , nixpkgs
+    }:
+    let
+      nameValuePair = name: value: { inherit name value; };
+      genAttrs = names: f: builtins.listToAttrs (map (n: nameValuePair n (f n)) names);
+
+      allSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+      forAllSystems = f: genAttrs allSystems
+        (system: f {
+          inherit system;
+          pkgs = import nixpkgs { inherit system; };
+        });
+    in
+    {
+      devShell = forAllSystems
+        ({ system, pkgs, ... }:
+          pkgs.stdenv.mkDerivation {
+            name = "update-flake-lock-devshell";
+            buildInputs = [ pkgs.shellcheck ];
+            src = self;
+          });
+    };
+}

shell.nix

@@ -0,0 +1,6 @@
+(import
+  (fetchTarball {
+    url = "https://github.com/edolstra/flake-compat/archive/99f1c2157fba4bfe6211a321fd0ee43199025dbf.tar.gz";
+    sha256 = "0x2jn3vrawwv9xp15674wjz9pixwjyj3j771izayl962zziivbx2";
+  })
+  { src = ./.; }).shellNix