{"id":21565806,"url":"https://github.com/hylandsoftware/trebuchet","last_synced_at":"2025-04-10T13:13:17.006Z","repository":{"id":57497930,"uuid":"194717448","full_name":"HylandSoftware/trebuchet","owner":"HylandSoftware","description":"Launch container images into Amazon ECR","archived":false,"fork":false,"pushed_at":"2023-05-03T15:09:26.000Z","size":76,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-24T11:56:54.357Z","etag":null,"topics":["aws","ci","cli","docker","ecr"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HylandSoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-01T17:41:38.000Z","updated_at":"2022-07-25T13:02:23.000Z","dependencies_parsed_at":"2024-06-20T11:57:51.764Z","dependency_job_id":"d5eb6f8b-ac0b-4891-a6df-92064a5660ad","html_url":"https://github.com/HylandSoftware/trebuchet","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HylandSoftware%2Ftrebuchet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HylandSoftware%2Ftrebuchet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HylandSoftware%2Ftrebuchet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HylandSoftware%2Ftrebuchet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HylandSoftware","download_url":"https://codeload.github.com/HylandSoftware/trebuchet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248225653,"owners_count":21068078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","ci","cli","docker","ecr"],"created_at":"2024-11-24T10:21:48.193Z","updated_at":"2025-04-10T13:13:16.246Z","avatar_url":"https://github.com/HylandSoftware.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trebuchet - Launch container images into Amazon ECR\n[![Build Status](https://travis-ci.org/HylandSoftware/trebuchet.svg?branch=master)](https://travis-ci.org/HylandSoftware/trebuchet) [![Coverage Status](https://coveralls.io/repos/github/HylandSoftware/trebuchet/badge.svg?branch=master)](https://coveralls.io/github/HylandSoftware/trebuchet?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/hylandsoftware/spot)](https://goreportcard.com/report/github.com/hylandsoftware/trebuchet)\n\n![](logo/trebuchet_200x200.png)\n\n----\n\nThe purpose of Trebuchet is to improve the quality of life for pushing Docker images to Amazon Elastic Container Registry (ECR).\n\n## Usage\n`Trebuchet` is shipped as a single binary (Linux/Windows) and as a Docker image. All images can be found [here](https://hub.docker.com/r/hylandsoftware/trebuchet).\n\n### Commands\n`push`:\n\n```\nPushes a Docker image into ECR\n\nRegion:\n        Region is required to be set as a flag, as an AWS environment variable (AWS_DEFAULT_REGION), or in the AWS config.\n\nProfile:\n        Profile may be set as a flag or an AWS environment variable. \n\nAmazon Resource Name (ARN):\n        Passing in a valid ARN allows trebuchet to assume a role to perform actions within AWS. A typical use-case for this\n        would be a service account to use in a software pipeline to push images to ECR.\n\nAliases:\n        trebuchet push can also be used as 'treb launch' or 'treb fling' for a more authentic experience.\n\nUsage:\n  treb push NAME[:TAG] [flags]\n\nAliases:\n  push, launch, fling\n\nExamples:\ntreb push -v --region us-east-1 helloworld:1.2.3\ntreb launch -v --as arn:aws:iam::112233445566:role/PushToECR --profile my-profile --region us-west-1 hello/world:3.4-beta\ntreb push helloworld:latest\n\nFlags:\n  -h, --help   help for push\n\nGlobal Flags:\n  -a, --as string       Amazon Resource Name (ARN) specifying the role to be assumed.\n  -p, --profile string  AWS named profile to use.\n  -r, --region string   AWS region to be used. Supported as flag, AWS_DEFAULT_REGION environment variable or AWS Config File.\n  -v, --verbose         Enables verbose logging.\n```\n\n`pull`:\n```\nPulls a Docker image from ECR\n\nStrip:\n\tStrip is a boolean flag. When set, it removes all ECR-specific elements from the image name. For example, \n\t112233445566.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest would be pulled as hello-world:latest.\n\nRegion:\n\tRegion is required to be set as a flag, as an AWS environment variable (AWS_DEFAULT_REGION), or in the AWS config.\n\nProfile:\n        Profile may be set as a flag or an AWS environment variable. \n\nAmazon Resource Name (ARN):\n\tPassing in a valid ARN allows trebuchet to assume a role to perform actions within AWS. A typical use-case for this\n\twould be a service account to use in a software pipeline to push images to ECR.\n\nUsage:\n  treb pull NAME[:TAG] [flags]\n\nExmaples:\ntreb pull -v --strip --region us-east-1 helloworld:1.2.3\ntreb pull -v -s --as arn:aws:iam::112233445566:role/PushToECR --profile my-profile --region us-west-1 hello/world:3.4-beta\ntreb pull helloworld:latest\n\nFlags:\n  -h, --help   help for repository\n  -s, --strip  strip the image name of ECR-specific elements\n\nGlobal Flags:\n  -a, --as string       Amazon Resource Name (ARN) specifying the role to be assumed.\n  -p, --profile string  AWS named profile to use.\n  -r, --region string   AWS region to be used. Supported as flag, AWS_DEFAULT_REGION environment variable or AWS Config File.\n  -v, --verbose         Enables verbose logging.\n```\n\n`repository`: \n```\nGet the full URL of a repository in Amazon ECR. The repository command will lookup the repository passed in\nto see if it exists in Amazon ECR and return it to be used for deployment or reference purposes.\n\nRegion:\n        Region is required to be set as a flag, as an AWS environment variable (AWS_DEFAULT_REGION), or in the AWS config.\n\nProfile:\n        Profile may be set as a flag or an AWS environment variable. \n\nAmazon Resource Name (ARN):\n        Passing in a valid ARN allows trebuchet to assume a role to perform actions within AWS. A typical use-case for this\n        would be a service account to use in a software pipeline to interact with ECR.\n\nUsage:\n  treb repository REPOSITORY [flags]\n\nAliases:\n  repository, repo\n\nExamples:\ntreb repository helloworld --region us-east-1\ntreb repo some/project/helloworld --region us-west-2 --profile my-profile --as arn:aws:iam::112233445566\ntreb repo my/repository\n\nFlags:\n  -h, --help   help for repository\n\nGlobal Flags:\n  -a, --as string       Amazon Resource Name (ARN) specifying the role to be assumed.\n  -p, --profile string  AWS named profile to use.\n  -r, --region string   AWS region to be used. Supported as flag, AWS_DEFAULT_REGION environment variable or AWS Config File.\n  -v, --verbose         Enables verbose logging.\n```\n\n### AWS Authentication and Settings Precedence\n`Trebuchet` uses the default AWS credentials chain and supports flags for specifying region and/or a role to assume.\nPrecedence of credentials and configuration that are loaded in `Trebuchet`:\n1. Flags passed to Trebuchet\n   - Example: `treb push --as arn:aws:iam::112233445566:role/JenkinsPushToECR --profile my-profile --region us-east-1 [some-image]`\n2. Environment variables. For more information, reference the [Environment Variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html)\n   section of the AWS Command Line documentation.\n   - Examples: `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` for authentication or `AWS_DEFAULT_REGION` to specify region\n3. AWS config/credentials files located at `~/.aws/config` and `~/.aws/credentials`.\nFor more information, reference the [Named Profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html)\nsection of the AWS Command Line documentation.\n    - Examples: `aws_access_key_id` and `aws_secret_access_key` in the credentials file or `region` and `role_arn` in the config file\n\n#### IAM Permissions\n\nThe User or IAM Role you are assuming needs at least the following permissions\nto create the repository if it doesn't exist and push images into ECR:\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"ecr:CreateRepository\",\n                \"ecr:BatchGetImage\",\n                \"ecr:CompleteLayerUpload\",\n                \"ecr:GetAuthorizationToken\",\n                \"ecr:DescribeRepositories\",\n                \"ecr:UploadLayerPart\",\n                \"ecr:InitiateLayerUpload\",\n                \"ecr:BatchCheckLayerAvailability\",\n                \"ecr:PutImage\",\n                \"ecr:GetDownloadUrlForLayer\"\n            ],\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\n### `Push` Command Usage in a Jenkins pipeline\nExample usage in Jenkins using the [kubenetes-plugin](https://github.com/jenkinsci/kubernetes-plugin)\n\n`build-spec.yml`:\n\n``` yml\nspec:\n  containers:\n  - name: jnlp\n    image: jenkins/jnlp-slave\n  - name: trebuchet\n    image: hylandsoftware/trebuchet\n    tty: true\n    securityContext:\n      privileged: true\n```\n\n\u003e **NOTE**: The trebuchet docker image uses a `docker:dind` daemon as its\n\u003e entrypoint. **You do not need to include a separate docker container in your\n\u003e jenkins build spec**. All tasks interacting with docker should execute inside\n\u003e the trebuchet container\n\n#### Using `WithCredentials` to provide AWS credentials\n`Jenkinsfile`:\n\n``` groovy\npipeline {\n    agent {\n        kubernetes {\n            label \"Push-To-ECR-Example\"\n            yamlFile 'build-spec.yml'\n        }\n    }\n\n    environment {\n        AWS_DEFAULT_REGION = 'us-east-1'\n    }\n\n    stages {\n        stage('Build Image') {\n            steps {\n                container('trebuchet') {\n                    sh 'docker build . -t hello-world:1.2.3'\n                }\n            }\n        }\n        stage('Push Docker Image to ECR') {\n            steps {\n                withCredentials([[$class: 'AmazonWebServicesCredentialsBinding', credentialsId: 'aws_credentials_id']) {\n                    container('trebuchet') {\n                        sh 'treb push hello-world:1.2.3 -v --as arn:aws:iam:1122334455:role/JenkinsPushToECR'\n                    }\n                }\n            }\n        }\n    }\n}\n```\n\n#### Using an AWS Credentials File\nIn this example, using an AWS credential file, we can use profiles from the file to set region, access keys, and roles to assume.\nIn the Jenkinsfile, we set [an AWS environment variable](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html): `AWS_SHARED_CREDENTIALS_FILE` to tell\nTrebuchet where to find the credentials file as it not in the default `~/.aws/credentials` location. We then use the `--profile` flag to specify the profile to use.\n\nCredentials file stored in Jenkins as a secret file with id `aws-credentials-file`:\n\n```\n[default-jenkins]\nregion = us-east-1\naws_access_key_id = ABCDEFGHIJKLMNOP\naws_secret_access_key = *******************\n\n[some-profile]\noutput = json\nregion = us-east-1\nrole_arn = arn:aws:iam::112233445566:role/JenkinsPushToECR\nsource_profile = default-jenkins\n```\n`Jenkinsfile`:\n\n```groovy\npipeline {\n    agent {\n        kubernetes {\n            label \"Push-To-ECR-Example\"\n            yamlFile 'build-spec.yml'\n        }\n    }\n\n    stages {\n        stage('Build Image') {\n            steps {\n                container('trebuchet') {\n                    sh 'docker build . -t hello-world:1.2.3'\n                }\n            }\n        }\n        stage('Push Docker Image to ECR') {\n            environment {\n                AWS_SHARED_CREDENTIALS_FILE = credentials('aws-credentials-file')\n            }\n        \n            steps {\n                container('trebuchet') {\n                    sh 'treb fling hello-world:1.2.3' --profile some-profile\n                }\n            }\n        }\n    }\n}\n```\n\n### `Repository` Command Usage in a Jenkins Pipeline\nThe `repository` command will return the full URL to a repository given as an argument to `trebuchet`. This allows\na pipeline to save this output as an environment variable and pass it to a deployment tool like [Helm](https://helm.sh/)\nto specify the location of an image to pull instead of hard-coding it in the Helm chart.\n\nHere's a shortened example of getting the full repository URL and upgrading a deployment via Helm and setting the \n`image.repository` to the environment variable created in the `Get Repository URL` stage.\n```groovy\npipeline {\n    agent {\n        ...\n    }\n    \n    stages {\n        // build...\n        \n        // trebuchet push...\n        \n        stage('Get Repository URL') {\n            container('trebuchet') {\n                script {\n                    REPOSITORY_URL = sh(returnStdout: true, script: 'treb repo hello-world --region us-east-1').trim()\n                }\n            }\n        }\n        \n        stage('Deploy') {\n            container('helm') {\n                sh '''\n                    helm upgrade hello-world deployments/helloworld --namespace helloworld --set image.repository=${REPOSITORY_URL}\n                '''\n            }\n        }\n    }\n}\n```\n\n\n## Building\nRequirements:\n- Go version `1.13+` or `vgo`, for Go Modules support\n\n``` bash\n# linux\ngo build -o treb -v main.go\n\n# windows\ngo build -o treb.exe -v main.go\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhylandsoftware%2Ftrebuchet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhylandsoftware%2Ftrebuchet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhylandsoftware%2Ftrebuchet/lists"}