Skip to content

6. deployment-environments.md

Latest commit

 

History

History
188 lines (157 loc) · 6.82 KB

6. deployment-environments.md

File metadata and controls

188 lines (157 loc) · 6.82 KB

Configuring environments

Note

This section can be applied to repos/<file>.yml or suborgs/<file>.yml. It will most commonly appear in the individual repos though.

Example environment definition

...
teams:
  # This team must be given explicit permission
  # before we can add them as a reviewer below
  - name: super-friends
    permission: write
collaborators:
  # This user must be given explicit permission
  # before we can add them as a reviewer below
  - username: KalEl
    permission: write
environments:
  - name: production
    wait_timer: 0
    prevent_self_review: true
    reviewers:
      - type: Team
        id: 1234647
      - type: User
        id: 139262123
    deployment_branch_policy:
      protected_branches: false
      custom_branch_policies:
        - names: ['main','dev']
          type: branch
        - names: ['v*.*.*']
          type: tag
    deployment_protection_rules:
      - app_id: 25112
    variables:
      - name: MY_AWESOME_VAR
        value: '845705'
      - name: my_lowercase_var
        value: I have spaces

Environment API Spec

Tip

GitHub's API documentation defines these inputs and types:

  1. Create or update an environment
  2. Create a deployment branch policy
  3. Create an environment variable

name string ${\text{\color{orange}Required}}$

This is the name of the environment, and will be what is referenced in a workflow with environment: <name>

 Example: 
environments:
  - name: dms-prod-example
...

wait_timer integer 

The amount of time to delay a job after the job is initially triggered. The time (in minutes) must be an integer between 0 and 43,200 (30 days).

 Example: 
environments:
  - name: dms-prod-example
    wait_timer: 30
...

prevent_self_review boolean 

Whether or not a user who created the job is prevented from approving their own job.

 Example: 
environments:
  - name: dms-prod-example
    prevent_self_review: true
...

reviewers array of objects or null ${\text{\color{orange}Required}}$ ${\text{\color{orange}if}}$ ${\text{\color{orange}prevent\_self\_review}}$ ${\text{\color{orange}is}}$ ${\text{\color{orange}true}}$

The people or teams that may review jobs that reference the environment. You can list up to six users or teams as reviewers. The reviewers must be given explicit access to the repository as either a team or collaborator. Only one of the required reviewers needs to approve the job for it to proceed.

Properties of reviewers

 type string 

  The type of reviewer.
  Can be one of: User, Team.

 id integer 

  The id of the user or team who can review the deployment

  Can be obtained by:
   Team: gh api /orgs/<org>/teams/<team-slug> | jq .id
   User: gh api /users/<username> | jq .id

 
environments:
  - name: production
    prevent_self_review: true
    reviewers:
      - type: Team
        id: 1234647
      - type: User
        id: 139262123
...

deployment_branch_policy object or null 

The type of deployment branch policy for this environment. To allow all branches to deploy, set to null.

Properties of deployment_branch_policy

 protected_branches boolean ${\text{\color{orange}Required}}$

  Whether only branches with branch protection rules can deploy
  to this environment. If protected_branches is true,
  custom_branch_policies must be false; if protected_branches
  is false, custom_branch_policies must be an object.

 custom_branch_policies boolean or object 

  Whether only branches that match the specified name patterns
  can deploy to this environment. If custom_branch_policies
  is false, protected_branches must be true; if
  custom_branch_policies is an object, protected_branches
  must be false.

 Example: 
environments:
  - name: production
    ...
    deployment_branch_policy:
      protected_branches: false
      custom_branch_policies:
        - names: ['main','dev']
          type: branch
        - names: ['v*.*.*']
          type: tag
...

variables array of objects 

Environment variables that can be referenced in a GitHub Actions workflow

Properties of variables

 name string ${\text{\color{orange}Required}}$

  The name of the variable.

 value string ${\text{\color{orange}Required}}$

  The value of the variable.

 Example: 
environments:
  - name: production
    variables:
      - name: MY_AWESOME_VAR
        value: super duper value
...