Updated readme for all the changes

README.md

@@ -28,21 +28,25 @@ In the event that you do *not* override these values, you will see a warning lik
 
 The reason this functionality is disabled by default is you may wish to utilize the `Resolver` syntax (described below) *without* overriding your default publication mechanism. In general, I wouldn't necessarily recommend this, since it means that your publication will not be self-contained within a single artifact realm, but that's a relatively common problem anyway these days so it's probably not a big deal.
 
+As a note on publication, *only* `publishMavenStyle := true` (the default) is supported. If you explicitly override this setting to `false`, the sbt-github-packages plugin will produce an error and refuse to load (unless `githubOwner` and/or `githubRepository` are undefined). The reason for this is to remove a bit of a foot-gun: GitHub Packages will silently allow you to publish Ivy-style packages, and will even show it within the UI, but will not allow you to *resolve* them.
+
 ### Resolvers
 
 If you're consuming packages that were published in the GitHub Package Registry, this plugin defines some convenience syntax for adding resolvers:
 
 ```sbt
-resolvers += Resolver.githubPackages("OWNER", "REPOSITORY")
+resolvers += Resolver.githubPackages("OWNER")
 ```
 
-This works for both public and private repositories, and you may add as many as desired, though if you use it with a private repository, you will also need to ensure that either `credentials` or `githubTokenSource` are appropriately configured.
+You may also *optionally* specify a repository as the second argument. **This is not required!** By default, sbt-github-packages will attempt to resolve from a repository named "_", which does not need to exist. If that repository *does* exist, and it is private, then the token used in authentication must have access to private repositories in that organization. In most cases, just the owner parameter will be sufficient.
+
+This resolver will give you access to packages published on *any* repository within the organization. If the token provided in the authentication information only has access to public repositories, then packages published on private repositories will report "not found". If the token has access to private repositories as well as public, then all packages will be visible.
 
-You will need to ensure that both `githubActor` and `githubTokenSource` are set to *your* details (i.e. the authentication information for the individual who ran `sbt`). A relatively common setup for this is to add the following to your `~/.gitconfig` file (replacing `USERNAME` with whatever your username is):
+You will need to ensure that both `githubActor` and `githubTokenSource` are set to *your* details (i.e. the authentication information for the individual who ran `sbt`). A relatively common setup for this is to use environment variables. For example, my `~/.profile` contains the following lines:
 
-```gitconfig
-[github]
-  actor = USERNAME
+```bash
+export GITHUB_ACTOR=djspiewak
+export GITHUB_TOKEN='<redacted>'
 ```
 
 Once this is configured, sbt-github-packages will automatically set your `githubActor` key to its value. That just leaves the `githubTokenSource`. The `TokenSource` ADT has the following possibilities:
@@ -60,7 +64,7 @@ object TokenSource {
 }
 ```
 
-Environment variables are a fairly good default. For example, I have a GitHub token for my laptop stored in the `GITHUB_TOKEN` environment variable. If you mirror this setup, you should configure `githubTokenSource` in the following way:
+As mentioned earlier, environment variables are a good default. For example, I have a GitHub token for my laptop stored in the `GITHUB_TOKEN` environment variable. If you mirror this setup, you should configure `githubTokenSource` in the following way:
 
 ```sbt
 githubTokenSource := TokenSource.Environment("GITHUB_TOKEN")
@@ -78,14 +82,11 @@ $ export GITHUB_TOKEN="abcdef12345cafebabe"   # <-- your token here (or your bui
 $ travis encrypt GITHUB_TOKEN=$GITHUB_TOKEN
 ```
 
-Then, in the `.travis.yml` file, you'll probably have the following (in addition to the `env.global` configuration that the `travis encrypt` command will prompt you to add):
+#### Token Permissions
 
-```yaml
-install:
-  - git config --global git.user USERNAME
-```
+GitHub Actions (and other instances of GitHub Apps) generate *different* tokens than those generated by the "Personal Access Tokens" section of your account settings. These tokens usually begin with `v1.`. They're weird because they are *not* associated with any particular user account. Thus, the value of `GITHUB_ACTOR` is irrelevant in such cases. It's entirely possible that `GITHUB_ACTOR` is irrelevant in *all* cases, but the API documentation claims otherwise. The API documentation claims many wrong things.
 
