diff --git a/README.md b/README.md index a0feaa7..9416c68 100644 --- a/README.md +++ b/README.md @@ -1,103 +1,69 @@ # artifact-registry-cred-helper - -This CLI tool simplifies authentication with Google Cloud Artifact Registry. It manages your credentials stored in a .netrc file, allowing you to easily switch between different Artifact Registry repositories and authentication methods (OAuth 2.0 tokens and service account JSON keys). +This tool simplifies setting and managing credentials for accessing Google +Artifact Registry from various build tools and package managers, including +Maven, Python (pip), Go, and APT. Instead of relying on more complex solutions +like keyrings or individual tool-specific plugins (which introduce additional +dependencies), this tool uses the simple and widely-supported basic +authentication mechanism. This minimizes dependencies and simplifies +troubleshooting. ## Installation -This project is assumed to be installed via go install. Ensure you have Go installed and configured correctly. Then, navigate to the root directory of this project and run: - -``` -go install github.com/yolocs/artifact-registry-cred-helper/cmd@latest -``` - -This will install the artifact-registry-cred-helper command in your $GOPATH/bin directory (or your system's PATH if configured differently). You may need to add this directory to your PATH environment variable. - -## Usage - -The tool provides two main commands: `set-netrc` and `get`. - -### `set-netrc` +This tool is a single binary. Download it from [insert release link here]. For +example, you might download `artifact-registry-cred-helper_linux_amd64`. Place +the binary in a directory included in your `PATH` environment variable. -This command updates your .netrc file with credentials for specified Artifact Registry hosts. It supports both OAuth 2.0 tokens and service account JSON keys. +Or: -Syntax: - -``` -artifact-registry-cred-helper set-netrc [options] +```sh +go install github.com/yolocs/artifact-registry-cred-helper/cmd/artifact-registry-cred-helper@latest ``` -Options: +## How it Works -* `--hosts ,,...`: (Required unless --refresh is used) A comma-separated list of Artifact Registry hostnames (e.g., us-go.pkg.dev, eu-python.pkg.dev). Hostnames must end with .pkg.dev. -* `--json-key `: The path to your service account JSON key file. If omitted, the tool uses an OAuth 2.0 token. -* `--netrc `: The path to your .netrc file. Defaults to the standard system location. -* `--refresh`: Refreshes the credentials for existing Artifact Registry entries in your .netrc file. This option ignores the --hosts and --json-key flags. It only works with OAuth2. -* `--append`: Appends new entries to the .netrc file instead of overwriting existing Artifact Registry entries. +`artifact-registry-cred-helper` modifies your build tool or package manager's +configuration file to include the necessary authentication credentials for your +Artifact Registry repositories. It uses a straightforward approach: It adds or +updates the relevant credential sections within your configuration file (e.g., +`` entries in Maven's `settings.xml`). This keeps your credentials +separate from your source code, improving security. -Examples: +The tool currently supports (default credential files): -Using OAuth 2.0 token: +* **Maven:** Modifies `~/.m2/settings.xml` +* **Python (pip):** Modifies `~/.netrc` +* **Go:** Modifies `~/.netrc` +* **APT:** Modifies `/etc/apt/auth.conf.d/artifact-registry.conf` -``` -artifact-registry-cred-helper set-netrc --hosts=us-go.pkg.dev,eu-python.pkg.dev -``` +The tool supports two authentication methods supported by Artifact Registry: -Using a service account JSON key: +* **OAuth2 Access Token:** **RECOMMENDED**. Suitable for short-lived tokens. +* **JSON Key (base64 encoded):** For long-term access. -``` -artifact-registry-cred-helper set-netrc --hosts=us-central1.pkg.dev --json-key /path/to/your/key.json -``` - -Refreshing existing credentials: - -``` -artifact-registry-cred-helper set-netrc --refresh -``` +## Usage -Appending new hosts: +The tool itself provides detailed documentation. -``` -artifact-registry-cred-helper set-netrc --hosts=us-go.pkg.dev --append +```sh +artifact-registry-cred-helper -h ``` -### `get` +## For Local Developement -This command retrieves the credentials for a given host from your .netrc file. It's designed to be compatible with the Credential Helper Spec. +Always prefer short-lived tokens for authentication but it causes trouble for +local dev loop. The tool provides an option to refresh the credential in the +background until your `gcloud` is logged out. For example: -Syntax: - -``` -artifact-registry-cred-helper get [options] +```sh +artifact-registry-cred-helper set-netrc \ + --repo-urls=us-go.pkg.dev/my-project/repo1,us-python.pkg.dev/my-project/repo2 \ + --background-refresh-interval=5m & ``` -Options: - -* `--hosts ,,...`: A comma-separated list of Artifact Registry hostnames. You can only use this OR stdin. -* **stdin**: A JSON payload with a "uri" field specifying the host. This is the preferred method for compatibility with the Credential Helper Spec. - -Examples: - -Using the --hosts flag: - -``` -artifact-registry-cred-helper get --hosts=us-go.pkg.dev -``` - -Using stdin (Credential Helper Spec compliant): - -``` -echo '{"uri": "us-go.pkg.dev"}' | artifact-registry-cred-helper get -``` - -The output will be a JSON object containing the authorization header to be used when interacting with the specified Artifact Registry host. - -## Environment Variables +This command would run the tool in the background and refresh the credential +every 5 minutes in the `.netrc` file. -The following environment variables can be used to override command-line options: +## For CI/CD -* `AR_CRED_HELPER_HOSTS`: Overrides the `--hosts` flag. -* `AR_CRED_HELPER_JSON_KE`: Overrides the `--json-key` flag. -* `AR_CRED_HELPER_NETRC`: Overrides the `--netrc` flag. -* `AR_CRED_HELPER_REFRESH_ONLY`: Overrides the `--refresh` flag. -* `AR_CRED_HELPER_APPEND_ONLY`: Overrides the `--append` flag. +Coming soon. diff --git a/pkg/apt/auth_config.go b/pkg/apt/auth_config.go index 9d6dfd3..dd1643c 100644 --- a/pkg/apt/auth_config.go +++ b/pkg/apt/auth_config.go @@ -8,7 +8,7 @@ import ( ) const ( - configDir = "/etc/apt/apt.conf.d" + configDir = "/etc/apt/auth.conf.d" ) // AuthConfig represents a apt auth config file. diff --git a/pkg/commands/set_apt.go b/pkg/commands/set_apt.go index b494f52..36e47ae 100644 --- a/pkg/commands/set_apt.go +++ b/pkg/commands/set_apt.go @@ -19,7 +19,7 @@ type SetAptCommand struct { } func (c *SetAptCommand) Desc() string { - return "Set the credential in /etc/apt/apt.conf.d for the given repos." + return "Set the credential in /etc/apt/auth.conf.d for the given repos." } func (c *SetAptCommand) Help() string { @@ -28,10 +28,10 @@ Usage: {{ COMMAND }} [options] This command MUST be run in 'sudo -E' mode. -Set the credential in /etc/apt/apt.conf.d for the given repos. +Set the credential in /etc/apt/auth.conf.d for the given repos. All Artifact Registry credentials will be removed from the auth config before setting the new hosts. - # Example: Set the credential in the default path /etc/apt/apt.conf.d/artifact-registry.conf + # Example: Set the credential in the default path /etc/apt/auth.conf.d/artifact-registry.conf artifact-registry-cred-helper set-apt --repo-urls us-apt.pkg.dev/my-project/repo1 # Example: Override the default auth config path. @@ -46,7 +46,7 @@ func (c *SetAptCommand) Flags() *cli.FlagSet { sec := set.NewSection("APT OPTIONS") sec.StringVar(&cli.StringVar{ Name: "config-name", - Usage: "The name of the config file under /etc/apt/apt.conf.d", + Usage: "The name of the config file under /etc/apt/auth.conf.d", Target: &c.configName, EnvVar: "AR_CRED_HELPER_APT_AUTH_CONFIG", Default: "artifact-registry.conf",