{"id":22878798,"url":"https://github.com/major0/gh-ecs-runner","last_synced_at":"2025-05-07T00:24:50.295Z","repository":{"id":41133818,"uuid":"485775941","full_name":"major0/gh-ecs-runner","owner":"major0","description":"Ephemeral GitHub ECS Runner","archived":false,"fork":false,"pushed_at":"2024-05-01T20:45:32.000Z","size":8,"stargazers_count":7,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-13T13:16:28.150Z","etag":null,"topics":["aws","ecs","github-runner","runner"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/major0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-04-26T12:26:59.000Z","updated_at":"2024-05-23T18:15:50.000Z","dependencies_parsed_at":"2024-05-01T20:49:59.226Z","dependency_job_id":"abce7491-c3ff-49c5-875b-dd2e9e47dac2","html_url":"https://github.com/major0/gh-ecs-runner","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/major0%2Fgh-ecs-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/major0%2Fgh-ecs-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/major0%2Fgh-ecs-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/major0%2Fgh-ecs-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/major0","download_url":"https://codeload.github.com/major0/gh-ecs-runner/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252789575,"owners_count":21804461,"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","ecs","github-runner","runner"],"created_at":"2024-12-13T16:31:39.453Z","updated_at":"2025-05-07T00:24:50.113Z","avatar_url":"https://github.com/major0.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"Dockerized GitHub Runner\n========================\n\nDeploy ephemeral/one-shot containerized [GitHub Runner][]s which can be\nleveraged from a [GitHub Workflow][].  This allows dynamic deployment of\n[GitHub Runner][]s which have access to your deployment environment w/out the\nneed to install dedicated agents into your network.  This is useful for\nperforming such actions as running automated testing from [GitHub][] against\nprivate infrastructure, database migration scripts, infrastructure deploys,\netc.\n\nHow it Works\n------------\n\nThe basics idea is that we are deploying a pre-existing container image which\nalready has the [GitHub Runner][] installed.  The container startup script\nsimply facilitates the automatic registration of the runner as an\nephemeral/one-shot agent.\n\nAs part of startup the base image performs the following actions:\n\n1. Lookup the appropriate `\u003corganization\u003e/\u003crepository\u003e` registration URL based\n   on `env` variables.\n2. Register itself with [GitHub][] as an _ephemeral_ [GitHub Runner][].\n3. [GitHub Runner][] begins polling the currently running [GitHub Workflow][]\n   looking for work.\n4. Once all work in the workflow is done, [GitHub][] will inform the runner\n   that there is nothing left to do and that the runner can terminate.\n5. The [GitHub Runner][] will automatically de-register itself.\n\nRequirements\n------------\n\nThere are a few dependancies that must be setup in the target environment\nbefore this can be made to really work.\n\n1. [Personal Access Token][GitHub PAT] with the appropriate permissions.\n2. An existing container image in a container registry accessible to the target\n   environment.  E.g. [Docker Hub][], [AWS ECR][], etc.\n3. Necessary access credentials for launching a container w/in the target\n   environment.  E.g. [AWS Access Keys][AWS Security].\n4. An existing job/task definition w/in the target environment.  I.e. for\n   [AWS][] there should be an existing [ECS Task][] definition which the\n   workflow can launch.\n\n_note: While it is technically possible to allow the workflow to define a\njob/task to launch on its own, this would allow a workflow to launch arbitrary\napplications into the target w/ little-to-no constraints._\n\n\nExample\n-------\n\nA simple example on launching the runner:\n\n```\njobs:\n  runner:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n      repository-projects: write\n    outputs:\n      id: ${{ steps.runner.outputs.runner_id }}\n      arn: ${{ steps.runner.outputs.task_arn }}\n      ipaddr: ${{ steps.runner.outputs.ipaddr }}\n    steps:\n\n    # Can leverage GitHub OIDC to AWS\n    # See: https://github.com/aws-actions/configure-aws-credentials\n    - id: credentials\n      name: Configure AWS credentials\n      uses: aws-actions/configure-aws-credentials@v1\n      with:\n        role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}\n\trole-session-name: MyDeploymentWorkflow\n        aws-region: us-west-2\n\n    - id: runner\n      uses: major0/gh-ecs-runner@master\n      with:\n        name: techops-runner\n        subnets-tag: placement:ecs\n        token: ${{ secrets.runner-token }}\n        labels: dev\n\n  do-stuff:\n    needs: runner\n    runs-on: [\"self-hosted\", \"Linux\", \"X64\", \"ephemeral\", \"dev\", \"${{ needs.runner.outputs.id }}\"]\n    permissions:\n      id-token: write\n      repository-projects: read\n    steps:\n\n    # See: https://github.com/actions/checkout\n    - uses: actions/checkout@v3\n      with:\n        ssh-key: ${{ secrets.ssh-key }}\n\n    # (optional) switch to different AWS credentials\n    - id: credentials\n      name: Configure AWS credentials\n      uses: aws-actions/configure-aws-credentials@v1\n      with:\n        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n\n    - id: my-stuff\n      run: |\n        # This runs in AWS on the GitHub Runner\n\techo \"Hello World\"\n```\n\nSee: [action.yaml](action.yaml) for input paramters.\n\n[//]: # (Begin Common Mark document references)\n\n[AWS]: https://aws.amazon.com/\n[AWS ECS]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html\n[AWS ECR]: https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html\n[AWS Security]: https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html\n[Docker Hub]: https://hub.docker.com/\n[ECS Task]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html\n[ECS Service]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html\n[GitHub]: https://www.github.com/\n[GitHub Runner]: https://docs.github.com/en/actions/hosting-your-own-runners\n[GitHub Workflow]: https://docs.github.com/en/get-started/getting-started-with-git/git-workflows\n[GitHub PAT]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajor0%2Fgh-ecs-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmajor0%2Fgh-ecs-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajor0%2Fgh-ecs-runner/lists"}