-If you are solely *depending upon* packages and not publishing, the token only needs the `read:packages` grant. If you are *publishing*, the token will need the `write:packages` grant. You can provision a new token under your GitHub account under the [Personal access tokens](https://github.com/settings/tokens) section of **Settings**.
+As an example, the documentation claims that, if you aren't publishing, your token only requires the `read: package` grant (and *not* `write: package`). Based on testing, as of right now, that appears to be false: `write: package` is required for *all* API calls against GitHub Packages, including resolution.
 
 #### Manual Configuration
 
@@ -104,20 +105,17 @@ Please, for the love of all that is holy, do not check this into your repository
 
 ### GitHub Actions
 
-Okay, so GitHub Actions is pretty much undocumented with respect to its interactions with GitHub Packages. Lovely. Some things I've learned through experimentation:
-
-- The automagical `${{ secrets.GITHUB_TOKEN }}`/`git config git.token` provided by GitHub Actions has access to packages in *other* public repositories, even when run from a pull request from a fork.
-- The automagical token is not a standard access token, but rather a *bearer token* for the GitHub Actions, uh, App. Confused yet? Among other things, it means that the username is irrelevant. You can leave it blank, or rely on some other default.
+Okay, so GitHub Actions is pretty much undocumented with respect to its interactions with GitHub Packages. Through experimentation though, we've learned some important things.
 
-The defaults for this plugin will work in GitHub Actions out of the box.
+The default token automagically-provided to all repositories works with GitHub Packages. So in other words, if you add `GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}` to your workflow's `env` section, things should work out just fine. The token in question is a JWT *bearer* token, not a conventional OAuth token, and so the `GITHUB_ACTOR` value is irrelevant *but must still be set*. Set `GITHUB_ACTOR` to any valid username.
 
 ### Keys
 
 The following setting keys are defined:
 
 - `githubOwner : String` Defines the organization or user name that owns the package registry to which this project will be published
 - `githubRepository : String` The repository which hosts this project under the organization/user defined in the other setting
-- `githubActor : String` (*defaults to `git config github.actor`*) *Your* GitHub username. This should almost never be specified in the build itself, but rather read from some external source. By default, it will read from the `git config` (by shelling out to the `git` command), but it's easy to override this to use an environment variable (e.g. `githubActor := sys.env("GITHUB_ACTOR")`). To be extremely clear, this is the user who ran the `sbt` command, it is not *necessarily* the repository owner!
-- `githubTokenSource : TokenSource` (*defaults to `GitConfig("github.token")`*) Where the plugin should go to read the GitHub API token to use in authentication. `TokenSource` has two possible values: `Environment(variable: String)` and `GitConfig(key: String)`. This is mostly just a convenience. You're free to do whatever you want. Just don't, like, put it in your build. 
+- `githubActor : String` (*defaults to `GITHUB_ACTOR`*) *Your* GitHub username. This should almost never be specified in the build itself, but rather read from some external source. By default, it will read the `GITHUB_ACTOR` environment variable. To be extremely clear, this is the user who ran the `sbt` command, it is not *necessarily* the repository owner!
+- `githubTokenSource : TokenSource` (*defaults to `Environment("GITHUB_TOKEN")`*) Where the plugin should go to read the GitHub API token to use in authentication. `TokenSource` has two possible values: `Environment(variable: String)` and `GitConfig(key: String)`. You can compose multiple sources together using `||`, which will result in each being attempted in order from left to right. This is mostly just a convenience. You're free to do whatever you want. Just don't, like, put it in your build. 
 
 `homepage` and `scmInfo` will be automatically set for you if `githubOwner` and `githubRepository` are themselves set.

build.sbt

@@ -16,7 +16,7 @@
 
 name := "sbt-github-packages"
 
-ThisBuild / baseVersion := "0.3"
+ThisBuild / baseVersion := "0.4"
 
 ThisBuild / organization := "com.codecommit"
 ThisBuild / publishGithubUser := "djspiewak"